# python-jyutils

**Repository Path**: yuhaoth/python-jyutils

## Basic Information

- **Project Name**: python-jyutils
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-25
- **Last Updated**: 2026-05-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


# 介绍

本工具包含以下模块：

| 模块                 | 说明                                      |
|----------------------|-------------------------------------------|
| `stdio_proxy`        | CAN/串口 TCP 代理服务端                    |
| `markdown2docx`      | Markdown 转 Word 文档                      |
| `misc.xmodem`        | XMODEM 文件传输协议实现                    |
| `misc.logging`       | 统一日志封装（YAML 配置）                  |

---

# 目录结构

```
python/jyutils/
├── __init__.py
├── .stdio_proxy.config.yaml          # proxy 配置文件（默认）
├── stdio_proxy/                      # TCP 代理服务端
│   ├── __init__.py
│   ├── proxy.py                      # 核心代理逻辑
│   ├── config.py                     # 配置加载与合并
│   ├── device.py                     # 设备基类
│   ├── can_device.py                 # SocketCAN / VirtualCAN
│   ├── serial_device.py              # 串口设备
│   ├── socket_device.py              # TCP socket 中继
│   ├── zlg_device.py                 # ZLG USBCAN-II
│   └── usbcanfd_device.py            # ZLG USBCANFD-100U Mini
├── misc/                             # 工具模块
│   ├── tcp_client.py                 # TCP 客户端
│   ├── xmodem.py                     # XMODEM 协议
│   ├── logging.py                    # 日志封装
│   └── .logging.config.yaml          # 日志配置
└── markdown2docx/                    # Markdown 转 Word
    ├── __init__.py
    └── md2docx_template.docx
```

---

# 安装

```bash
pip install .
```

---

# stdio_proxy

将 CAN / 串口 / ZLG USBCAN-II / USBCANFD 数据通过 TCP 转发给多个客户端，支持级联中继。

## 配置文件

配置文件为 `.stdio_proxy.config.yaml`，按以下顺序搜索并合并：

1. 环境变量 `JYUTILS_CONFIG` 指定的路径（若存在）
2. `$PWD/.stdio_proxy.config.yaml`
3. `$HOME/.stdio_proxy.config.yaml`
4. `<jyutils 包目录>/.stdio_proxy.config.yaml`

合并规则：全局键（`inout_port`、`readonly_port`、`default_interface`）后定义覆盖先定义；接口定义先定义优先（同名不覆盖）。

```yaml
# TCP 读写端口（客户端可收发）
inout_port: 12345
# TCP 只读端口（客户端只能接收）
readonly_port: 12346
# 缺省接口（未指定 --interface 时使用）
default_interface: can0

# SocketCAN 物理接口
can0:
    device_type: can
    device: can0
    baudrate: 1000000

# Virtual CAN 接口（无需硬件，适合开发/测试）
vcan0:
    device_type: virtual_can
    device: vcan0
    baudrate: 500000

# ZLG USBCAN-II 接口（Windows only，需要 zlgcan 驱动和 python-can-zlg 包）
zlg0:
    device_type: zlg_usbcan2
    device: 0          # 设备 index
    baudrate: 500000
    channel: 0         # CAN 通道号（0 或 1）

# ZLG USBCANFD-100U Mini 接口（Windows only，支持 CANFD）
zlgfd0:
    device_type: zlg_usbcanfd
    device: 0              # 设备 index
    baudrate: 500000       # 仲裁域波特率（CAN 波特率）
    data_baudrate: 2000000 # 可选 – 数据域波特率（CANFD）
    channel: 0             # CAN 通道号（0 或 1）

# 串口接口
serial:
    device_type: serial
    device: COM3
    baudrate: 115200

# Socket 客户端（连接另一个 proxy，实现级联/中继）
socket_relay:
    device_type: socket
    device: 127.0.0.1:9999   # host:port 格式
    baudrate: 0
```

## 支持的设备类型

| device_type    | 说明                              |
|----------------|-----------------------------------|
| `can`          | SocketCAN 物理接口                 |
| `virtual_can`  | python-can VirtualBus（虚拟）      |
| `zlg_usbcan2`  | ZLG USBCAN-II / USBCAN-I 设备     |
| `zlg_usbcanfd` | ZLG USBCANFD-100U Mini（支持 CANFD）|
| `serial`       | 串口（RS232/RS485）               |
| `socket`       | TCP socket 客户端（级联/中继）     |

## 运行代理

```bash
# 使用缺省接口
stdio-proxy

# 指定接口
stdio-proxy --interface can0
stdio-proxy --interface vcan0
stdio-proxy --interface zlg0
stdio-proxy --interface zlgfd0
stdio-proxy --interface serial
stdio-proxy --interface socket_relay

# 指定配置文件
stdio-proxy -c /path/to/.stdio_proxy.config.yaml --interface can0
```

## TCP 客户端

```bash
# 读写端口（可收发数据）
tcp-client --host 127.0.0.1 --port 12345

# 只读端口（只能接收数据）
tcp-client --host 127.0.0.1 --port 12346

# 按 Ctrl+C 退出
```

---

# markdown2docx

将 Markdown 文件（含 PlantUML 图表）转换为 Word 文档（`.docx`）。

依赖：`pandoc`、`plantuml`（需在 PATH 中）。

```bash
# 基本用法
md2docx input.md output.docx

# PlantUML 过滤（pandoc filter）
plantuml-filter
```

`md2docx` 内部调用 `pandoc`，使用 `md2docx_template.docx` 作为样式模板，并自动引用 `plantuml-filter` 渲染文档中的 PlantUML 代码块。

可通过环境变量 `PLANTUML_BIN` 指定 PlantUML 可执行文件路径（默认 `plantuml`）。

---

# 日志配置

日志通过 `.logging.config.yaml` 配置，按以下顺序搜索并**合并**（后定义的覆盖先定义，嵌套 dict 深度合并）：

1. `<jyutils/misc 包目录>/.logging.config.yaml`（最低优先级）
2. `$HOME/.logging.config.yaml`
3. `$PWD/.logging.config.yaml`
4. 环境变量 `JYUTILS_LOGGING_CONFIG` 指定的路径（最高优先级）

```yaml
version: 1
formatters:
  default:
    format: "%(asctime)s  %(levelname)-7s  %(name)s  %(filename)s:%(lineno)d  %(message)s"
handlers:
  console:
    class: logging.StreamHandler
    stream: ext://sys.stdout
    formatter: default
loggers:
  jyutils.stdio_proxy.proxy:
    level: INFO
    handlers: [console]
    propagate: false
  jyutils.stdio_proxy.can_device:
    level: INFO
    handlers: [console]
    propagate: false
  jyutils.stdio_proxy.serial_device:
    level: INFO
    handlers: [console]
    propagate: false
  jyutils.stdio_proxy.socket_device:
    level: INFO
    handlers: [console]
    propagate: false
  jyutils.stdio_proxy.zlg_device:
    level: INFO
    handlers: [console]
    propagate: false
  jyutils.stdio_proxy.usbcanfd_device:
    level: INFO
    handlers: [console]
    propagate: false
  jyutils.stdio_proxy.config:
    level: INFO
    handlers: [console]
    propagate: false
  jyutils.misc.tcp_client:
    level: INFO
    handlers: [console]
    propagate: false
  jyutils.misc.xmodem:
    level: INFO
    handlers: [console]
    propagate: false
  jyutils.misc.logging:
    level: INFO
    handlers: [console]
    propagate: false
  jyutils.markdown2docx:
    level: INFO
    handlers: [console]
    propagate: false
root:
  level: DEBUG
  handlers: [console]
```