企业官网建设流程全解析

导读

本文基于 TobudOS 仓库内嵌的 MicroPython 组件文档，完整讲解如何将 pyboard（MicroPython 官方开发板）配置为 USB 鼠标：从修改boot.py切换 USB 模式、通过 REPL 手动发送鼠标事件，到利用板载加速度计实现"倾斜控制鼠标"的完整程序，并覆盖安全模式（safe mode）进入与恢复正常模式的全部步骤。读完本文你将掌握pyb.usb_mode()、pyb.USB_HID()的底层参数与 API 细节，能够独立把 pyboard 改造为可交互的 HID 输入设备。

pyboard 作为 USB 设备的两种角色

pyboard 本身是一个 USB 设备。默认情况下，它插上电脑后表现为一个 U 盘（MSC，mass storage device），用于存放boot.py、main.py等文件；同时它也可以被配置为串口（VCP，Virtual COM Port）。本文的主角则是第三种角色：HID（Human Interface Device，人机接口设备），即让 pyboard 在电脑看来是一只鼠标。

在 TobudOS 仓库中，MicroPython 以 RTOS 任务的形式运行——示例入口 中通过tos_task_create()创建名为micropython的任务来执行mp_main()，因此boot.py与main.py中的代码都运行在 TobudOS 内核之上。其中启动脚本的执行逻辑在 port/mpmain.c：mp_main()依次调用pyexec_file_if_exists("boot.py")与pyexec_file_if_exists("main.py")，这正是"boot 阶段配置 USB、main 阶段运行业务代码"的运行时依据。

第一步：编辑 boot.py，把 pyboard 配置为 USB 鼠标

要让 pyboard 以鼠标身份出现，必须先在boot.py中修改 USB 配置。如果你从未动过boot.py，它默认内容大致如下：

# boot.py -- run on boot to configure USB and filesystem # Put app code in main.py import pyb #pyb.main('main.py') # main script to run after this one #pyb.usb_mode('VCP+MSC') # act as a serial and a storage device #pyb.usb_mode('VCP+HID') # act as a serial device and a mouse

启用鼠标模式只需取消最后一行的注释，使其变为：

pyb.usb_mode('VCP+HID') # act as a serial device and a mouse

如果boot.py已经被你改过，那么它能工作的最小代码为：

import pyb pyb.usb_mode('VCP+HID')

这行代码告诉 pyboard：启动时把自己配置为VCP + HID复合设备——既能当串口（用于 REPL 调试），又能当人机接口设备（本例中是鼠标）。

完成编辑后：

1. 安全弹出/卸载 pyboard 的 U 盘；
2. 按下板上的RST开关复位开发板；
3. 此时电脑应能将 pyboard 识别为一只鼠标。

第二步：通过 REPL 手动发送鼠标事件

鼠标模式生效后，先通过串口程序（如 PuTTY、minicom）连接到 pyboard 的 REPL，手动发送事件验证效果：

>>> hid = pyb.USB_HID() >>> hid.send((0, 100, 0, 0)) # (button status, x-direction, y-direction, scroll)

执行后，你的鼠标指针应向右移动 100 像素。这里send()的四元组含义为：

让鼠标左右来回摆动，可以用正弦函数构造周期性位移：

>>> import math >>> def osc(n, d): ... for i in range(n): ... hid.send((0, int(20 * math.sin(i / 10)), 0, 0)) ... pyb.delay(d) ... >>> osc(100, 50)

其中第一个参数n是发送的鼠标事件次数，第二个参数d是两次事件之间的延时（毫秒）。可以尝试不同的取值观察指针摆动幅度与频率的变化。

练习：思考如何修改上述代码，让鼠标指针绕一个圆圈移动（提示：同时使用 x 与 y 两个方向的位移，并按圆周参数化）。

第三步：用加速度计控制鼠标（含安全模式实操）

接下来实现"板子怎么倾斜，鼠标就往哪走"。这段代码可以粘贴到 REPL 中直接运行，也可以放进main.py。我们选择放进main.py——因为这样做能顺便学会进入安全模式（safe mode）。

为什么需要安全模式？当前 pyboard 已经处于 VCP+HID 模式，插上电脑后不再显示 U 盘，你无法访问文件系统去编辑main.py；同样，也没法改boot.py退出 HID 模式。安全模式正是用来解决这个"死锁"的。

进入安全模式的操作步骤

1. 按住板上的USR开关；
2. 保持按住 USR，按下并松开RST开关；
3. 此时 LED 会依次循环：绿 → 橙 → 绿+橙 → 再循环；
4. 持续按住 USR，直到只有橙色 LED 亮起，然后松开 USR；
5. 橙色 LED 应快速闪烁 4 次后熄灭；
6. 此时已进入安全模式。

安全模式下boot.py与main.py都不会被执行，pyboard 以默认设置启动，因此 U 盘会重新出现，你可以正常编辑main.py（保持boot.py不变，因为我们编辑完main.py后还要回到 HID 模式）。

main.py 中的加速度计鼠标程序

在main.py中写入以下代码：

import pyb switch = pyb.Switch() accel = pyb.Accel() hid = pyb.USB_HID() while not switch(): hid.send((0, accel.x(), accel.y(), 0)) pyb.delay(20)

程序逻辑拆解：

• pyb.Switch()：创建 USR 开关对象，调用switch()可读取其状态（按住为True），作为退出循环的条件；更完整的用法可参考开关教程；
• pyb.Accel()：创建加速度计对象，accel.x()、accel.y()返回有符号整数（典型范围约 -30～30），用于表征板子的倾斜角度；原始测量值存在噪声，实际工程中通常按区间判断而非比较精确值，详见加速度计教程；
• 主循环以 20ms 为周期，把 x/y 轴倾角实时映射为鼠标位移。

保存文件、弹出 U 盘并按下RST复位。此时 pyboard 应表现为一只鼠标，板子的倾斜角度会带动指针移动。按下USR开关即可停止鼠标运动。

关于 y 轴方向：运行后会注意到 y 轴方向是反的，修复方法很简单——在hid.send()的 y 坐标前加一个负号即可：

hid.send((0, accel.x(), -accel.y(), 0))

第四步：恢复正常模式

如果不再需要鼠标功能，pyboard 会在每次插入 USB 时都以鼠标身份启动。恢复正常的操作是：

1. 按前述步骤先进入安全模式；
2. 编辑boot.py，在VCP+HID那一行前加上#注释掉：

#pyb.usb_mode('VCP+HID') # act as a serial device and a mouse

3. 保存文件，弹出 U 盘并复位 pyboard。

此时 pyboard 恢复为默认的串口 + 存储设备模式。关于安全模式与文件系统工厂复位（factory reset）的更多细节，参见安全模式与工厂复位教程。

深入理解：usb_mode() 参数与 USB_HID API

pyb.usb_mode() 完整参数

在 pyb 库文档 中，pyb.usb_mode()的完整签名为：

usb_mode([modestr], port=-1, vid=0xf055, pid=-1, msc=(), hid=pyb.hid_mouse, high_speed=False)

• 不带参数调用：返回当前 USB 模式字符串；
• modestr取值：
  • None：禁用 USB；
  • 'VCP'：仅串口（虚拟串口）；
  • 'MSC'：仅存储设备；
  • 'VCP+MSC'：串口 + 存储设备（默认模式）；
  • 'VCP+HID'：串口 + 人机接口设备（本文所用的鼠标模式）；
  • 'VCP+MSC+HID'：三者兼有（仅特定型号开发板支持）；
  • 为向后兼容，'CDC'等同于'VCP'，'CDC+MSC'、'CDC+HID'同理；
• port：多 USB 端口板卡上选择端口（0、1…），-1 表示自动选择默认端口；
• vid/pid：自定义厂商 ID 与产品 ID，pid=-1时根据modestr自动选择；
• msc：启用 MSC 时指定要暴露的 SCSI LUN 列表，例如msc=(pyb.Flash(), pyb.SDCard())；
• hid：启用 HID 时指定 HID 细节，为一个五元组(subclass, protocol, max packet length, polling interval, report descriptor)。默认pyb.hid_mouse是适合 USB 鼠标的取值，另有pyb.hid_keyboard常量可用于模拟 USB 键盘；
• high_speed：硬件支持时设为True可启用 USB 高速模式。

pyb.USB_HID 类

在 pyb.USB_HID 文档 中，该类用于创建表示 USB HID 接口的对象，可模拟鼠标、键盘等外设。使用前必须先用pyb.usb_mode()将 USB 模式切换为包含 HID 接口。

• 构造：pyb.USB_HID()直接创建对象；
• USB_HID.send(data)：通过 HID 接口发送数据，data为整数组成的 tuple/list 或 bytearray（即本文中(按键状态, x, y, 滚轮)的发送通道）；
• USB_HID.recv(data, *, timeout=5000)：接收总线数据，data可为接收字节数的整数或用于填充的可变缓冲区；timeout为毫秒级超时。若data为整数则返回新缓冲区，否则返回实际读入字节数。

总结与扩展思路

至此，一条完整的实践链路已经打通：boot.py中pyb.usb_mode('VCP+HID')完成设备角色切换 → REPL 中pyb.USB_HID().send()验证 HID 数据通路 →main.py中以加速度计数据实时驱动指针 → 安全模式作为"逃生通道"保证随时可回退。

基于同样的机制，还可以进一步扩展：将hid参数替换为pyb.hid_keyboard常量即可把 pyboard 变成 USB 键盘；USB_HID.recv()可用于接收上位机发来的 HID 数据，为双向人机交互留出空间。这套方法在 TobudOS 集成 MicroPython 的工程中，可直接复用到基于 STM32 等 MCU 的自研板卡上，只需确认板级 USB 硬件支持 HID 端点即可。