@zenovate/opman

CLI for OP devices: compile Python to PikaPython bytecode (.py.o), upload over serial or BLE, with command mode and Python REPL.

• Platforms: macOS (arm64 / x64), Windows x64
• npm: @zenovate/opman

Install

npm install -g @zenovate/opman

Project-local:

npm install -D @zenovate/opman
npx opman --help

Commands

| Task | Command | |------|---------| | Version | opman --version | | Compile .py | opman compile hello.py / opman compile *.py -o build/ | | Upload file | opman upload hello.py.o /py -p COM3 -b 9600 | | Compile + upload + run | opman deploy hello.py -p COM3 -b 9600 | | Upload + run .py.o / .o | opman deploy hello.py.o -p COM3 -b 9600 | | Command mode / params | opman shell -p COM3 -b 9600 | | Python REPL | opman python -p COM3 -b 9600 | | BLE scan | opman ble-scan [--name OP] [--all-devices] | | Raw monitor | opman monitor -p COM3 | | Shell completion | opman completion bash / zsh / fish / powershell |

opman python enters Python REPL automatically — you do not need to switch device modes manually.

deploy — compile, upload, and run

deploy accepts source or precompiled bytecode, uploads to the device (default directory /py), then runs {"PythonFileRun":"<filename>"}. Use upload if you only want to transfer without running.

Input types

| Input | Behavior | |-------|----------| | .py | Compile to .py.o locally, then upload and run | | .py.o | Skip compile; upload and run | | .o (any path ending in .o) | Same as .py.o — treated as bytecode |

Flow: compile (if .py) → connect → upload → PythonFileRun → (optional) raw monitor until ESC.

# Serial: compile, upload, run (remote dir defaults to /py)
opman deploy examples/hello.py -p COM3 -b 9600

# Upload precompiled bytecode (skip compile)
opman deploy examples/hello.py.o -p COM3 -b 9600
opman deploy build/hello.o -p COM3 -b 9600

# Custom local compile output, remote name, timeout
opman deploy examples/hello.py -p COM3 -o build/hello.py.o \
  --remote-name demo.py.o --run-timeout 60

# Custom remote directory
opman deploy examples/hello.py --remote-dir /py -p COM3 -b 9600

# Upload tuning
opman deploy examples/hello.py.o -p COM3 --packet-size 200 --skip-command-mode

# BLE by address or name (partial match); on macOS use --packet-size 50
opman deploy examples/hello.py --ble ZENO --packet-size 50 --monitor

# Monitor with hex + timestamp (press ESC to stop)
opman deploy examples/hello.py -p COM3 --monitor --hex --timestamp

| Flag | Default | Description | |------|---------|-------------| | --remote-dir | /py | Device directory to upload to | | -o / --output | same dir as input | Local .py.o path when compiling .py | | --remote-name | derived from input | Filename on device (used for PythonFileRun) | | --monitor | off | After run succeeds, print raw device output until ESC | | --run-timeout | 30 | Seconds to wait for PythonFileRun response | | --hex | off | Hex display during --monitor | | --timestamp | off | Timestamp prefix during --monitor | | -p / --ble | — | Serial port, or BLE address / name (one required) | | -b / -c | 115200 | Serial baud or full config, e.g. 9600,N,8,1 | | --packet-size | 100 | Upload chunk size (bytes) | | --skip-command-mode | off | Skip command mode before upload |

upload

opman upload hello.py.o /py -p COM3 -b 9600
opman upload hello.py.o /py -p COM3 --remote-name custom.py.o
opman upload hello.py.o /py -p COM3 --packet-size 200 --skip-command-mode

macOS + BLE: Default --packet-size is 100 bytes. On macOS over BLE, uploads may fail with FileWrite timed out repeatedly. Use a smaller chunk size, e.g. --packet-size 50 (or 30 if still unstable). Serial uploads usually do not need this.

opman upload hello.py.o /py --ble AA:BB:CC:DD:EE:FF --packet-size 50

monitor

opman monitor -p COM3
opman monitor -p COM3 --hex --timestamp -o capture.log
opman monitor -p COM3 --no-drain          # serial only: keep pre-connect buffer
opman monitor --ble ZENO --hex -o ble.log

| Flag | Default | Description | |------|---------|-------------| | --hex | off | Hex display | | --timestamp | off | Timestamp prefix per chunk | | --no-drain | off | Do not drain serial buffer after connect (serial only) | | -o / --output | — | Also write to file |

Press ESC (or Ctrl+C) to stop.

python

opman python -p COM3 -b 9600
opman python -p COM3 --timeout 60
opman python -p COM3 --skip-python-mode      # device already in REPL
opman python -p COM3 --no-legacy-fallback    # do not fall back on old firmware path
opman python --ble ZENO

Device: exit() to leave REPL. Local: quit disconnects only.

Examples

Compile

opman compile examples/hello.py
opman compile examples/*.py
opman compile examples/*.py -o build/
opman compile examples/hello.py -o /tmp/custom.py.o

Serial (Windows)

opman deploy examples/hello.py -p COM3 -b 9600
opman deploy examples/hello.py.o -p COM3 -b 9600
opman deploy examples/hello.py -p COM3 -b 9600 --monitor
opman shell -p COM3 -b 9600
opman shell -p COM3 --skip-command-mode
opman python -p COM3 -b 9600
opman monitor -p COM3

Serial config string (-c, same as 9600,N,8,1)

opman shell -p COM5 -c "9600,N,8,1"

BLE

opman ble-scan
opman ble-scan --name OP
opman ble-scan --all-devices
opman deploy examples/hello.py --ble AA:BB:CC:DD:EE:FF --packet-size 50
opman deploy examples/hello.py.o --ble ZENO --packet-size 50
opman deploy examples/hello.py --ble ZENO --monitor --hex --packet-size 50
opman upload examples/hello.py.o /py --ble ZENO --packet-size 50
opman python --ble ZENO
opman monitor --ble ZENO --hex --timestamp

On macOS, prefer --packet-size 50 (or 30) for BLE upload/deploy; see upload.

Full parameter reference (Chinese): docs/操作说明.md

Shell completion

Provided by the Go binary (npm global install or bin/opman). Tab-complete subcommands, flags, and local file paths.

opman completion --help

Current session

| Shell | Command | |-------|---------| | Bash | source <(opman completion bash) | | Zsh | source <(opman completion zsh) | | Fish | opman completion fish \| source | | PowerShell | opman completion powershell \| Out-String \| Invoke-Expression |

Persist across sessions

# Bash (Linux)
opman completion bash > /etc/bash_completion.d/opman

# Bash (macOS, Homebrew)
opman completion bash > $(brew --prefix)/etc/bash_completion.d/opman

# Zsh (macOS, Homebrew)
opman completion zsh > $(brew --prefix)/share/zsh/site-functions/_opman

# Fish
opman completion fish > ~/.config/fish/completions/opman.fish

PowerShell: add the “current session” command to your profile ($PROFILE).

# Smaller completion script (no flag descriptions)
opman completion bash --no-descriptions > /tmp/opman-completion.bash
source /tmp/opman-completion.bash

Serial ports and BLE devices are not auto-suggested; connection flags -p / --ble are prioritized until one is set.

Help

opman --help
opman <command> --help
opman deploy --help