推荐:用 M5 Imager 和读卡器烧录
官方烧录工具是 M5 Imager。请到官方文档链接的 GitHub Releases 页面,按你的操作系统下载对应版本。具体版本号以该页面和工具内的说明为准。
官方明确建议用读卡器把 microSD 接到电脑上烧录。按官方步骤:
- 打开 M5 Imager。在设备列表中选择
CardputerZero,然后点击NEXT。 - 将 microSD 卡插入读卡器并连接至电脑,等待系统识别存储设备,再选择需要烧录的镜像版本。
- 选择目标存储设备。请确认所选设备正确,避免误擦除其他存储介质的数据。
- 根据需要配置用户名、密码以及 Wi-Fi 连接信息。
- 如需远程登录设备,可启用 SSH 连接功能。
- 确认配置无误后,开始烧录并等待流程完成。
烧录完成后,在关机状态下将卡插入设备,再向右拨动电源开关开机。首次开机可能耗时较长。如果烧录时已经完成用户配置,设备会跳过首次配置向导。
USB 接口烧录(官方不推荐)
官方写明:通过 USB 接口烧录的速度相对较慢,且 usbboot 在部分电脑可能存在兼容问题。如需提升烧录效率,强烈建议使用读卡器。下面的步骤仅整理自官方文档,供无法使用读卡器时对照,不是推荐路径。
先安装 Rpiboot,使插有 microSD 并连接到电脑的 CardputerZero 被识别为磁盘,再用 M5 Imager 烧录。官方提醒部分版本可能有兼容性问题,应使用文档给出的 usbboot 版本与 commit。
- Windows:下载并安装官方文档链接的 rpiboot 程序。
- Linux / macOS:官方要求从源码编译 usbboot。文档给出的命令是:安装依赖(Linux 为
git、libusb-1.0-0-dev、pkg-config;macOS 用 Homebrew 安装libusb和pkg-config),克隆仓库后执行git checkout 61c482663c9b2a61ee86ba491f131ba4ca90e4ea,再make与sudo ./rpiboot。
随后的官方操作步骤是:
- 将 microSD 卡插入设备,将 USB 接口切换开关拨至左侧,以启用机身右侧的 USB Type-C 接口。
- 用右侧 USB Type-C 把设备连到电脑,打开
rpiboot,进入识别等待。官方还写明:在usbboot目录执行./rpiboot -d mass-storage-gadget64,可提高 USB 烧录时的传输速度。 - 长按设备的 Boot 按键。
- 保持按住 Boot 的同时,将电源开关拨至
ON,并在持续按住超过 5 秒后松开。 - 等待
rpiboot识别成功后,电脑会识别到对应的存储设备,再回到 M5 Imager 完成烧录。
首次配置与键盘
首次开机时,按配置向导设置用户名、连接网络,并按需启用 SSH。完成后重启使设置生效。向右拨开关开机,向左拨会先执行关机流程再断电;用命令行关机后,仍需将开关拨到左侧断电。充电走 USB-C2,开关机及 USB Switch 任意位置均可充电。
键盘上,sym 输入蓝色符号,shift 输入大写,fn 触发橙色快捷功能。这三个修饰键:按住不放时指示灯常亮,对按住期间的按键生效;短按一次指示灯慢闪,只对下一次按键生效;连按两次指示灯快闪,锁定该功能,再按一次解除。方向键是按住 fn 再按 F / X / Z / C;部分非文本界面也可直接用这些键。确认用 OK / ENTER。长按 ESC 退出当前应用回到 HOME,短按 ESC 通常返回上一级或取消。常用组合如亮度 fn + U / fn + I、音量 fn + S / fn + D、帮助 fn + H、截屏 fn + J,完整表见官方操作说明。
在 HOME 用方向键选择应用,OK / ENTER 打开。支持帮助的应用可按 fn + H。锁屏:在 HOME 长按 TAB 可手动锁屏;HOME 及部分应用默认 30 秒无操作后自动锁屏,可在 Settings > Screen > DarkTime 调整。解锁时先按任意键点亮屏幕,再依次按 TAB 和 ENTER。
预装软件
下列名称、作用和用法均按官方操作说明逐条整理,不把原版 ESP32 Cardputer 的固件或界面当成 Zero,也不把未经该文档确认的应用写进来。官方说明:系统镜像预装了命令行终端、文件管理器和多媒体应用,可从 HOME 直接打开;GPS、LoRa、NFC 和 SubG Chat 需要连接相应扩展模块。应用源码与帮助可在 官方应用仓库 和 Launcher 源码仓库 查阅。
系统与开发工具
- Settings:打开后选择要调整的系统项目。例如
Screen > DarkTime可调整自动锁屏等待时间。扩展口 5V 在Settings > ExtPort中开启;ADB 在Settings > Developer中开启;预装应用更新在Settings > System > Software。 - Store:联网后打开,浏览应用,进入详情页并按提示安装。安装完成后可在 HOME 打开。也可通过 Store 安装第三方应用;开发并发布到 Store,请参阅官方 开发者指南。本站不整理商店里的完整上架清单。
- CLI:打开终端,输入命令并按
ENTER执行。默认按屏幕宽度显示;需要看更宽输出时可进入 Viewport 模式。fn + Z/fn + C左右移动光标,fn + F/fn + X查看上一条 / 下一条命令,fn + K/fn + N跳到行首 / 行尾,shift + fn + L/shift + fn + M上下翻页,fn + 6进入或退出 Viewport,按住fn再按4、5、7或8平移视口。 - Python:打开 Python 3 交互式解释器(REPL),输入代码后按
ENTER执行。官方示例为print("Hello, CardputerZero!")。光标与历史命令的按键与 CLI 类似:fn + Z/fn + C、fn + F/fn + X,翻页为shift + fn + L/shift + fn + M。 - ZClaw:基于 ZeroClaw 的 AI 助手,可配置多个 AI 服务。完成配置后,按
ENTER输入消息,按F/X滚动对话,按TAB打开设置。首次打开时按向导新建自定义 AI 服务,填写服务 URL、API Key 等参数,完成后会自动下载所需程序。若希望在电脑上粘贴 URL 和 API Key,可先用临时值走完向导;程序下载完成后退出 ZClaw,通过 SSH 或 ADB,用编辑器打开/home/{username}/.zeroclaw/zclaw_providers.tsv(将{username}换成设备的 Linux 用户名),按原字段顺序、用 Tab 分隔替换为实际参数,保存后再打开 ZClaw。 - SSH Client:填写远程设备的连接信息后按
OK连接。用fn + F/fn + X切换输入字段,TAB保存,ESC返回。 - IP Panel:查看设备的 Wi-Fi 和以太网 IP 地址。
- Files:用
F/X选择文件或目录,OK打开,ESC返回。TAB打开操作菜单,可复制、剪切、粘贴、重命名、删除或查看文件信息,并可预览部分兼容格式。用PgUp/PgDn翻页。
拍摄与音频
- Camera:使用内置摄像头或受支持的 USB 摄像头拍照。受屏幕尺寸限制,预览可能无法呈现照片的全部细节。CardputerZero Lite 版本无内置摄像头。拍摄页按
5/7缩小 / 放大,6或ENTER拍照,8打开相册。相册中5/7上一张 / 下一张,6查看照片信息,8删除,ESC或4返回拍摄页。 - Rec:打开后按界面提示开始或停止录音。
- Music:将音乐文件放入当前用户主目录下的
Music文件夹。可显示专辑封面和歌词;检测到该目录中的音乐后会隐藏示例曲目。封面页用左右方向键选择专辑,ENTER打开;曲目列表用上下方向键选曲,ENTER播放或暂停,8查看正在播放的曲目。用4–8执行当前页显示的操作。也可用fn + Q播放或暂停,fn + W/fn + E上一首 / 下一首,fn + A静音,fn + S/fn + D调节音量。 - Piano:
A、S、D、F、G、H、J、K演奏白键,W、E、T、Y、U演奏黑键。SPACE显示或隐藏键位图,Z/C切换八度,P打开示例曲目教程。TAB切换普通演奏和和弦模式;和弦模式下按M切换大调和弦与小调和弦。
指南针、红外与计算
- Compass:首次使用按屏幕提示完成校准,即可查看电子指南针。按
8查看实时 IMU 数据等更多信息。CardputerZero Lite 不支持此应用。 - IR Remote:录制并重放红外遥控信号,可用于控制家电。用
F/X/Z/C导航,按4–8执行当前页显示的操作。录制时将原遥控器对准设备的红外接收端,重放时将设备的红外发射端对准目标设备。 - IR Chat:让两台或多台设备通过红外相互通信。按
ENTER打开消息编辑器,输入后再按ENTER发送。每条消息最多包含 7 个可打印 ASCII 字符。 - Calculator:用数字键输入数字,配合
sym输入小数点和运算符。支持+、-、*、/、^和括号。按OK或输入=求值,退格键删除一个字符。得到结果后可直接输入运算符继续计算。
游戏与设备测试
- Snake:用方向键控制蛇的移动,吃到食物后蛇身变长。移动时避开蛇身和边界。
- Tank:用
F/X/Z/C控制坦克移动,SPACE开火。胜利或游戏结束后,按SPACE重新开始。 - Keyboard Guide:查看键盘修饰键的用法,与设备首次开机的键盘教学内容一致。
- FactoryTest:用于设备功能测试,打开后按界面提示完成对应硬件项目的检查。如出现功能异常,联系技术支持时请提供相应测试页面的照片。
定位与无线通信(需要官方 Cap)
- GPS:官方写明需连接 Cap LoRa-1262。打开后查看定位状态、经纬度、海拔等信息。用
Z/C切换 Position 和 Details,用F/X滚动详情。 - LoRa:官方同样写明需连接 Cap LoRa-1262。进入发送页面并输入消息,按
ENTER发送,按ESC取消。接收设备可在应用内查看消息。官方预装应用并未写明支持 Cap LoRa868。 - NFC:官方写明需连接 Cap CC1101。打开后将标签靠近模块以读取信息。用
Z/C在扫描、标签详情和读卡器信息之间切换,用F/X滚动详情,按ENTER打开标签详情。 - SubG Chat:在参与聊天的设备上连接 Cap CC1101,打开应用。用
Z/C切换消息和模块信息,用F/X滚动消息。按ENTER打开编辑器,也可直接输入字符开始编辑,再按ENTER发送。每条消息最多 56 个可打印 ASCII 字符。按ESC取消编辑。
插入或移除 Cap 前必须先关机,不能热插拔。更完整的接口与模块说明见扩展模块。
SSH、ADB、更新与系统恢复
SSH:启用后可通过设备 IP 地址连接。IP 可在 IP Panel 或 Settings 中查看。首次配置向导或烧录时都可以启用 SSH。
ADB:官方操作说明写明,在 Settings > Developer 中开启 ADB,将 USB Switch 切换至 Slave 模式,再通过 USB-C2 连接电脑。更完整的步骤在 CardputerZero ADB 连接调试:将机身左侧 USB-SW 拨到左侧;在 APP Launcher 中进入 Settings > Developer > ADB 并启用;按操作系统下载 ADB Platform-Tools;用机身右侧 USB Type-C 连接电脑。传输文件可用 adb push(文档示例为 adb push data.json /opt);若提示没有权限,先执行 adb kill-server。进入设备终端使用 adb shell。
更新:设备自带的应用软件可在 Settings > System > Software 中更新。
系统恢复:如需重新安装系统,按官方镜像烧录指南烧录最新镜像。本站不提供自行制作的镜像,也不列出未在官方工具中出现的版本号。
官方还提供 CardputerZero Hub 与开发者指南,以及 应用开发模板。开发相关步骤以这些官方页面为准。
Recommended: flash with M5 Imager and a card reader
The official flashing tool is M5 Imager. Use the official docs’ link to GitHub Releases and download the build for your operating system. Version numbers are whatever that page and the tool itself list.
Official docs strongly recommend connecting the microSD card to the computer with a card reader. The official steps are:
- Open M5 Imager. Select
CardputerZeroin the device list, then clickNEXT. - Insert the microSD card into a card reader and connect it to the computer. After the system detects the storage device, select the image version to flash.
- Select the target storage device. Confirm it is the correct device so you do not erase other media.
- Configure the username, password, and Wi-Fi information as needed.
- If you need remote login, you can enable SSH.
- Confirm the settings, start flashing, and wait for the process to finish.
When flashing is done, insert the card while the device is off, then slide the power switch to the right. The first boot may take a while. If user setup was completed in the imager, the device skips the first-run wizard.
Flashing over USB (officially not recommended)
Official docs state that USB flashing is relatively slow, and that usbboot may have compatibility issues on some computers. A card reader is strongly recommended. The steps below are reproduced from the official guide for cases where a reader is unavailable; they are not the recommended path.
Install Rpiboot so that a CardputerZero with a microSD card, connected to the computer, is recognized as a disk, then flash with M5 Imager. Official docs warn that some versions may be incompatible, and tell you to use the usbboot revision and commit they give.
- Windows: download and install the rpiboot program linked from the official docs.
- Linux / macOS: official docs require building usbboot from source. The documented commands install dependencies (
git,libusb-1.0-0-dev, andpkg-configon Linux;libusbandpkg-configvia Homebrew on macOS), clone the repository, rungit checkout 61c482663c9b2a61ee86ba491f131ba4ca90e4ea, thenmakeandsudo ./rpiboot.
The official USB procedure then is:
- Insert the microSD card into the device and set the USB switch to the left to enable the right-side USB Type-C port.
- Connect the right-side USB Type-C port to the computer and start
rpiboot, waiting for detection. Official docs also say that running./rpiboot -d mass-storage-gadget64from theusbbootdirectory can increase USB transfer speed. - Press and hold the device’s Boot button.
- While holding Boot, slide the power switch to
ON, keep holding for more than 5 seconds, then release. - After
rpibootconnects successfully, the computer will see the storage device, and you can finish flashing in M5 Imager.
First-run setup and the keyboard
On first boot, the setup wizard asks you to set a username, join a network, and optionally enable SSH. Restart afterwards so the settings take effect. Slide the switch right to power on, and left to run the shutdown sequence and then cut power. After a software shutdown, still slide the switch left. Charging is through USB-C2 and works whether the device is on or off, and in either USB Switch position.
sym types the blue symbols, shift types capitals, and fn triggers the orange shortcuts. Hold a modifier to keep it active (steady light), tap once for the next key only (slow blink), or double-tap to lock it (fast blink) and tap again to unlock. Arrows are fn plus F / X / Z / C; some non-text screens also accept those keys directly. Confirm with OK / ENTER. A long press of ESC quits to HOME; a short press usually goes back or cancels. Frequent shortcuts include brightness fn + U / fn + I, volume fn + S / fn + D, help fn + H, and screenshot fn + J. The full table is in the official usage guide.
On HOME, use the arrows to select an app and OK / ENTER to open it. Apps that support help use fn + H. Lock the screen on HOME with a long press of TAB. HOME and some apps also lock after 30 seconds of inactivity by default; change this in Settings > Screen > DarkTime. To unlock, press any key to wake the screen, then TAB and ENTER in sequence.
Preinstalled software
The names, roles, and controls below are checked against the official usage guide, item by item. Firmware or UI from the original ESP32 Cardputer is not treated as Zero, and apps not confirmed in that guide are not added here. Official docs say the system image preinstalls a command-line terminal, a file manager, and multimedia apps, opened from HOME; GPS, LoRa, NFC, and SubG Chat require the corresponding expansion modules. Source and help live in the official app repository and the Launcher source repository.
System and developer tools
- Settings: open it and choose the system item to change. For example,
Screen > DarkTimeadjusts the auto-lock delay. Enable port 5V inSettings > ExtPort, ADB inSettings > Developer, and preinstalled-app updates inSettings > System > Software. - Store: open it while online, browse apps, open a details page, and follow the prompts to install. Installed apps then appear on HOME. Third-party apps can also be installed from Store; to develop and publish to Store, see the official developer guide. This site does not inventory the complete Store catalog.
- CLI: open the terminal, type a command, and press
ENTER. Output is wrapped to the screen width by default; use Viewport mode for wider output.fn + Z/fn + Cmove the cursor,fn + F/fn + Xrecall previous or next commands,fn + K/fn + Njump to the start or end of the line,shift + fn + L/shift + fn + Mpage up or down, andfn + 6toggles Viewport mode. Holdfnand press4,5,7, or8to pan the viewport. - Python: opens the Python 3 REPL. Type code and press
ENTER. The official example isprint("Hello, CardputerZero!"). Cursor and history keys match CLI:fn + Z/fn + C,fn + F/fn + X, and paging withshift + fn + L/shift + fn + M. - ZClaw: an AI assistant based on ZeroClaw that can be configured with multiple AI services. After setup, press
ENTERto type a message,F/Xto scroll the conversation, andTABfor settings. The first launch walks you through creating a custom AI service (URL, API key, and similar fields) and then downloads the required program. To paste a URL and API key on a computer, finish the wizard with temporary values first; after the download finishes, quit ZClaw, connect over SSH or ADB, and edit/home/{username}/.zeroclaw/zclaw_providers.tsv(replace{username}with the device’s Linux username). Keep the original field order and Tab separators, save, then reopen ZClaw. - SSH Client: enter the remote connection details and press
OKto connect.fn + F/fn + Xmove between fields,TABsaves, andESCgoes back. - IP Panel: shows the device’s Wi-Fi and Ethernet IP addresses.
- Files:
F/Xselect a file or folder,OKopens it, andESCgoes back.TABopens the action menu for copy, cut, paste, rename, delete, or file info, and some compatible formats can be previewed. Page withPgUp/PgDn.
Camera and audio
- Camera: uses the built-in camera or a supported USB camera. The preview may not show every detail because of the screen size. CardputerZero Lite has no built-in camera. On the capture page,
5/7zoom out or in,6orENTERtakes a photo, and8opens the album. In the album,5/7go to the previous or next photo,6shows information,8deletes, andESCor4returns to capture. - Rec: follow the on-screen prompts to start or stop recording.
- Music: put music files in the
Musicfolder in the current user’s home directory. The app can show album art and lyrics, and hides the sample tracks once it finds music there. On the cover page, use left/right to pick an album andENTERto open it; in the track list, use up/down to select,ENTERto play or pause, and8to see the playing track. Use4–8for the actions shown on the current page. You can also usefn + Qto play or pause,fn + W/fn + Efor previous or next,fn + Ato mute, andfn + S/fn + Dfor volume. - Piano:
A,S,D,F,G,H,J,Kplay the white keys;W,E,T,Y,Uplay the black keys.SPACEshows or hides the keymap,Z/Cchange octave, andPopens the sample-song tutorial.TABswitches between normal and chord mode; in chord mode,Mtoggles major and minor chords.
Compass, infrared, and calculator
- Compass: follow the on-screen calibration the first time, then use the electronic compass. Press
8for live IMU data and more. CardputerZero Lite does not support this app. - IR Remote: record and replay infrared remote signals, for example to control appliances. Navigate with
F/X/Z/C, and use4–8for the actions shown on the page. Point the original remote at the device’s IR receiver when recording, and point the device’s IR transmitter at the target when replaying. - IR Chat: lets two or more devices communicate over infrared. Press
ENTERto open the editor, type a message, and pressENTERagain to send. Each message can contain at most 7 printable ASCII characters. - Calculator: type digits with the number keys, and use
symfor the decimal point and operators. Supported operators are+,-,*,/,^, and parentheses. PressOKor type=to evaluate, and Backspace to delete one character. After a result, you can type an operator and continue.
Games and device tests
- Snake: steer with the arrow keys. The snake grows when it eats food. Avoid the snake’s body and the edges.
- Tank: move with
F/X/Z/Cand fire withSPACE. After a win or game over, pressSPACEto restart. - Keyboard Guide: explains the modifier keys, matching the first-boot keyboard tutorial.
- FactoryTest: a hardware self-test. Follow the on-screen checks. If something fails, official docs ask you to provide photos of the relevant test pages when contacting support.
Location and radio (official Caps required)
- GPS: official docs require Cap LoRa-1262. The app shows fix status, latitude, longitude, altitude, and related data.
Z/Cswitch Position and Details;F/Xscroll details. - LoRa: also requires Cap LoRa-1262. Open the send page, type a message, press
ENTERto send orESCto cancel. A receiving device can view the message in the app. The official preinstalled apps do not name Cap LoRa868. - NFC: official docs require Cap CC1101. Hold a tag near the module to read it.
Z/Cswitch among scan, tag details, and reader information;F/Xscroll details;ENTERopens tag details. - SubG Chat: attach Cap CC1101 on each participating device and open the app.
Z/Cswitch between messages and module information;F/Xscroll messages. PressENTERto open the editor, or start typing, then pressENTERto send. Each message can contain at most 56 printable ASCII characters. PressESCto cancel editing.
Power the device off before inserting or removing a Cap; hot-swapping is not supported. See the expansion modules section for ports and Cap details.
SSH, ADB, updates, and recovery
SSH: once enabled, connect using the device IP address, which is shown in IP Panel or Settings. SSH can also be enabled in the first-run wizard or while flashing.
ADB: the official usage guide says to enable ADB in Settings > Developer, set USB Switch to Slave, and connect through USB-C2. The full procedure is in the CardputerZero ADB guide: set the left-side USB-SW to the left; in APP Launcher open Settings > Developer > ADB and enable it; download ADB Platform-Tools for your OS; and connect the right-side USB Type-C port to the computer. Transfer files with adb push (the documented example is adb push data.json /opt). If you see a permission error, run adb kill-server first. Open a device shell with adb shell.
Updates: built-in application software can be updated in Settings > System > Software.
Recovery: to reinstall the system, flash the latest official image using the official image guide. This site does not host a custom image and does not list version numbers that are not shown in the official tools.
Official docs also point to the CardputerZero Hub and developer guide and the application template. Follow those official pages for development steps.