Metadata-Version: 2.1
Name: stardust-canopen-tools
Version: 0.1.0
Summary: Stardust CANopen tools: SDO read/write & register config CLI over SocketCAN
Home-page: UNKNOWN
License: Proprietary
Platform: UNKNOWN
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# stardust-canopen-tools

Stardust CANopen 工具(Python), 通过 SocketCAN 读写驱动器(CANopen)参数。
可打包为 Debian 包: **python3-stardust-canopen-tools**(二进制包
`python3-stardust-canopen-tools`, 见 `debian/`)。

## 内容

| 模块 | 说明 |
|---|---|
| `stardust_canopen_tools.canopen_sdo` | SDO 公共库: `SdoClient`、帧封装、hex/dec/ascii 编码、abort 解释 |
| `stardust_canopen_tools.canopen_sdo_tool` | 控制台: 按 index/sub 直接 SDO 读写(console: `canopen-sdo-tool`) |
| `stardust_canopen_tools.canopen_reg_tool` | 控制台: 按设备配置/寄存器名称读写(console: `canopen-reg-tool`) |
| `stardust_canopen_tools/configs/*.yaml` | 每设备一份寄存器配置(随包安装) |

## 本地运行(不安装)

```bash
# 从 canopen_tools/ 目录以包方式运行
cd canopen_tools
# sdo 工具(直接按 index/sub 读写)。默认接口 can0; 本地 vcan 联调需显式 -d vcan0
python3 -m stardust_canopen_tools.canopen_sdo_tool read \
    -d vcan0 -n 1 -i 0x100C -s 0

# reg 工具(按配置/寄存器名读写)。只有一台设备时可省略 -d/--dev,
# 寄存器名可直接作位置参数或 -r/--reg; 提供标准短参数:
#   -d 设备  -r 寄存器  -c 大类  -n 节点  -i 接口  -l 长度
python3 -m stardust_canopen_tools.canopen_reg_tool list-devices
python3 -m stardust_canopen_tools.canopen_reg_tool list -c guarding
python3 -m stardust_canopen_tools.canopen_reg_tool info -r guard_time
python3 -m stardust_canopen_tools.canopen_reg_tool read -r guard_time
python3 -m stardust_canopen_tools.canopen_reg_tool write guard_time 100
# 本地 vcan 联调: 默认走 can0(真实硬件), 测试请加 -i vcan0
python3 -m stardust_canopen_tools.canopen_reg_tool read guard_time -i vcan0
# 写入可强制字节长度(1/2/4), 默认按寄存器类型转换:
python3 -m stardust_canopen_tools.canopen_reg_tool write target_speed 1000 -l 4
```

> 直接以文件方式运行亦可(模块内做了双 import 兼容):
> `python3 stardust_canopen_tools/canopen_reg_tool.py list-devices`

## 安装(开发)

```bash
cd canopen_tools
pip install .            # 安装 python 包 + console scripts(canopen-sdo-tool / canopen-reg-tool)
canopen-reg-tool list-devices
```

## Shell tab 补全(可选)

依赖 `argcomplete`(随包安装;源码运行需 `pip install argcomplete`)。安装后启用:

```bash
register-python-argcomplete canopen-reg-tool canopen-sdo-tool
# 或写入 bashrc 每次登录生效:
#   echo 'eval "$(register-python-argcomplete canopen-reg-tool canopen-sdo-tool)"' >> ~/.bashrc
```

- 自动补全: 子命令与选项;`--dev` 补设备名,`--cat` 补大类,
  `info/read/write` 的寄存器名(位置参数或 `--reg`)实时按设备配置补全。
- 注册在**已安装的 console 脚本**上生效;若习惯 `python3 -m ...` 运行,
  可先 `pip install .`(或 `pip install -e .`)再用 console 脚本。

## 打 Debian 包

需 `debhelper / dh-python`。在 `canopen_tools/` 下:

```bash
dpkg-buildpackage -us -uc -b
# 产物: ../python3-stardust-canopen-tools_0.1.0-1_all.deb
```

- 二进制包名: `python3-stardust-canopen-tools`(见 `debian/control`, 采用 Debian
  `python3-*` 惯例, dh_python3 会自动填充 `${python3:Depends}`);
- 运行时依赖 `python3-yaml`(`${python3:Depends}` 自动推导)。

## 设备配置文件

`stardust_canopen_tools/configs/<device>.yaml`, 字段见仓库文档
`docs/features/register_tool.md`。可通过 `--config-dir` 或环境变量
`CANOPEN_CONFIGS` 指向其它配置目录。

## 验证

- 可用仓库内测试工具 `test_tools/sim_drive/mock_drive.py`(vcan)联调;
- 示例:
  ```
  python3 ../test_tools/sim_drive/mock_drive.py --dev vcan0 \
      --nodes 1,2,4,3 --guard-nodes 1,2,4,3
  canopen-reg-tool read --dev kinco --cat guarding --node 1
  ```


