13.3.1.1. openmv 命令行工具（CLI）

安装该软件包会添加一个 openmv 可执行文件，它会打开一个通过 USB 连接到摄像头的 pygame 查看器。如果在串口之后不传入任何参数，它会运行一个内置的小型测试脚本，将生成的帧缓冲区流式传回，并将其按比例缩放显示，同时叠加显示当前帧率:

openmv --port /dev/ttyACM0

端口路径取决于主机平台。在 Linux 上，USB CDC 为 /dev/ttyACMx，USB 转 UART 桥接为 /dev/ttyUSBx。在 macOS 上为 /dev/tty.usbmodem... 或 /dev/cu.usbmodem...。在 Windows 上为 COMx。

该查看器是确认软件包已安装、摄像头可访问以及协议正常工作的最快方式。它在脚本开发期间也是一个实用的演示工具——用 --script 把内置测试脚本替换为任何 MicroPython 文件，无需离开终端即可观察结果。

在终端中按 Esc、Ctrl+C，或关闭查看器窗口，都会干净地退出。

13.3.1.1.1. 运行自定义脚本

--script 让 CLI 指向磁盘上的某个 MicroPython 源文件。该文件会被上传到摄像头，替代内置测试脚本执行，它产生的任何帧都会流式传回查看器:

openmv --port /dev/ttyACM0 --script my_script.py

脚本打印到 stdout 的任何内容都会实时镜像到主机终端。传入 --quiet 可抑制此输出，或传入 --debug 以获得详细的协议日志。

13.3.1.1.2. 预览自定义通道

--channel NAME 会轮询由运行中的摄像头端脚本注册的自定义数据通道，并将每次更新的前十个字节打印到终端:

openmv --port /dev/ttyACM0 --channel ticks

在未提供 --script 时运行的内置测试脚本会注册一个 ticks 通道，返回摄像头的毫秒级运行时间，因此 --channel ticks 演示了 自定义通道 中详细介绍的双向通道接口——而无需你在主机或摄像头上自己编写任何代码。

13.3.1.1.3. 基准测试模式

--bench 会将标准测试脚本替换为 JPEG 压缩吞吐量基准测试:

openmv --port /dev/ttyACM0 --bench

摄像头捕获一帧 RGB565 QVGA 图像，将其压缩为 JPEG，然后在紧凑循环中反复刷出同一个压缩缓冲区。查看器报告的是原始 USB 数据速率，而非实时解码的帧，因此屏幕上的数字是该链路与该主机能够维持的上限。这对于在不改变实际捕获内容（从而避免引入变数）的情况下比较不同摄像头或主机非常有用。

13.3.1.1.4. 性能分析

CLI 可以在流式传输的帧上叠加实时分析器数据。该叠加层仅在摄像头运行带有 profile 通道注册的 PROFILE_ENABLE=1 固件版本时才有用；在标准固件上，分析控制项不起作用。

  • --firmware PATH —— 加载摄像头正在运行的固件 ELF，以便叠加层能将分析记录中的函数地址解析为人类可读的名称。如果不提供，叠加层将显示原始地址。

查看器中的三个键盘快捷键用于驱动分析器：

按键

操作

P

循环切换分析器叠加层：关闭、性能、事件。

M

在 inclusive（包含）和 exclusive（独占）之间切换分析器模式。包含计时会把被调用者的时间计入调用者；独占计时则不会。

R

重置分析器计数器。

13.3.1.1.5. 协议调优标志

下面的标志对应 openmv.Camera 上的构造函数参数。默认值适用于所有出厂的摄像头；只有在调试自定义固件版本或模拟不利链路条件时才覆盖它们。

  • --baudrate N —— 默认为 921600（用于将 USB 切换到 OpenMV 协议的特殊值）。仅在 UART 链路上覆盖此值。

  • --timeout SEC —— 每次操作的超时时间（秒）（默认 1.0）。

  • --max-retry N —— 在判定链路损坏之前的重试次数（默认 3）。

  • --max-payload N —— 最大有效载荷大小（字节）（默认 4096）。如果摄像头无法处理这么大，会协商降低。

  • --crc BOOL —— 对每个数据包启用 CRC 校验（默认 true）。

  • --seq BOOL —— 启用序列号校验（默认 true）。

  • --ack BOOL —— 启用逐包确认（默认 true）。

  • --events BOOL —— 启用来自摄像头的事件通知（默认 true）。

  • --drop-rate FLOAT —— [0.0, 1.0] 范围内的丢包模拟率（默认 0.0）。仅用于测试。

一个 CLI 专用的调优旋钮：

  • --poll MS —— 查看器主循环的轮询速率，单位毫秒（默认 4）。

13.3.1.1.6. 其他标志

两个标志可在不改变摄像头端行为的情况下调整查看器呈现流的方式：

  • --scale N —— 显示缩放系数（默认 4）。当 QVGA 帧在 4K 显示器上太小而难以看清时很有用。

  • --raw —— 请求摄像头发送未压缩的像素缓冲区，而不是 JPEG 压缩的缓冲区。这在没有硬件 JPEG 支持的摄像头上很有用；流式传输帧 介绍了其中的权衡。

13.3.1.1.7. 查看器在做什么

CLI 本身就是一个 openmv.Camera 程序。它建立连接，调用 stop() 清除任何正在运行的脚本，用 exec() 上传脚本，用 streaming() 启用流式传输，然后循环调用 read_frame()（更新显示）、read_stdout()（镜像脚本的打印输出）和 read_status()（监视其他所有已注册通道的活动）。其源代码位于 cli.py，是一个端到端驱动摄像头的应用程序的可用参考实现。