云端模型再强,若不能使用这台机器上的输入和输出,它就只是一个缩小了的聊天窗口。把外设设计成工具时,要同时考虑分辨率、型号差异和电气限制。

键盘与屏幕:适合短命令,不适合长报告

46 键矩阵键盘由 TCA8418 经 I2C 连接(地址 0x34)。官方操作说明详细写了 sym / shift / fn 的按住、单击、双击锁定,以及组合键。方向键在不少界面是 fn + F/X/Z/C。对 agent 界面来说,这意味着:输入要短,菜单要浅,回复要能在 320 × 170 的 ST7789v3 屏幕上分段滚动。ZClaw 正是按这个尺寸做的键盘优先聊天界面。自己做终端界面时,也应默认「一屏只有几行字」。

官方 CLI 终端在需要看宽输出时提供 Viewport 模式(fn + 6)。如果 agent 把整段 JSON 或长日志直接打到屏幕上,会几乎不可读。更好的做法是:模型先在云端总结,设备只显示结论和需要确认的工具调用。

相机:先确认你的型号有镜头

标准版与 v1.0 内置 IMX219 CSI 4-Lane 800 万像素摄像头(3280 × 2464)。Lite 没有内置摄像头。官方 Camera 应用可以使用内置摄像头或受支持的 USB 摄像头,并明确写了 Lite 无内置摄像头。预览受屏幕尺寸限制,无法呈现照片的全部细节。

把相机做成工具时,稳妥的流程是:

  1. 用官方 Camera 应用,或你在当前镜像里实际找到的拍摄命令,把照片写到已知目录;
  2. 再让支持视觉的云端模型去读这张已经拍好的照片(注意带宽和费用);
  3. 不要假设某个未经核对的 rpicam-* 命令一定预装在官方镜像里。先在设备上用 which 或软件列表确认。

需要「看一眼再行动」的 agent,在 Lite 上必须外接摄像头,或放弃该工具。

麦克风、扬声器与红外

机身有 MEMS 麦克风、ES8389 编解码、AW8737A + 1W @ 8Ω 扬声器,以及 3.5 mm TRRS。官方有 Rec 录音和 Music 播放应用。语音输入可以作为云端语音识别的前端,但要考虑 2.4 GHz 网络的上行带宽和电池消耗。不要在未测试延迟和功耗前,就把「全程语音 agent」写成已经验证的方案。

红外发射与接收可用于官方 IR Remote,以及 IR Chat(每条消息最多 7 个可打印 ASCII 字符)。把红外做成工具前,先理解它适合短控制码,不是通用数据通道。

传感器因型号而异

IMU BMI270 出现在标准版与 v1.0 上,Lite 没有。众筹版 CardputerZero 的官方对照还列有 BMM150 磁力计;v1.0 与 Lite 没有。官方 Compass 应用在 Lite 上不可用。RTC 为 RX8130CE,I2C 地址 0x32。

读取 I2C 设备需要相应的用户权限,以及发行版中的工具或库(例如 i2c-tools,或 Python 的 smbus 绑定)。这些软件是否预装,以你设备上的镜像为准。未安装时,先确认包名再使用 apt,不要在脚本里假装它们已经存在。

GPIO、Grove 与 Cap

扩展包括:

  • HY2.0-4P:可在 I2C / UART 之间切换,默认 UART;5V 输出最大电流小于 500 mA。官方说明:右侧 Grove 与顶部 EXT 的 5V 默认关闭,需在 Settings > ExtPort 中开启。
  • EXT 2.54-14P:SPI、UART、I2C、USB 与 GPIO。标有 D+* / D-* 的引脚默认为 GPIO,可切换为 USB。

官方强调:Cap 系列模块不支持热插拔,插拔前必须关机。官方操作说明还写明,GPS / LoRa 需要 Cap LoRa-1262,NFC 与 SubG Chat 需要 Cap CC1101。这些模块可以作为 agent 的「定位」「发一条短无线消息」「读标签」工具,但应当先在官方应用里验证模块工作,再写入你自己的白名单。

5V 输出小于 500 mA,不能给耗电很大的外设供电。设计工具时要把电流预算写进去。

终端本身就是工具

对现场调试来说,最有用的工具往往不是传感器,而是受约束的命令:查看 IP、内存、磁盘、进程,或运行你预先写好的检查脚本。上一篇的 tiny_cloud_agent.py 展示了如何把命令限制在白名单里。扩大白名单时,应避免 shell=True,避免把模型输出直接拼进命令行。

电源、网络与热设计会限制工具频率

待机功耗 2.5W、1750 mAh 电池,意味着高频拍照、持续 Wi-Fi 上传或让 CPU 长时间满载,都会很快耗尽电量。只有 2.4 GHz 的无线和 10/100M USB 以太网,也会限制上传大图的体验。把「每秒拍一张并送到云端做视觉推理」写成默认行为,并不符合这台机器的约束。更合理的策略是:按需采集、本地先缩小或摘录、再发送,并且在电池模式下降低频率。

A strong cloud model is still only a shrunken chat window if it cannot use this machine’s inputs and outputs. When you turn peripherals into tools, design for the screen, the exact model you have, and the electrical limits.

Keyboard and display: short commands, not long reports

The 46-key matrix keyboard is connected through a TCA8418 over I2C (address 0x34). Official usage documentation describes how sym, shift, and fn work when held, tapped, or double-tapped to lock, plus the function combinations. In many screens the arrows are fn + F/X/Z/C. For an agent UI that means short input, shallow menus, and replies that can scroll in sections on a 320 × 170 ST7789v3 panel. ZClaw is already a keyboard-first chat UI built for that size. If you write your own terminal UI, assume only a few lines fit on screen.

The official CLI terminal offers a Viewport mode (fn + 6) when output is wider than the panel. Dumping raw JSON or a long log onto the display is almost unreadable. A better split is: summarize in the cloud, and show only the conclusion plus any tool call that needs confirmation.

Camera: confirm that your model has one

The standard model and v1.0 include an IMX219 CSI 4-lane 8MP camera (3280 × 2464). Lite has no built-in camera. The official Camera app can use the built-in camera or a supported USB camera, and it states explicitly that Lite has no built-in camera. Preview is limited by the screen and may not show every detail in a photo.

A cautious way to expose the camera as a tool is:

  1. capture into a known directory with the official Camera app, or with a capture command you have actually found on the current image;
  2. send that already-captured file to a cloud vision model (watch bandwidth and cost);
  3. do not assume that an unchecked rpicam-* binary is preinstalled. Confirm it with which or the image’s package list.

An agent that must “look, then act” needs an external camera on Lite, or that tool should be omitted.

Microphone, speaker, and infrared

The hardware includes a MEMS microphone, an ES8389 codec, an AW8737A amplifier with a 1W @ 8Ω speaker, and a 3.5 mm TRRS jack. Official apps include Rec and Music. Speech can be a front end to cloud speech recognition, but 2.4 GHz uplink bandwidth and battery draw matter. Do not describe an always-on voice agent as a verified design before those costs are measured.

Infrared transmit and receive are used by the official IR Remote app and by IR Chat (at most seven printable ASCII characters per message). Treat IR as a short control-code tool, not a general-purpose data channel.

Sensors differ by model

The BMI270 IMU is present on the standard model and v1.0, and absent on Lite. The official comparison also lists a BMM150 magnetometer on the Kickstarter CardputerZero, but not on v1.0 or Lite. The official Compass app is not supported on Lite. The RTC is an RX8130CE at I2C address 0x32.

Reading I2C devices requires the right permissions and whatever tools or libraries your image actually provides (for example i2c-tools, or a Python smbus binding). Do not assume they are preinstalled. If you need to install a package with apt, confirm the package name on the device first.

GPIO, Grove, and Cap modules

Expansion includes:

  • HY2.0-4P, switchable between I2C and UART, UART by default, with 5V output limited to less than 500 mA. Official documentation says 5V on the right-hand Grove port and the top EXT header is off by default and is enabled under Settings > ExtPort.
  • EXT 2.54-14P, with SPI, UART, I2C, USB, and GPIO. Pins marked D+* / D-* default to GPIO and can be switched to USB.

Official documentation is explicit: Cap modules do not support hot-plugging; shut the device down before inserting or removing one. The usage guide also states that GPS / LoRa need a Cap LoRa-1262, and that NFC and SubG Chat need a Cap CC1101. Those modules can become tools for a fix, a short radio message, or a tag read, but verify them in the official apps before adding them to your own allowlist.

The 5V budget under 500 mA cannot power a hungry accessory. Write the current budget into the tool design.

The terminal is already a tool

For field debugging, the most useful tools are often not sensors but constrained commands: inspect addresses, memory, disks, and processes, or run a script you wrote beforehand. The tiny_cloud_agent.py example in the previous article shows how to keep commands on an allowlist. When you widen that list, avoid shell=True and never interpolate model output directly into a command line.

Power, network, and heat limit how often tools should run

A 2.5W idle figure and a 1750 mAh battery mean that frequent photos, continuous Wi-Fi uploads, or a CPU held at full load will drain the pack quickly. 2.4 GHz-only radio and 10/100M USB Ethernet also limit how comfortably you can upload large images. “Capture one frame every second and send it to a cloud vision model” is a poor default for this hardware. A better policy is: capture on demand, shrink or excerpt locally, then send, and lower the rate on battery power.