opman CLI 使用文档
文档对应 @zenovate/opman 0.1.10。请用
opman --version确认本机版本。完整参数以opman <command> --help为准。
opman 是面向 OP 设备的命令行工具：将 Python 编译为 PikaPython 字节码（.py.o），经串口或 BLE 上传与部署，并提供 Python REPL 与 BLE 扫描。
工具选型以及用 OP Manager 做现场分发，见 OP-BTS Python 脚本使用规范与工具指引。
目录
平台支持
| 平台 | 支持情况 |
|---|---|
| macOS（arm64 / x64） | 支持 |
| Windows x64 | 支持 |
| Linux | 不支持（npm 包未提供 Linux 二进制） |
| Windows ARM（原生） | 未声明支持；请使用 Windows x64 |
安装
前置条件： 已安装 Node.js ≥ 16（含 npm）。
全局安装：
npm install -g @zenovate/opman
opman --version
项目本地安装：
npm install -D @zenovate/opman
npx opman --help
下文示例使用全局安装后的 opman 命令；若为项目本地安装，请加上 npx 前缀。
快速上手
将 COM3 换成你的串口（Windows）或 macOS 上的 /dev/cu.*。许多光电头工装使用 9600 波特率；若省略 -b，opman 的默认波特率为 115200。
# 1）本地编译 .py → .py.o（无需连接设备）
opman compile hello.py
# 2a）仅上传（不运行）
opman upload hello.py.o /py -p COM3 -b 9600
# 2b）或一步完成：编译 + 上传 + 运行
opman deploy hello.py -p COM3 -b 9600
# 可选：进入设备上的 Python REPL
opman python -p COM3 -b 9600
BLE（在 macOS 上建议减小 --packet-size）：
opman ble-scan --name OP
opman deploy hello.py --ble ZENO --packet-size 50
设备上的脚本必须放在 /py 目录。
命令参考
需要连设备的命令：必须指定 -p（串口） 或 --ble（BLE） 之一，二者互斥。
compile
在本地将 .py 编译为 .py.o（无需设备）。
opman compile hello.py
opman compile *.py -o build/
opman compile hello.py -o build/hello.py.o
| Flag | 默认值 | 说明 |
|---|---|---|
-o / --output |
与各输入同目录 | 输出 .py.o 文件或目录 |
upload
将本地文件上传到设备目录（不会自动运行脚本）。
opman upload hello.py.o /py -p COM3 -b 9600
opman upload hello.py.o /py --ble AA:BB:CC:DD:EE:FF --packet-size 50
| Flag | 默认值 | 说明 |
|---|---|---|
-p / --port |
— | 串口名（如 COM3、/dev/cu.usbserial-xxx） |
--ble |
— | BLE 地址或名称（部分匹配） |
-b / --baud |
115200 |
串口波特率（指定 -c 时忽略） |
-c / --serial-config |
— | 完整串口参数，如 9600,N,8,1 |
--remote-name |
本地文件名 | 设备上的文件名 |
--packet-size |
100 |
上传分片大小（字节） |
--skip-command-mode |
关 | 上传前跳过进入命令模式 |
deploy
若输入为 .py 则先编译，再上传到设备（默认 /py），然后执行 PythonFileRun。若只需传输，请用 upload。
| 输入 | 行为 |
|---|---|
.py |
编译 → 上传 → 运行 |
.py.o / *.o |
跳过编译；上传 → 运行 |
opman deploy hello.py -p COM3 -b 9600
opman deploy hello.py.o -p COM3 -b 9600
opman deploy hello.py -p COM3 -b 9600 --monitor
opman deploy hello.py --ble ZENO --packet-size 50 --monitor
| Flag | 默认值 | 说明 |
|---|---|---|
--remote-dir |
/py |
设备目录 |
-o / --output |
与输入同目录 | 编译 .py 时的本地 .py.o 路径 |
--remote-name |
由输入推导 | 设备上的文件名（用于运行） |
--monitor |
关 | 运行成功后打印原始输出，直到按 ESC |
--run-timeout |
30 |
等待 PythonFileRun 响应的秒数 |
--hex / --timestamp |
关 | 监视显示选项 |
--packet-size |
100 |
上传分片大小（字节） |
-p / --ble / -b / -c |
— | 与 upload 相同 |
shell
交互式命令模式（读写设备参数 / JSON 命令）。提示符：>。
opman shell -p COM3 -b 9600
opman shell --ble ZENO
| Flag | 默认值 | 说明 |
|---|---|---|
--timeout |
5 |
单条命令响应超时（秒） |
--skip-command-mode |
关 | 跳过进入命令模式 |
python
设备上的交互式 Python REPL。提示符：>>>。opman 会自动进入 Python 模式。
opman python -p COM3 -b 9600
opman python --ble ZENO
在设备端输入 exit() 离开 REPL；本地输入 quit 仅断开连接。
| Flag | 默认值 | 说明 |
|---|---|---|
--timeout |
30 |
每行 Python 超时（秒） |
--skip-python-mode |
关 | 设备已在 REPL |
--no-legacy-fallback |
关 | 不在旧固件路径上回退 |
ble-scan
扫描 BLE 设备（无需串口）。
opman ble-scan
opman ble-scan --name OP
opman ble-scan --all-devices
| Flag | 默认值 | 说明 |
|---|---|---|
--name |
— | 按名称子串过滤（不区分大小写） |
--all-devices |
关 | 不过滤名称关键字 |
--timeout |
15 |
扫描时长（秒） |
monitor
打印串口或 BLE 原始数据。按 ESC（或 Ctrl+C）结束。
opman monitor -p COM3
opman monitor -p COM3 --hex --timestamp -o capture.log
opman monitor --ble ZENO --hex
| Flag | 默认值 | 说明 |
|---|---|---|
--hex / --timestamp |
关 | 显示选项 |
--no-drain |
关 | 连接后不清空串口缓冲（仅串口） |
-o / --output |
— | 同时写入文件 |
completion
生成 Shell 自动补全脚本（bash / zsh / fish / powershell）。
opman completion bash
opman completion zsh
opman completion fish
opman completion powershell
当前会话示例：
| Shell | 命令 |
|---|---|
| Bash | source <(opman completion bash) |
| Zsh | source <(opman completion zsh) |
| Fish | opman completion fish | source |
| PowerShell | opman completion powershell | Out-String | Invoke-Expression |
串口名与 BLE 设备不会自动补全；请自行指定 -p 或 --ble。
连接要点
串口
- 同一时刻只能有一个程序占用串口（请先关闭其他串口工具）。
- Windows 光电头工装常见 COM3 @ 9600 8N1——请传
-b 9600（opman 默认波特率为 115200）。 - macOS 路径形如
/dev/cu.usbserial-…（对外通信优先用cu.*，而非tty.*）。 - 完整参数：
-c "9600,N,8,1"（校验N/E/O，数据位7/8，停止位1/2）。
BLE
- macOS 首次使用需在「系统设置 → 隐私与安全性 → 蓝牙」中允许终端访问蓝牙。
--ble可填地址/UUID，也可填名称（部分匹配；扫描约 15 秒后连接第一个匹配设备）。- 建议先用
opman ble-scan；勿与 OP Manager 同时占用同一连接。 - macOS + BLE 上传： 默认
--packet-size为100。若出现FileWrite timed out repeatedly，请改用--packet-size 50（仍不稳定可试30）。串口上传通常无需调整。
常见问题
如何确认设备串口号？
- Windows： 设备管理器 → 端口（COM 和 LPT），查看
COMx。 - macOS： 插入适配器后执行
ls /dev/cu.*，选择对应的cu.usbserial-…（或类似名称）。
opman 没有列出串口的子命令。
macOS BLE 上传报 FileWrite timed out
请减小分片，例如：
opman upload hello.py.o /py --ble ZENO --packet-size 50
npm 安装失败 / 我在用 Linux
- 确认 Node.js ≥ 16，且系统为 macOS 或 Windows x64。
- 已发布的 npm 包不支持 Linux。本站不提供 Linux 上的受支持安装途径。
deploy 与 upload 有什么区别？
upload：只传输文件。deploy：必要时编译.py，上传后在设备上运行脚本（PythonFileRun）。
脚本必须放在设备哪个目录？
必须放在 /py。其他目录下的脚本无法正常运行。
Windows 串口驱动或权限问题
请从技术支持页面的驱动下载区安装与你的工装/适配器匹配的 USB 转串口驱动（如 CH34x / FTDI）。确保终端有权限访问该 COM 口，并关闭其他占用该口的程序。