USB串口控制(CDC)
萤火虫T1 的 Type-C 口是芯片原生 USB。插到电脑上,电脑会同时看到两个设备:一个 U 盘(存放固件、App 和素材)和一个虚拟串口(CDC)。这个串口不需要装任何驱动,在设备端就是一个普通的 sys.stdin / sys.stdout——读一行、写一行,就完成了一次和电脑的通信。
Windows 10+ / macOS / Linux 全部免驱。CDC 走 USB,波特率填什么都不影响。
sys.stdin.readline() 读电脑发来的命令,print() 把数据回传给电脑。
USB 收到的字节进的是和 REPL 同一个输入缓冲区——程序没在跑时,你打的字由 REPL 处理。
Type-C 一次提供两个设备

| 电脑看到的设备 | 作用 | 在设备端是什么 |
|---|---|---|
| U 盘(MSC) | 放固件、App、图片、配置文件 | FAT 分区,挂载到 /sd |
| 串口(CDC) | 发命令、收日志、调试 | sys.stdin(读)/ sys.stdout(写) |
本文只讲串口(CDC)。两个设备互不干扰:写文件走 U 盘那条路,传数据走串口这条。
硬件与接口
| 项目 | 值 |
|---|---|
| 接口 | Type-C,芯片原生 USB(TinyUSB) |
| 设备端对象 | sys.stdin(读)、sys.stdout(写) |
| 是否需要驱动 | 不需要(Windows 10 及以上、macOS、主流 Linux 免驱) |
| 波特率 | 无效参数。CDC 走 USB 全速总线,串口助手填 115200 只是为了不被拒绝 |
| 输入缓冲 | USB-CDC 与 UART0 REPL 共用同一个输入缓冲区 |
| 主机关闭/未连接时 | 写入的数据直接丢弃(固件只在 CDC 已连接时才发送) |
| 单次写入超时 | 最长 500 毫秒,之后剩余数据丢弃,不会把程序永久卡死 |
| 中断字符 | Ctrl-C(0x03)由固件直接转成 KeyboardInterrupt,你的程序读不到这个字节 |
快速开始
把下面几行直接粘到 REPL 里,或者放进 SD 卡的 boot.py:
import sys
print("Firefly T1 ready") # 电脑串口助手立刻能看到这一行
while True:
line = sys.stdin.readline() # 阻塞等待电脑发来一整行
print("收到:", line)
运行现象:在电脑的串口助手里发一句 hello 并勾选「发送新行」,设备立刻回显 收到: hello。
API 参考
设备端没有额外的 cdc 模块,用的就是 MicroPython 标准的 sys.stdin / sys.stdout。下面几个接口已经过官方 App 实测。
读取一行 sys.stdin.readline()
line = sys.stdin.readline()
从电脑读入一整行,返回 str。
- 阻塞:缓冲区里没有「换行」时,这个调用会一直等下去,后面的代码不会执行。
- 返回的字符串包含行尾的换行符,通常接一个
.strip()去掉。 - 串口助手必须勾选「发送新行」(
\n或\r\n),否则readline()永远不返回。 - 程序退出、回到 REPL 之后,你在串口里输入的内容由 REPL 消费,不再进你的代码。
写出一行 print() / sys.stdout.write()
print("data") # 自动补换行
sys.stdout.write("data\n") # 不补换行,需要自己写 \n
向电脑发送数据,返回写入的字符数(print() 返回 None)。
- 串口助手通常是按行刷新的,所以每次发完记得带
\n。 - 主机没连接时数据会被丢弃,不会报错——调试日志刷不出来时先检查串口是否真的打开了。
- 单次写入最长等 500 毫秒:主机端口开着但没人读、缓冲区满了,剩下的数据会被丢掉而不是无限等待。
- 这也是 REPL 的输出通道。所以一边跑程序一边
print(),看到的就是同一个串口。
非阻塞读取 select.poll()
readline() 会阻塞,如果设备还要同时刷屏幕、读按键,就用 select.poll() 先问「有没有数据」:
import select
import sys
poll = select.poll()
poll.register(sys.stdin, select.POLLIN)
events = poll.poll(0) # 参数是超时毫秒数,0 = 立即返回
if events:
cmd = sys.stdin.readline().strip()
print("收到:", cmd)
这是官方 App 的写法:主循环里先 poll(0),有数据才 readline(),没数据就继续渲染画面。
中断 Ctrl-C
USB 收到的 Ctrl-C(字节 0x03)由固件直接转成键盘中断,while True: sys.stdin.readline() 这种死循环因此可以用 Ctrl-C 停下来:
try:
while True:
cmd = sys.stdin.readline().strip()
except KeyboardInterrupt:
print("已停止")
要注意的是:这个字节不会出现在 readline() 的返回值里,所以你不能把它当成普通命令来处理。
常见坑点
| 坑 | 原因与正确做法 |
|---|---|
| 发了命令设备没反应 | 串口助手没勾「发送新行」→ readline() 需要换行符才返回 |
| 程序「卡死」不动了 | 执行到了 readline() 在等输入 → 想边跑边收命令就用 poll() 非阻塞读 |
想用 Ctrl-C 当命令发 | 它被固件当键盘中断吃掉了 → 用 ESC 或自定义字符串(如 quit)当退出命令 |
print() 出来是空的 | 主机侧串口没打开 → 数据只发给已连接的 CDC,未连接直接丢弃 |
| 大量日志时丢字 | 单次写入 500 毫秒超时 → 降频打印,或把日志写文件 |
| 从串口发的字变成了 REPL 报错 | 程序已经退出,输入被 REPL 接管 → 重新运行你的脚本 |
| 中文乱码 | 设备端发的是 UTF-8 字节 → 串口助手也切到 UTF-8 编码 |
| 串口助手连不上 / 波特率报错 | 波特率对 CDC 无效 → 随便填 115200 即可;连不上先换一根数据线(不是充电线) |
更多配方
命令分发(最常用的骨架)
import sys
while True:
cmd = sys.stdin.readline().strip().lower()
if not cmd:
continue
if cmd == "ping":
print("pong")
elif cmd == "ver":
print("Firefly T1")
elif cmd == "quit":
print("bye")
break
else:
print("未知命令:", cmd)
电脑侧用 Python 发命令
上位机装 pyserial(pip install pyserial),把 COM3 换成你的串口号(macOS / Linux 形如 /dev/tty.usbmodem*):
import serial
import time
port = serial.Serial('COM3', 115200, timeout=1)
time.sleep(0.5) # 等设备端 CDC 准备好
port.write(b'ping\n') # 注意:必须以换行结尾
print(port.readline().decode().strip())
port.close()
调试日志:用一个开关控制输出
import sys
DEBUG = True
def log(*args):
if DEBUG:
print("[log]", *args)
log() 走的是同一个 CDC,串口助手里能直接看到;关掉 DEBUG 就完全静默。
完整示例
萤火虫T1 的 App 放在 SD 卡的 /sd/apps/<应用目录>/ 下,入口是 boot.py。下面这段放进 /sd/apps/my-cdc-app/boot.py:非阻塞收命令、ping 回显、beep 触发蜂鸣器、quit 退出。
import select
import sys
import time
import beep
poll = select.poll()
poll.register(sys.stdin, select.POLLIN)
print("my-cdc-app started, type help")
running = True
while running:
events = poll.poll(0)
if events:
cmd = sys.stdin.readline().strip().lower()
if cmd == "help":
print("commands: ping / beep / help / quit")
elif cmd == "ping":
print("pong")
elif cmd == "beep":
beep.tone(2000, 200)
print("beep!")
elif cmd == "quit":
print("bye")
running = False
elif cmd:
print("未知命令:", cmd)
time.sleep(0.02) # 刷屏、刷灯之类的活干在这里
beep.stop()
排错
| 现象 | 原因 / 处理 |
|---|---|
| 电脑上根本没有串口 | 用了充电线(无数据线芯)→ 换数据线;或换一个 USB 口 / 换一台电脑验证 |
| 有串口但发什么都没反应 | 串口助手没勾「发送新行」→ 勾上再发 |
| 能收到设备日志,但发命令不生效 | 程序已退出到 REPL,输入被 REPL 接管 → 重新运行脚本 |
收到重复的 >>> 提示 | 你打断到了 REPL 提示符 → 先 Ctrl-D 软重启再运行脚本 |
| 打印内容缺失、丢行 | 打印太频繁触发 500 毫秒写入超时 → 降低频率或写文件 |
设备端 OSError / 崩溃 | 读取被中断或热插拔 → 用 try/except 包裹主循环 |
| 中文变问号 | 串口助手不是 UTF-8 → 改成 UTF-8 编码 |
相关模块见 蜂鸣器(beep)、五向按键(button) 与 拓展接口。
AI 用法(即将上线)
以后你不用自己写命令分发骨架、也不用记 poll() 的用法:用自然语言描述你想要的交互,Agent 会照着本文档里的 API,直接生成能在萤火虫T1 上运行的完整程序。
比如直接对它说:
电脑通过串口发
beep 2000 200就让蜂鸣器按这个频率响这么久,发say hello就在屏幕上显示这句话,发quit就退出。
它就会把 sys.stdin、select.poll()、beep 和显示屏接口组合成一个能跑的程序,并帮你放进 SD 卡的 /sd/apps/。
入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。