跳到主要内容

USB串口控制(CDC)

独角仙S1 的 Type-C 口是芯片原生 USB。插到电脑上,电脑会同时看到两个设备:一个 U 盘(存放固件、App 和素材)和一个虚拟串口(CDC)。这个串口不需要装任何驱动,在设备端就是一个普通的 sys.stdin / sys.stdout——读一行、写一行,就完成了一次和电脑的通信。

插上就能用

Windows 10+ / macOS / Linux 全部免驱。CDC 走 USB,波特率填什么都不影响。

读一行写一行

sys.stdin.readline() 读电脑发来的命令,print() 把数据回传给电脑。

和 REPL 共用缓冲

USB 收到的字节进的是和 REPL 同一个输入缓冲区——程序没在跑时,你打的字由 REPL 处理。

Type-C 一次提供两个设备​

独角仙S1 USB-CDC 串口接口示意图

电脑看到的设备作用在设备端是什么
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("Beetle S1 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("Beetle S1")
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 就完全静默。

完整示例​

独角仙S1 的 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) · 灯光控制(WS2812) · 显示屏(ST7789)

AI 用法(即将上线)​

以后你不用自己写命令分发骨架、也不用记 poll() 的用法:用自然语言描述你想要的交互,Agent 会照着本文档里的 API,直接生成能在独角仙S1 上运行的完整程序。

比如直接对它说:

电脑通过串口发 beep 2000 200 就让蜂鸣器按这个频率响这么久,发 img on 就显示一张图,发 quit 就退出。

它就会把 sys.stdin、select.poll()、beep 和显示屏接口组合成一个能跑的程序,并帮你放进 SD 卡的 /sd/apps/。

Agent 入口(即将上线)

入口链接会放在这里。上线后点一下,就能直接开始描述你想要的应用。