1. 项目概述如果你玩过CircuitPython大概率对插上USB线后电脑上自动弹出的CIRCUITPY盘符和串口终端不陌生。这很方便让你能像操作U盘一样拖拽代码文件也能随时打开串口监视器查看打印信息。但当你真正想把手里的开发板变成一个“正经”的USB设备比如一个专属的宏键盘、一个游戏手柄或者一个不希望被用户随意修改内部文件的数据采集器时这些默认出现的“开发工具”就显得有些碍眼了。它们不仅占用了系统资源更关键的是会让你的最终产品在用户电脑上看起来像个半成品开发板而不是一个独立、专业的设备。这正是CircuitPython USB设备自定义的核心价值所在。它允许你作为一名开发者在boot.py这个特殊的启动脚本中像导演一样编排你的开发板在USB舞台上的“角色”。你可以让存储设备CIRCUITPY在演出时“隐身”可以关闭那个用于调试的串口终端REPL甚至可以启用第二个纯粹的、不受干扰的数据串口。更进一步你还能定义全新的、符合USB HID标准的自定义设备比如一个带有特殊摇杆和按钮布局的游戏手柄或者一个工业用的控制面板。这个过程不仅仅是开关几个功能它涉及到对USB底层机制的理解比如“端点”这个硬件资源的分配以及如何编写描述设备能力的“报告描述符”。本篇文章我将结合自己多次将CircuitPython项目产品化的经验从最基础的配置讲起一直深入到自定义HID设备的开发帮你彻底掌握如何让你的CircuitPython设备在USB世界里表现得既专业又高效。2. 核心概念与boot.py的绝对权威在开始动手修改之前我们必须建立一个最重要的认知所有USB设备的配置都必须且只能在boot.py文件中进行。这是CircuitPython设计上的一个铁律理解其背后的“为什么”能帮你避开无数坑。2.1 为什么必须是boot.py你可以把开发板连接电脑的过程想象成一次外交会晤。boot.py运行于会晤开始前的“内部筹备会议”阶段。在这个阶段你的开发板还没有和电脑主机建立任何正式的USB通信连接。此时你可以从容地决定这次会晤要派出哪些“代表”USB设备以及每个代表的“职权范围”设备描述符。一旦boot.py执行完毕CircuitPython就会根据你的配置生成一份完整的“外交人员名单和设备能力说明书”即USB描述符集。紧接着开发板才会正式向电脑“亮明身份”开始枚举过程。电脑会读取这份说明书并为每一个设备分配资源、安装驱动。而你的主程序code.py则是在枚举过程开始后才启动的。此时USB连接的“外交框架”已经确立木已成舟。如果你试图在code.py中调用storage.disable_usb_drive()CircuitPython会直接抛出一个错误因为USB大容量存储设备这个“代表”已经在会晤中开始工作了你无法中途将其撤下。实操心得我早期就犯过在code.py里尝试禁用设备的错误结果程序直接崩溃。记住这个顺序硬件复位 -boot.py执行配置USB- USB枚举 -code.py执行。任何想动态切换USB设备功能比如运行时让CIRCUITPY出现又消失的需求在标准CircuitPython下是无法实现的必须在设计之初就在boot.py里定死。2.2 硬复位与文件写入完成与boot.py的权威性紧密相关的另一个关键点是boot.py只在硬复位Hard Reset后运行。什么是硬复位就是你给板子重新上电或者按下了物理的复位RESET按钮。在REPL里输入CtrlD进行软复位或者只是修改并保存了boot.py文件都不会触发boot.py的重新执行。这带来一个非常重要的操作流程每次修改boot.py后你必须执行一次硬复位新的配置才会生效。而且在复位前你必须确保修改已经完全写入板载的存储中。避坑指南CircuitPython的文件写入有时不是立即完成的特别是当你通过某些编辑器或IDE保存时可能会有缓存。最稳妥的做法是在编辑完boot.py后在文件管理器中对CIRCUITPY盘执行一次“弹出”或“安全移除硬件”操作。等待系统提示“可以安全移除硬件”后再按复位键。我曾经因为没等写入完成就复位导致boot.py文件损坏整个文件系统需要重新格式化项目代码全丢。3. 基础设备管理隐藏、显示与串口倍增掌握了boot.py的运作机制我们就可以开始实操了。我们从最简单的开始管理那些CircuitPython默认提供的标准设备。3.1 让CIRCUITPY盘符消失对于要作为成品交付的设备让内部的文件系统对用户不可见是基本要求。这能防止用户误删或修改关键文件也让设备看起来更专业。import storage storage.disable_usb_drive() # 这行代码会让CIRCUITPY盘符在电脑上消失就这么简单。但这里藏着一个巨大的“陷阱”原文也用了醒目的警告不要只写这一行试想你写了一个boot.py里面只有storage.disable_usb_drive()。你把它放到板子上复位。好了CIRCUITPY盘符不见了你的程序code.py开始运行设备工作正常。但有一天你需要更新code.py里的逻辑或者修复一个bug你该怎么办你没有任何办法再把CIRCUITPY弄出来因为你无法修改boot.py了——它所在的盘符根本看不见这就是所谓的“把自己锁在外面”。为了避免这种情况你必须设计一个“逃生舱”机制。最常见的做法是使用一个硬件按钮。在boot.py中检测这个按钮的状态如果按钮没有被按下则禁用设备如果检测到按钮被按下则保持设备启用。import storage import board import digitalio # 假设我们使用板载的按钮A按下时连接到高电平如Circuit Playground Express button digitalio.DigitalInOut(board.BUTTON_A) button.switch_to_input(pulldigitalio.Pull.DOWN) # 启用内部下拉电阻 # 仅当按钮未被按下时才禁用USB存储 if not button.value: # 按钮按下时value为True高电平 storage.disable_usb_drive() print(“Boot: USB Drive disabled.”) # 这个打印会进入boot_out.txt else: print(“Boot: Button held, USB Drive remains enabled.”)这样在需要更新程序时你只需要按住按钮再给板子上电或复位CIRCUITPY盘符就会正常出现供你修改文件。松开按钮再复位它又会隐藏起来。注意事项storage.disable_usb_drive()只是让电脑无法通过USB访问这个存储在CircuitPython内部你依然可以通过文件系统API如open()读写CIRCUITPY上的文件。从CircuitPython 9.0.0开始当USB驱动被禁用时文件系统会自动对内部代码变为可读写。更早的版本可能需要手动调用storage.remount(“/”, readonlyFalse)。3.2 管理串口REPL与数据通道CircuitPython默认启用一个串行通信设备CDC它直接连接到Python的REPL交互式解释器。这对于调试至关重要但同样在产品中我们可能想关闭它或者需要额外的、纯净的数据通道。相关的模块是usb_cdcCommunications Device Class。它管理两个逻辑设备console: 连接REPL的串口。默认启用。data: 一个独立的、不与REPL交互的数据串口。默认禁用。import usb_cdc # 方案1完全禁用所有串口与usb_cdc.disable()等效 usb_cdc.enable(consoleFalse, dataFalse) # 方案2仅启用REPL控制台默认状态 usb_cdc.enable(consoleTrue, dataFalse) # 方案3同时启用控制台和数据端口非常有用 usb_cdc.enable(consoleTrue, dataTrue) # 方案4禁用控制台但启用数据端口用于纯数据产品 usb_cdc.enable(consoleFalse, dataTrue)为什么需要第二个数据端口想象你在做一个传感器数据记录器。你的code.py不断读取传感器并通过print()发送数据。如果使用默认的console端口所有数据都会混在REPL流里。更麻烦的是如果数据流中偶然出现了ASCII码3CtrlC主机端的串口工具会将其解释为中断信号可能打断你的接收程序。而data端口提供了一个干净的管道你可以用usb_cdc.data.write()发送任意二进制数据主机端用对应的COM端口接收完全不受REPL协议干扰。如何在主机端区分这两个端口当启用data端口后电脑上会出现两个串口设备名字可能很相似。这里推荐使用Adafruit提供的adafruit-board-toolkitPython库它可以帮助你精准定位。# 在电脑的终端/命令提示符中安装 pip3 install adafruit-board-toolkit# 在你的主机Python脚本中 import adafruit_board_toolkit.circuitpython_serial as cpy_serial # 获取所有连接到REPL的串口 repl_ports cpy_serial.repl_comports() print(“REPL ports:”, [p.device for p in repl_ports]) # 获取所有数据串口 data_ports cpy_serial.data_comports() print(“Data ports:”, [p.device for p in data_ports])3.3 管理MIDI设备USB MIDI设备默认在大多数板子上是启用的。如果你用不到音乐功能可以禁用它以节省USB资源。import usb_midi usb_midi.disable()一个重要的硬件兼容性问题在一些资源紧张的微控制器上如STM32F4 ESP32-S2/S3USB端点后面会详细讲数量有限MIDI默认可能是禁用的。如果你想启用它可能需要先禁用另一个设备来“腾地方”。import usb_hid, usb_midi # 在ESP32-S2上为了启用MIDI我们可能需要牺牲HID功能 usb_hid.disable() # 禁用所有键盘、鼠标等HID设备 usb_midi.enable() # 现在可以启用MIDI了4. 深入HID设备从使用到自定义HID人机接口设备是USB世界里最有趣的部分之一。它让你的CircuitPython板子可以模拟成键盘、鼠标、游戏手柄或者任何你想象得到的人机交互设备。4.1 标准HID设备与选择启用CircuitPython默认提供了三个HID设备usb_hid.Device.KEYBOARD: 标准键盘包含数字锁定灯等状态指示。usb_hid.Device.MOUSE: 标准鼠标支持最多5个按键和滚轮。usb_hid.Device.CONSUMER_CONTROL: 消费控制设备用于多媒体键播放/暂停、音量、浏览器快捷键等。你可以在boot.py中选择启用哪些import usb_hid # 启用全部三个默认设备这也是默认行为无需显式写出 usb_hid.enable( (usb_hid.Device.KEYBOARD, usb_hid.Device.MOUSE, usb_hid.Device.CONSUMER_CONTROL) ) # 只启用键盘适合做宏键盘 usb_hid.enable((usb_hid.Device.KEYBOARD,)) # 注意单个设备也要放在元组里 # 完全禁用所有HID设备 usb_hid.disable() # 或者 usb_hid.enable(()) # 启用一个空元组关于CONSUMER_CONTROL的实用技巧很多人不知道键盘上的音量加减、播放暂停这些键并不是通过普通的键盘键值发送的。它们走的是独立的Consumer Control通道。在adafruit_hid库中你可以找到ConsumerControlCode类来使用这些功能。这样做的好处是这些控制键是系统全局的不会干扰你正在输入文本的应用程序。4.2 创建自定义HID设备当标准设备不能满足需求时你就需要自定义HID设备了。这需要你提供两样东西HID报告描述符Report Descriptor一个用字节数组定义的、描述设备功能和数据格式的“蓝图”。一个驱动该设备的CircuitPython类用于生成符合描述符定义的数据报告。编写报告描述符是一门专业学问涉及对USB HID规范的深入理解。但对于我们大多数人来说更实用的方法是“借鉴”和“修改”。网络上有很多现成的描述符比如来自开源游戏手柄、绘图板的你可以直接拿来用。下面是一个自定义游戏手柄的描述符示例摘自原文但增加了详细注释import usb_hid # 这是一个支持16个按钮和4个模拟轴X,Y,Z,Rz的游戏手柄报告描述符 # 描述符是一个字节数组每个字节或每对字节都有特定含义 GAMEPAD_REPORT_DESCRIPTOR bytes(( 0x05, 0x01, # 用法页Generic Desktop - 声明这是一个通用桌面控制设备 0x09, 0x05, # 用法Game Pad - 进一步声明为游戏手柄 0xA1, 0x01, # 集合Application开始 - 定义一个应用集合 # 以下是集合内的内容 0x85, 0x04, # 报告ID (4) - 这个报告的ID是4用于复合设备中区分不同设备 0x05, 0x09, # 用法页Button - 这部分描述按钮 0x19, 0x01, # 用法最小值Button 1 0x29, 0x10, # 用法最大值Button 16 - 共16个按钮 0x15, 0x00, # 逻辑最小值0 - 按钮松开状态 0x25, 0x01, # 逻辑最大值1 - 按钮按下状态 0x75, 0x01, # 报告大小1 - 每个按钮用1个比特表示 0x95, 0x10, # 报告数量16 - 总共16个这样的比特 0x81, 0x02, # 输入Data, Var, Abs - 这些是主机从设备读取的数据 0x05, 0x01, # 用法页Generic Desktop - 切换回通用桌面描述模拟轴 0x15, 0x81, # 逻辑最小值-127 - 模拟轴的最小值 0x25, 0x7F, # 逻辑最大值127 - 模拟轴的最大值 0x09, 0x30, # 用法X - X轴 0x09, 0x31, # 用法Y - Y轴 0x09, 0x32, # 用法Z - Z轴通常作为第三个轴 0x09, 0x35, # 用法Rz - Rz轴绕Z轴旋转常作为第四个轴 0x75, 0x08, # 报告大小8 - 每个轴用1个字节8比特表示 0x95, 0x04, # 报告数量4 - 总共4个轴 0x81, 0x02, # 输入Data, Var, Abs - 这些也是输入数据 0xC0, # 集合结束 )) # 使用上面的描述符创建一个自定义HID设备对象 gamepad usb_hid.Device( report_descriptorGAMEPAD_REPORT_DESCRIPTOR, usage_page0x01, # 用法页通用桌面控制 (Generic Desktop) usage0x05, # 用法游戏手柄 (Game Pad) report_ids(4,), # 报告ID元组与描述符中的0x85, 0x04对应 in_report_lengths(6,), # 输入报告长度16个按钮2字节 4个轴4字节 6字节 out_report_lengths(0,), # 输出报告长度0字节这个手柄不从主机接收数据 ) # 启用标准设备加上我们的自定义游戏手柄 usb_hid.enable( (usb_hid.Device.KEYBOARD, usb_hid.Device.MOUSE, usb_hid.Device.CONSUMER_CONTROL, gamepad) # 将自定义设备加入元组 )关键参数解析report_ids: 在复合HID设备中每个子设备需要用唯一的报告ID来区分。这里设为(4,)。in_report_lengths: 指定发送给主机的报告Input Report的长度。这里一个报告是6字节。out_report_lengths: 指定从主机接收的报告Output Report的长度。对于只发送不接收的设备如简单手柄设为(0,)。创建好设备对象后你还需要编写相应的驱动代码来组装和发送报告。这通常需要你创建一个类根据按钮和摇杆的状态构造一个6字节的数组并通过usb_hid.devices找到你的设备进行发送。这部分代码相对复杂但adafruit_hid库中的现有设备类如Keyboard,Mouse是极好的参考。4.3 复合HID设备与端点管理当你像上面那样启用多个HID设备时CircuitPython会自动将它们合并成一个复合HID设备。这意味着从主机的角度看只连接了一个USB HID设备但这个设备内部包含了键盘、鼠标、自定义手柄等多个功能。它们共享一对USB端点一个IN一个OUT依靠不同的报告ID来区分彼此的数据包。什么是端点你可以把端点想象成USB设备上的“专用车道”。每条车道端点对负责运输一种特定类型的数据。HID设备共用一条车道MIDI用另一条每个CDC串口各用两条车道CIRCUITPY存储设备也用一条。微控制器芯片的USB硬件所能提供的“车道”总数是有限的这就是硬件端点限制。下表列出了常见微控制器的端点对数量不含控制端点0微控制器系列可用端点对数量典型代表芯片SAMD21 (M0)7Arduino Zero, Feather M0SAMD51 (M4)7Metro M4, Feather M4nRF528407Circuit Playground Bluefruit, ClueRP20407Raspberry Pi Pico, Feather RP2040STM32F43某些STM32F4开发板ESP32-S2/S34 (有效)ESP32-S2/S3开发板Spresense6 (固定分配)Sony Spresense端点需求计算CIRCUITPY(MSC): 需要1对端点。MIDI: 需要1对端点。CDC(串口):每个CDC设备需要2对端点一对控制一对数据。如果同时启用console和data则需要4对。HID(复合): 所有HID设备共享1对端点。一个典型的“满配”场景SAMD51开发板CIRCUITPY(1) MIDI(1) CDC consoledata(4) HID composite(1) 7对端点。刚好用完所有资源。一个受限制的场景ESP32-S3 它只有4对可用端点。如果你想同时使用CDC console和data4对那么CIRCUITPY、MIDI和HID就都无法启用了。你必须做出取舍例如只启用console2对这样还能再启用CIRCUITPY1对和HID1对。硬件选型建议如果你的项目需要丰富的USB功能比如同时需要存储、双串口和复杂的HID优先选择基于SAMD51、nRF52840或RP2040的板子它们提供了最宽松的端点资源。ESP32-S2/S3在无线功能上强大但在复杂USB应用上限制较大。5. 高级主题与疑难排解掌握了基本配置和自定义后我们来看看一些高级用法和开发中必然会踩的坑。5.1 Boot Keyboard/Mouse模式USB HID协议中有一个“Boot Protocol”子类。这是为了在计算机启动的最早期阶段比如在BIOS或引导加载程序界面操作系统还没有加载完整驱动时能有一个绝对标准的、极简的键盘或鼠标可以使用。CircuitPython的HID设备可以被标记为支持这种模式。import usb_hid # 创建一个支持Boot Protocol的键盘设备 boot_keyboard usb_hid.Device( # ... 其他参数 ... usage_page0x01, # Generic Desktop usage0x06, # Keyboard # 关键报告描述符必须符合Boot Protocol规范 # 通常可以直接使用库内置的这里仅为示意 ) # 在enable时这个设备会被特殊对待但是请谨慎使用根据社区反馈和原文提示Boot设备在某些主机上特别是macOS可能存在兼容性问题可能导致设备无法被正常识别。除非你的设备明确需要在BIOS环境下工作比如一个KVM切换器否则建议使用标准的HID协议。5.2 Windows HID设备清理难题在Windows上开发自定义HID设备是一场“持久战”。Windows系统会对连接过的HID设备缓存其报告描述符等信息。如果你在开发过程中修改了描述符比如从16键手柄改成18键Windows可能会固执地使用旧的缓存信息导致你的新设备无法正常工作。症状修改了boot.py中的报告描述符并复位后设备管理器里显示设备有叹号或者你的应用程序读不到正确的数据。解决方案拔掉你的CircuitPython设备。下载并运行USB Device Cleanup Tool由Uwe Sieber开发。这是一个轻量级工具可以列出并删除所有已断开连接的USB设备记录。在工具列表中找到与你设备相关的陈旧条目可能显示为未知设备或带有错误描述将其删除。重新插上你的设备让Windows重新安装驱动并缓存新的描述符。这个过程在迭代开发自定义HID描述符时可能会重复很多次养成每次大改描述符后都清理一下的习惯能节省大量调试时间。5.3 Linux下的特殊问题原文提到了一个Linux特有的问题如果你只启用一个自定义的游戏手柄设备并且没有其他标准HID设备在某些Linux发行版上可能会导致USB枚举失败出现“USB busy”错误。根本原因Linux的HID驱动对某些单一功能的HID设备处理逻辑可能与Windows/macOS不同。解决方案Workaround很简单在启用你的自定义设备时至少再附带一个标准的HID设备比如鼠标。# 在Linux上不要只启用一个自定义游戏手柄 # usb_hid.enable((gamepad,)) # 这可能在某些Linux系统上失败 # 正确的做法附带一个标准设备 usb_hid.enable((gamepad, usb_hid.Device.MOUSE)) # 启用游戏手柄和鼠标这样就能保证复合HID设备被正确识别。在你的应用代码中你只需要使用游戏手柄部分忽略鼠标即可。5.4 错误排查与安全模式当你的boot.py配置要求了超过硬件支持的端点数量时CircuitPython会在启动时进入安全模式。现象板子上的LED可能呈现特定颜色闪烁模式如黄色CIRCUITPY盘符可能出现也可能不出现code.py根本不会运行。如何诊断连接串口终端REPL你会看到类似这样的错误信息Auto-reload is on. Simply save files over USB to run them or enter REPL to disable. Code done running. Waiting for reload. Press any key to enter the REPL. Use CTRL-D to reload. Safe mode: USB devices need more endpoints than are available.这明确告诉你USB设备需要的端点超过了可用数量。你需要返回boot.py精简你的配置例如禁用MIDI或CIRCUITPY或者将两个CDC串口减少为一个。另一个常见错误来源是boot.py本身的语法或运行时错误。这些错误不会显示在串口终端因为USB还没初始化而是被记录在CIRCUITPY根目录下的boot_out.txt文件中。每次硬复位后这个文件都会被覆盖。所以如果你的设备行为异常第一件事就是检查这个文件。6. 完整实战构建一个“隐身”的宏键盘让我们把所有知识串联起来完成一个实战项目一个基于CircuitPython的宏键盘它在正常工作时完全“隐身”不显示CIRCUITPY和REPL只有按住一个特定按钮启动时才会进入配置模式。硬件Adafruit KB2040RP2040芯片自带按键矩阵支持或任何带有足够GPIO和按钮的板子。目标默认状态下设备模拟一个标准键盘和消费控制设备。CIRCUITPY和REPL串口默认禁用使设备在电脑上只显示为一个键盘。通过按住BOOT按钮或自定义按钮上电可以进入配置模式此时CIRCUITPY和REPL启用方便更新脚本。利用消费控制键实现多媒体功能。boot.py配置import board import digitalio import storage import usb_cdc import usb_hid import usb_midi # --- 硬件初始化 --- # 使用板载的BOOT按钮在KB2040上通常是GP7按下为低电平 config_button digitalio.DigitalInOut(board.BOOT) # 请根据你的板子修改引脚 config_button.switch_to_input(pulldigitalio.Pull.UP) # 启用内部上拉电阻 # --- USB设备配置逻辑 --- # 检测按钮是否被按下 button_pressed not config_button.value # 按下时value为False if button_pressed: # **配置模式**按钮按下启用所有开发接口 print(“Boot: Configuration mode enabled. USB drive and REPL ON.”) # storage 和 usb_cdc 默认就是启用的我们无需额外操作 # 但为了清晰可以显式启用虽然默认就是True # storage.enable_usb_drive() # 默认已启用 # usb_cdc.enable(consoleTrue, dataFalse) # 默认已启用console else: # **正常运行模式**按钮未按下隐藏开发接口只保留HID print(“Boot: Normal operation mode. HID only.”) storage.disable_usb_drive() usb_cdc.disable() # 禁用REPL串口 # --- HID设备配置两种模式都需要--- # 我们始终启用键盘和消费控制设备禁用鼠标因为我们用不到 # 这样可以节省一点点资源并避免某些电脑因检测到鼠标而禁用触摸板 usb_hid.enable( (usb_hid.Device.KEYBOARD, usb_hid.Device.CONSUMER_CONTROL,) # 注意我们移除了 MOUSE ) # --- MIDI设备配置我们不需要禁用--- usb_midi.disable() # 打印最终配置状态信息会写入boot_out.txt print(“Boot: HID devices configured.”) print(“Boot: Configuration button state:”, button_pressed)code.py主程序示例import time import board import keypad import usb_hid from adafruit_hid.keyboard import Keyboard from adafruit_hid.keycode import Keycode from adafruit_hid.consumer_control import ConsumerControl from adafruit_hid.consumer_control_code import ConsumerControlCode # 初始化键盘和消费控制对象 kbd Keyboard(usb_hid.devices) cc ConsumerControl(usb_hid.devices) # 假设我们连接了一个2x2的按键矩阵引脚为ROW1, ROW2, COL1, COL2 # 请根据实际硬件连接修改 rows [board.GP0, board.GP1] cols [board.GP2, board.GP3] keys keypad.KeyMatrix(rows, cols, value_when_pressedFalse) # 定义每个按键的功能 (0,0), (0,1), (1,0), (1,1) key_actions [ (Keycode.CONTROL, Keycode.C), # 复制 (Keycode.CONTROL, Keycode.V), # 粘贴 ConsumerControlCode.VOLUME_DECREMENT, # 音量减 ConsumerControlCode.PLAY_PAUSE, # 播放/暂停 ] print(“Macro Pad Started!”) # 这个print在正常模式下看不到因为REPL被禁用了 while True: event keys.events.get() if event: key_index event.key_number if event.pressed: action key_actions[key_index] if isinstance(action, tuple): # 键盘组合键 kbd.press(*action) else: # 消费控制键 cc.send(action) else: # 按键释放 action key_actions[key_index] if isinstance(action, tuple): kbd.release(*action) # 消费控制键无需释放动作 time.sleep(0.01)项目总结与要点双重模式通过boot.py中的按钮检测实现了产品模式与开发模式的无缝切换这是产品化项目的必备设计。资源优化禁用了不需要的鼠标和MIDI设备为未来可能的功能扩展留出了端点资源。功能实现在code.py中结合adafruit_hid库轻松实现了键盘宏和多媒体控制功能。注意消费控制键的使用方式与普通键盘键不同。调试在正常模式下所有print()输出都不可见。调试时需要按住按钮进入配置模式或者通过额外的硬件如LED来指示状态。通过这个完整的流程你可以将一个通用的CircuitPython开发板转变为一个行为可控、用户体验专业的USB外设。从基础的设备显隐控制到复杂的自定义HID设备开发再到跨平台的疑难排解这套组合拳足以应对大多数基于USB的嵌入式Python项目。记住关键始终在于理解USB资源的有限性并在boot.py这个唯一的配置窗口内做好精细的规划和容错设计。
CircuitPython USB设备自定义：从boot.py配置到HID开发实战
发布时间：2026/5/15 22:06:23
1. 项目概述如果你玩过CircuitPython大概率对插上USB线后电脑上自动弹出的CIRCUITPY盘符和串口终端不陌生。这很方便让你能像操作U盘一样拖拽代码文件也能随时打开串口监视器查看打印信息。但当你真正想把手里的开发板变成一个“正经”的USB设备比如一个专属的宏键盘、一个游戏手柄或者一个不希望被用户随意修改内部文件的数据采集器时这些默认出现的“开发工具”就显得有些碍眼了。它们不仅占用了系统资源更关键的是会让你的最终产品在用户电脑上看起来像个半成品开发板而不是一个独立、专业的设备。这正是CircuitPython USB设备自定义的核心价值所在。它允许你作为一名开发者在boot.py这个特殊的启动脚本中像导演一样编排你的开发板在USB舞台上的“角色”。你可以让存储设备CIRCUITPY在演出时“隐身”可以关闭那个用于调试的串口终端REPL甚至可以启用第二个纯粹的、不受干扰的数据串口。更进一步你还能定义全新的、符合USB HID标准的自定义设备比如一个带有特殊摇杆和按钮布局的游戏手柄或者一个工业用的控制面板。这个过程不仅仅是开关几个功能它涉及到对USB底层机制的理解比如“端点”这个硬件资源的分配以及如何编写描述设备能力的“报告描述符”。本篇文章我将结合自己多次将CircuitPython项目产品化的经验从最基础的配置讲起一直深入到自定义HID设备的开发帮你彻底掌握如何让你的CircuitPython设备在USB世界里表现得既专业又高效。2. 核心概念与boot.py的绝对权威在开始动手修改之前我们必须建立一个最重要的认知所有USB设备的配置都必须且只能在boot.py文件中进行。这是CircuitPython设计上的一个铁律理解其背后的“为什么”能帮你避开无数坑。2.1 为什么必须是boot.py你可以把开发板连接电脑的过程想象成一次外交会晤。boot.py运行于会晤开始前的“内部筹备会议”阶段。在这个阶段你的开发板还没有和电脑主机建立任何正式的USB通信连接。此时你可以从容地决定这次会晤要派出哪些“代表”USB设备以及每个代表的“职权范围”设备描述符。一旦boot.py执行完毕CircuitPython就会根据你的配置生成一份完整的“外交人员名单和设备能力说明书”即USB描述符集。紧接着开发板才会正式向电脑“亮明身份”开始枚举过程。电脑会读取这份说明书并为每一个设备分配资源、安装驱动。而你的主程序code.py则是在枚举过程开始后才启动的。此时USB连接的“外交框架”已经确立木已成舟。如果你试图在code.py中调用storage.disable_usb_drive()CircuitPython会直接抛出一个错误因为USB大容量存储设备这个“代表”已经在会晤中开始工作了你无法中途将其撤下。实操心得我早期就犯过在code.py里尝试禁用设备的错误结果程序直接崩溃。记住这个顺序硬件复位 -boot.py执行配置USB- USB枚举 -code.py执行。任何想动态切换USB设备功能比如运行时让CIRCUITPY出现又消失的需求在标准CircuitPython下是无法实现的必须在设计之初就在boot.py里定死。2.2 硬复位与文件写入完成与boot.py的权威性紧密相关的另一个关键点是boot.py只在硬复位Hard Reset后运行。什么是硬复位就是你给板子重新上电或者按下了物理的复位RESET按钮。在REPL里输入CtrlD进行软复位或者只是修改并保存了boot.py文件都不会触发boot.py的重新执行。这带来一个非常重要的操作流程每次修改boot.py后你必须执行一次硬复位新的配置才会生效。而且在复位前你必须确保修改已经完全写入板载的存储中。避坑指南CircuitPython的文件写入有时不是立即完成的特别是当你通过某些编辑器或IDE保存时可能会有缓存。最稳妥的做法是在编辑完boot.py后在文件管理器中对CIRCUITPY盘执行一次“弹出”或“安全移除硬件”操作。等待系统提示“可以安全移除硬件”后再按复位键。我曾经因为没等写入完成就复位导致boot.py文件损坏整个文件系统需要重新格式化项目代码全丢。3. 基础设备管理隐藏、显示与串口倍增掌握了boot.py的运作机制我们就可以开始实操了。我们从最简单的开始管理那些CircuitPython默认提供的标准设备。3.1 让CIRCUITPY盘符消失对于要作为成品交付的设备让内部的文件系统对用户不可见是基本要求。这能防止用户误删或修改关键文件也让设备看起来更专业。import storage storage.disable_usb_drive() # 这行代码会让CIRCUITPY盘符在电脑上消失就这么简单。但这里藏着一个巨大的“陷阱”原文也用了醒目的警告不要只写这一行试想你写了一个boot.py里面只有storage.disable_usb_drive()。你把它放到板子上复位。好了CIRCUITPY盘符不见了你的程序code.py开始运行设备工作正常。但有一天你需要更新code.py里的逻辑或者修复一个bug你该怎么办你没有任何办法再把CIRCUITPY弄出来因为你无法修改boot.py了——它所在的盘符根本看不见这就是所谓的“把自己锁在外面”。为了避免这种情况你必须设计一个“逃生舱”机制。最常见的做法是使用一个硬件按钮。在boot.py中检测这个按钮的状态如果按钮没有被按下则禁用设备如果检测到按钮被按下则保持设备启用。import storage import board import digitalio # 假设我们使用板载的按钮A按下时连接到高电平如Circuit Playground Express button digitalio.DigitalInOut(board.BUTTON_A) button.switch_to_input(pulldigitalio.Pull.DOWN) # 启用内部下拉电阻 # 仅当按钮未被按下时才禁用USB存储 if not button.value: # 按钮按下时value为True高电平 storage.disable_usb_drive() print(“Boot: USB Drive disabled.”) # 这个打印会进入boot_out.txt else: print(“Boot: Button held, USB Drive remains enabled.”)这样在需要更新程序时你只需要按住按钮再给板子上电或复位CIRCUITPY盘符就会正常出现供你修改文件。松开按钮再复位它又会隐藏起来。注意事项storage.disable_usb_drive()只是让电脑无法通过USB访问这个存储在CircuitPython内部你依然可以通过文件系统API如open()读写CIRCUITPY上的文件。从CircuitPython 9.0.0开始当USB驱动被禁用时文件系统会自动对内部代码变为可读写。更早的版本可能需要手动调用storage.remount(“/”, readonlyFalse)。3.2 管理串口REPL与数据通道CircuitPython默认启用一个串行通信设备CDC它直接连接到Python的REPL交互式解释器。这对于调试至关重要但同样在产品中我们可能想关闭它或者需要额外的、纯净的数据通道。相关的模块是usb_cdcCommunications Device Class。它管理两个逻辑设备console: 连接REPL的串口。默认启用。data: 一个独立的、不与REPL交互的数据串口。默认禁用。import usb_cdc # 方案1完全禁用所有串口与usb_cdc.disable()等效 usb_cdc.enable(consoleFalse, dataFalse) # 方案2仅启用REPL控制台默认状态 usb_cdc.enable(consoleTrue, dataFalse) # 方案3同时启用控制台和数据端口非常有用 usb_cdc.enable(consoleTrue, dataTrue) # 方案4禁用控制台但启用数据端口用于纯数据产品 usb_cdc.enable(consoleFalse, dataTrue)为什么需要第二个数据端口想象你在做一个传感器数据记录器。你的code.py不断读取传感器并通过print()发送数据。如果使用默认的console端口所有数据都会混在REPL流里。更麻烦的是如果数据流中偶然出现了ASCII码3CtrlC主机端的串口工具会将其解释为中断信号可能打断你的接收程序。而data端口提供了一个干净的管道你可以用usb_cdc.data.write()发送任意二进制数据主机端用对应的COM端口接收完全不受REPL协议干扰。如何在主机端区分这两个端口当启用data端口后电脑上会出现两个串口设备名字可能很相似。这里推荐使用Adafruit提供的adafruit-board-toolkitPython库它可以帮助你精准定位。# 在电脑的终端/命令提示符中安装 pip3 install adafruit-board-toolkit# 在你的主机Python脚本中 import adafruit_board_toolkit.circuitpython_serial as cpy_serial # 获取所有连接到REPL的串口 repl_ports cpy_serial.repl_comports() print(“REPL ports:”, [p.device for p in repl_ports]) # 获取所有数据串口 data_ports cpy_serial.data_comports() print(“Data ports:”, [p.device for p in data_ports])3.3 管理MIDI设备USB MIDI设备默认在大多数板子上是启用的。如果你用不到音乐功能可以禁用它以节省USB资源。import usb_midi usb_midi.disable()一个重要的硬件兼容性问题在一些资源紧张的微控制器上如STM32F4 ESP32-S2/S3USB端点后面会详细讲数量有限MIDI默认可能是禁用的。如果你想启用它可能需要先禁用另一个设备来“腾地方”。import usb_hid, usb_midi # 在ESP32-S2上为了启用MIDI我们可能需要牺牲HID功能 usb_hid.disable() # 禁用所有键盘、鼠标等HID设备 usb_midi.enable() # 现在可以启用MIDI了4. 深入HID设备从使用到自定义HID人机接口设备是USB世界里最有趣的部分之一。它让你的CircuitPython板子可以模拟成键盘、鼠标、游戏手柄或者任何你想象得到的人机交互设备。4.1 标准HID设备与选择启用CircuitPython默认提供了三个HID设备usb_hid.Device.KEYBOARD: 标准键盘包含数字锁定灯等状态指示。usb_hid.Device.MOUSE: 标准鼠标支持最多5个按键和滚轮。usb_hid.Device.CONSUMER_CONTROL: 消费控制设备用于多媒体键播放/暂停、音量、浏览器快捷键等。你可以在boot.py中选择启用哪些import usb_hid # 启用全部三个默认设备这也是默认行为无需显式写出 usb_hid.enable( (usb_hid.Device.KEYBOARD, usb_hid.Device.MOUSE, usb_hid.Device.CONSUMER_CONTROL) ) # 只启用键盘适合做宏键盘 usb_hid.enable((usb_hid.Device.KEYBOARD,)) # 注意单个设备也要放在元组里 # 完全禁用所有HID设备 usb_hid.disable() # 或者 usb_hid.enable(()) # 启用一个空元组关于CONSUMER_CONTROL的实用技巧很多人不知道键盘上的音量加减、播放暂停这些键并不是通过普通的键盘键值发送的。它们走的是独立的Consumer Control通道。在adafruit_hid库中你可以找到ConsumerControlCode类来使用这些功能。这样做的好处是这些控制键是系统全局的不会干扰你正在输入文本的应用程序。4.2 创建自定义HID设备当标准设备不能满足需求时你就需要自定义HID设备了。这需要你提供两样东西HID报告描述符Report Descriptor一个用字节数组定义的、描述设备功能和数据格式的“蓝图”。一个驱动该设备的CircuitPython类用于生成符合描述符定义的数据报告。编写报告描述符是一门专业学问涉及对USB HID规范的深入理解。但对于我们大多数人来说更实用的方法是“借鉴”和“修改”。网络上有很多现成的描述符比如来自开源游戏手柄、绘图板的你可以直接拿来用。下面是一个自定义游戏手柄的描述符示例摘自原文但增加了详细注释import usb_hid # 这是一个支持16个按钮和4个模拟轴X,Y,Z,Rz的游戏手柄报告描述符 # 描述符是一个字节数组每个字节或每对字节都有特定含义 GAMEPAD_REPORT_DESCRIPTOR bytes(( 0x05, 0x01, # 用法页Generic Desktop - 声明这是一个通用桌面控制设备 0x09, 0x05, # 用法Game Pad - 进一步声明为游戏手柄 0xA1, 0x01, # 集合Application开始 - 定义一个应用集合 # 以下是集合内的内容 0x85, 0x04, # 报告ID (4) - 这个报告的ID是4用于复合设备中区分不同设备 0x05, 0x09, # 用法页Button - 这部分描述按钮 0x19, 0x01, # 用法最小值Button 1 0x29, 0x10, # 用法最大值Button 16 - 共16个按钮 0x15, 0x00, # 逻辑最小值0 - 按钮松开状态 0x25, 0x01, # 逻辑最大值1 - 按钮按下状态 0x75, 0x01, # 报告大小1 - 每个按钮用1个比特表示 0x95, 0x10, # 报告数量16 - 总共16个这样的比特 0x81, 0x02, # 输入Data, Var, Abs - 这些是主机从设备读取的数据 0x05, 0x01, # 用法页Generic Desktop - 切换回通用桌面描述模拟轴 0x15, 0x81, # 逻辑最小值-127 - 模拟轴的最小值 0x25, 0x7F, # 逻辑最大值127 - 模拟轴的最大值 0x09, 0x30, # 用法X - X轴 0x09, 0x31, # 用法Y - Y轴 0x09, 0x32, # 用法Z - Z轴通常作为第三个轴 0x09, 0x35, # 用法Rz - Rz轴绕Z轴旋转常作为第四个轴 0x75, 0x08, # 报告大小8 - 每个轴用1个字节8比特表示 0x95, 0x04, # 报告数量4 - 总共4个轴 0x81, 0x02, # 输入Data, Var, Abs - 这些也是输入数据 0xC0, # 集合结束 )) # 使用上面的描述符创建一个自定义HID设备对象 gamepad usb_hid.Device( report_descriptorGAMEPAD_REPORT_DESCRIPTOR, usage_page0x01, # 用法页通用桌面控制 (Generic Desktop) usage0x05, # 用法游戏手柄 (Game Pad) report_ids(4,), # 报告ID元组与描述符中的0x85, 0x04对应 in_report_lengths(6,), # 输入报告长度16个按钮2字节 4个轴4字节 6字节 out_report_lengths(0,), # 输出报告长度0字节这个手柄不从主机接收数据 ) # 启用标准设备加上我们的自定义游戏手柄 usb_hid.enable( (usb_hid.Device.KEYBOARD, usb_hid.Device.MOUSE, usb_hid.Device.CONSUMER_CONTROL, gamepad) # 将自定义设备加入元组 )关键参数解析report_ids: 在复合HID设备中每个子设备需要用唯一的报告ID来区分。这里设为(4,)。in_report_lengths: 指定发送给主机的报告Input Report的长度。这里一个报告是6字节。out_report_lengths: 指定从主机接收的报告Output Report的长度。对于只发送不接收的设备如简单手柄设为(0,)。创建好设备对象后你还需要编写相应的驱动代码来组装和发送报告。这通常需要你创建一个类根据按钮和摇杆的状态构造一个6字节的数组并通过usb_hid.devices找到你的设备进行发送。这部分代码相对复杂但adafruit_hid库中的现有设备类如Keyboard,Mouse是极好的参考。4.3 复合HID设备与端点管理当你像上面那样启用多个HID设备时CircuitPython会自动将它们合并成一个复合HID设备。这意味着从主机的角度看只连接了一个USB HID设备但这个设备内部包含了键盘、鼠标、自定义手柄等多个功能。它们共享一对USB端点一个IN一个OUT依靠不同的报告ID来区分彼此的数据包。什么是端点你可以把端点想象成USB设备上的“专用车道”。每条车道端点对负责运输一种特定类型的数据。HID设备共用一条车道MIDI用另一条每个CDC串口各用两条车道CIRCUITPY存储设备也用一条。微控制器芯片的USB硬件所能提供的“车道”总数是有限的这就是硬件端点限制。下表列出了常见微控制器的端点对数量不含控制端点0微控制器系列可用端点对数量典型代表芯片SAMD21 (M0)7Arduino Zero, Feather M0SAMD51 (M4)7Metro M4, Feather M4nRF528407Circuit Playground Bluefruit, ClueRP20407Raspberry Pi Pico, Feather RP2040STM32F43某些STM32F4开发板ESP32-S2/S34 (有效)ESP32-S2/S3开发板Spresense6 (固定分配)Sony Spresense端点需求计算CIRCUITPY(MSC): 需要1对端点。MIDI: 需要1对端点。CDC(串口):每个CDC设备需要2对端点一对控制一对数据。如果同时启用console和data则需要4对。HID(复合): 所有HID设备共享1对端点。一个典型的“满配”场景SAMD51开发板CIRCUITPY(1) MIDI(1) CDC consoledata(4) HID composite(1) 7对端点。刚好用完所有资源。一个受限制的场景ESP32-S3 它只有4对可用端点。如果你想同时使用CDC console和data4对那么CIRCUITPY、MIDI和HID就都无法启用了。你必须做出取舍例如只启用console2对这样还能再启用CIRCUITPY1对和HID1对。硬件选型建议如果你的项目需要丰富的USB功能比如同时需要存储、双串口和复杂的HID优先选择基于SAMD51、nRF52840或RP2040的板子它们提供了最宽松的端点资源。ESP32-S2/S3在无线功能上强大但在复杂USB应用上限制较大。5. 高级主题与疑难排解掌握了基本配置和自定义后我们来看看一些高级用法和开发中必然会踩的坑。5.1 Boot Keyboard/Mouse模式USB HID协议中有一个“Boot Protocol”子类。这是为了在计算机启动的最早期阶段比如在BIOS或引导加载程序界面操作系统还没有加载完整驱动时能有一个绝对标准的、极简的键盘或鼠标可以使用。CircuitPython的HID设备可以被标记为支持这种模式。import usb_hid # 创建一个支持Boot Protocol的键盘设备 boot_keyboard usb_hid.Device( # ... 其他参数 ... usage_page0x01, # Generic Desktop usage0x06, # Keyboard # 关键报告描述符必须符合Boot Protocol规范 # 通常可以直接使用库内置的这里仅为示意 ) # 在enable时这个设备会被特殊对待但是请谨慎使用根据社区反馈和原文提示Boot设备在某些主机上特别是macOS可能存在兼容性问题可能导致设备无法被正常识别。除非你的设备明确需要在BIOS环境下工作比如一个KVM切换器否则建议使用标准的HID协议。5.2 Windows HID设备清理难题在Windows上开发自定义HID设备是一场“持久战”。Windows系统会对连接过的HID设备缓存其报告描述符等信息。如果你在开发过程中修改了描述符比如从16键手柄改成18键Windows可能会固执地使用旧的缓存信息导致你的新设备无法正常工作。症状修改了boot.py中的报告描述符并复位后设备管理器里显示设备有叹号或者你的应用程序读不到正确的数据。解决方案拔掉你的CircuitPython设备。下载并运行USB Device Cleanup Tool由Uwe Sieber开发。这是一个轻量级工具可以列出并删除所有已断开连接的USB设备记录。在工具列表中找到与你设备相关的陈旧条目可能显示为未知设备或带有错误描述将其删除。重新插上你的设备让Windows重新安装驱动并缓存新的描述符。这个过程在迭代开发自定义HID描述符时可能会重复很多次养成每次大改描述符后都清理一下的习惯能节省大量调试时间。5.3 Linux下的特殊问题原文提到了一个Linux特有的问题如果你只启用一个自定义的游戏手柄设备并且没有其他标准HID设备在某些Linux发行版上可能会导致USB枚举失败出现“USB busy”错误。根本原因Linux的HID驱动对某些单一功能的HID设备处理逻辑可能与Windows/macOS不同。解决方案Workaround很简单在启用你的自定义设备时至少再附带一个标准的HID设备比如鼠标。# 在Linux上不要只启用一个自定义游戏手柄 # usb_hid.enable((gamepad,)) # 这可能在某些Linux系统上失败 # 正确的做法附带一个标准设备 usb_hid.enable((gamepad, usb_hid.Device.MOUSE)) # 启用游戏手柄和鼠标这样就能保证复合HID设备被正确识别。在你的应用代码中你只需要使用游戏手柄部分忽略鼠标即可。5.4 错误排查与安全模式当你的boot.py配置要求了超过硬件支持的端点数量时CircuitPython会在启动时进入安全模式。现象板子上的LED可能呈现特定颜色闪烁模式如黄色CIRCUITPY盘符可能出现也可能不出现code.py根本不会运行。如何诊断连接串口终端REPL你会看到类似这样的错误信息Auto-reload is on. Simply save files over USB to run them or enter REPL to disable. Code done running. Waiting for reload. Press any key to enter the REPL. Use CTRL-D to reload. Safe mode: USB devices need more endpoints than are available.这明确告诉你USB设备需要的端点超过了可用数量。你需要返回boot.py精简你的配置例如禁用MIDI或CIRCUITPY或者将两个CDC串口减少为一个。另一个常见错误来源是boot.py本身的语法或运行时错误。这些错误不会显示在串口终端因为USB还没初始化而是被记录在CIRCUITPY根目录下的boot_out.txt文件中。每次硬复位后这个文件都会被覆盖。所以如果你的设备行为异常第一件事就是检查这个文件。6. 完整实战构建一个“隐身”的宏键盘让我们把所有知识串联起来完成一个实战项目一个基于CircuitPython的宏键盘它在正常工作时完全“隐身”不显示CIRCUITPY和REPL只有按住一个特定按钮启动时才会进入配置模式。硬件Adafruit KB2040RP2040芯片自带按键矩阵支持或任何带有足够GPIO和按钮的板子。目标默认状态下设备模拟一个标准键盘和消费控制设备。CIRCUITPY和REPL串口默认禁用使设备在电脑上只显示为一个键盘。通过按住BOOT按钮或自定义按钮上电可以进入配置模式此时CIRCUITPY和REPL启用方便更新脚本。利用消费控制键实现多媒体功能。boot.py配置import board import digitalio import storage import usb_cdc import usb_hid import usb_midi # --- 硬件初始化 --- # 使用板载的BOOT按钮在KB2040上通常是GP7按下为低电平 config_button digitalio.DigitalInOut(board.BOOT) # 请根据你的板子修改引脚 config_button.switch_to_input(pulldigitalio.Pull.UP) # 启用内部上拉电阻 # --- USB设备配置逻辑 --- # 检测按钮是否被按下 button_pressed not config_button.value # 按下时value为False if button_pressed: # **配置模式**按钮按下启用所有开发接口 print(“Boot: Configuration mode enabled. USB drive and REPL ON.”) # storage 和 usb_cdc 默认就是启用的我们无需额外操作 # 但为了清晰可以显式启用虽然默认就是True # storage.enable_usb_drive() # 默认已启用 # usb_cdc.enable(consoleTrue, dataFalse) # 默认已启用console else: # **正常运行模式**按钮未按下隐藏开发接口只保留HID print(“Boot: Normal operation mode. HID only.”) storage.disable_usb_drive() usb_cdc.disable() # 禁用REPL串口 # --- HID设备配置两种模式都需要--- # 我们始终启用键盘和消费控制设备禁用鼠标因为我们用不到 # 这样可以节省一点点资源并避免某些电脑因检测到鼠标而禁用触摸板 usb_hid.enable( (usb_hid.Device.KEYBOARD, usb_hid.Device.CONSUMER_CONTROL,) # 注意我们移除了 MOUSE ) # --- MIDI设备配置我们不需要禁用--- usb_midi.disable() # 打印最终配置状态信息会写入boot_out.txt print(“Boot: HID devices configured.”) print(“Boot: Configuration button state:”, button_pressed)code.py主程序示例import time import board import keypad import usb_hid from adafruit_hid.keyboard import Keyboard from adafruit_hid.keycode import Keycode from adafruit_hid.consumer_control import ConsumerControl from adafruit_hid.consumer_control_code import ConsumerControlCode # 初始化键盘和消费控制对象 kbd Keyboard(usb_hid.devices) cc ConsumerControl(usb_hid.devices) # 假设我们连接了一个2x2的按键矩阵引脚为ROW1, ROW2, COL1, COL2 # 请根据实际硬件连接修改 rows [board.GP0, board.GP1] cols [board.GP2, board.GP3] keys keypad.KeyMatrix(rows, cols, value_when_pressedFalse) # 定义每个按键的功能 (0,0), (0,1), (1,0), (1,1) key_actions [ (Keycode.CONTROL, Keycode.C), # 复制 (Keycode.CONTROL, Keycode.V), # 粘贴 ConsumerControlCode.VOLUME_DECREMENT, # 音量减 ConsumerControlCode.PLAY_PAUSE, # 播放/暂停 ] print(“Macro Pad Started!”) # 这个print在正常模式下看不到因为REPL被禁用了 while True: event keys.events.get() if event: key_index event.key_number if event.pressed: action key_actions[key_index] if isinstance(action, tuple): # 键盘组合键 kbd.press(*action) else: # 消费控制键 cc.send(action) else: # 按键释放 action key_actions[key_index] if isinstance(action, tuple): kbd.release(*action) # 消费控制键无需释放动作 time.sleep(0.01)项目总结与要点双重模式通过boot.py中的按钮检测实现了产品模式与开发模式的无缝切换这是产品化项目的必备设计。资源优化禁用了不需要的鼠标和MIDI设备为未来可能的功能扩展留出了端点资源。功能实现在code.py中结合adafruit_hid库轻松实现了键盘宏和多媒体控制功能。注意消费控制键的使用方式与普通键盘键不同。调试在正常模式下所有print()输出都不可见。调试时需要按住按钮进入配置模式或者通过额外的硬件如LED来指示状态。通过这个完整的流程你可以将一个通用的CircuitPython开发板转变为一个行为可控、用户体验专业的USB外设。从基础的设备显隐控制到复杂的自定义HID设备开发再到跨平台的疑难排解这套组合拳足以应对大多数基于USB的嵌入式Python项目。记住关键始终在于理解USB资源的有限性并在boot.py这个唯一的配置窗口内做好精细的规划和容错设计。
相关文章
跨境电商怎么入门？2026 5月零基础完整教程｜7步掌握从选品到出单的核心流程
摘要 本文面向零基础新手，系统拆解跨境电商从市场调研、平台选择、选品策略到物流支付的全流程。读完你将掌握一套可落地的入门方法论，避开常见的封号、侵权、压货三大坑，直接上手操作。 一、开篇引入 跨境电商，简单说就是把中国…
极简主义提示工程白皮书（含Adobe+Midjourney双平台对照表｜限免领取倒计时48h）
更多请点击： https://intelliparadigm.com 第一章：极简主义提示工程的核心范式 什么是极简主义提示工程 极简主义提示工程（Minimalist Prompt Engineering）主张以最少的词汇、最清晰的结构和最明确的意图驱动大语言模型输出。它…
【Transformer系列】从One-Hot到Embedding：构建AI语言理解的基石
1. 从One-Hot编码说起：AI的第一堂语言课 想象你正在教一个外星人认识汉字。你拿出一本字典说："这里有10万个字，每个字对应一个编号，猫是第12345号，狗是第67890号。"这就是最原始的One-Hot编码思想——用一串…
GanttProject完全指南：免费开源工具如何帮你轻松管理复杂项目
GanttProject完全指南：免费开源工具如何帮你轻松管理复杂项目 【免费下载链接】ganttproject Official GanttProject repository. 项目地址: https://gitcode.com/gh_mirrors/ga/ganttproject 在项目管理领域，专业工具往往价格昂贵且学习曲线陡峭…
终极指南：如何高效容器化部署PostgreSQL - 多阶段构建与镜像瘦身实践
终极指南：如何高效容器化部署PostgreSQL - 多阶段构建与镜像瘦身实践 【免费下载链接】awesome-postgres A curated list of awesome PostgreSQL software, libraries, tools and resources, inspired by awesome-mysql 项目地址: https://gitcode.com/gh_mirrors…
掌握Lua的基本数据类型：入门必备基础
Lua与宿主程序之间的关系：可以嵌入到宿主程序，并为宿主程序提供脚本能力，同时可以帮助拓展宿主程序。另外Lua也提供了一些工具帮助编译Lua文本（luac），执行lua脚本（lua）以下介绍时都是…
【linux】基础开发工具（3）gcc/g++，动静态库
c/c源代码到可执行程序“四级跳”作为c/c开发者，理解编译的过程至关重要，理解c/c从代码一步步编译成可执行程序的过程是我们学习的必经之路。从 .c/.cpp 源代码到可执行程序，需经历预处理、编译、汇编、链接四个阶段，每一步都决定…
【招聘】福特换帅的真相，没有人敢直说
福特换帅的真相，没有人敢直说最近重读了艾伦穆拉利拯救福特的故事。 所有的商业媒体，都在讲他的战略多么高明，One Ford多么伟大，融资多么前瞻，文化变革多么成功。 我讲一个不一样的版本。 我讲人。一、亨利福特&#x…
OfficeClaw：Python混合自动化方案，解决Office GUI交互难题
1. 项目概述：一个被低估的办公自动化利器如果你在日常工作中，经常需要和Word、Excel、PowerPoint这些Office文档打交道，并且厌倦了手动、重复的点击操作，那么你很可能已经听说过或尝试过各种自动化方案。从宏录制到VBA，…
【2026】新高考英语大纲词汇表3500个电子版PDF（含正序版、乱序版和默写版）
高中英语大纲词汇表（2026年版）内容说明 词汇收录标准 严格遵循高中英语教学大纲要求，精选3500个核心词汇，全面覆盖高中阶段英语学习的基础词汇与进阶词汇。 版本分类及功能 版本类型编排特点主要功能正序版按字母顺序排列系统…
【最新v2.7.1 版本】零代码无命令！OpenClaw 零基础快速部署保姆级实战教程
OpenClaw（小龙虾）Windows 一键部署保姆级教程 | 10 分钟搭建专属数字员工 前言 2026 年开源圈热门 AI 智能体 OpenClaw（昵称小龙虾），GitHub 星标突破 28 万，凭借本地运行 零代码操作 智能自动执行收获大…
别再只用HashMap了！用Java BitSet和布隆过滤器处理亿级数据去重，内存省了90%
亿级数据去重的终极武器：Java BitSet与布隆过滤器实战手册 当你的JVM内存被一个简单的用户ID去重任务撑爆时，当你的日志分析系统因为HashSet的过度内存消耗而崩溃时，是时候重新审视那些被我们忽视的空间压缩神器了。本文将带你深入两种能够将…
贾子理论与AI时代文明竞争：从暴力计算到本质贯通的范式重构
贾子理论与AI时代文明竞争：从暴力计算到本质贯通的范式重构摘要本文基于贾子理论的文明竞争视角，揭示中美AI战略差异的本质并非技术参数较量，而是“暴力计算”与“本质贯通”两种文明范式的根本对立。美国依赖算力堆叠与资本逻辑追求技术霸权…
2026年AI大模型API中转平台排名揭晓，诗云API(ShiyunApi)脱颖而出成省心之选
在AI开发领域，如何接入模型厂商的官方API是一个绕不开的现实问题。对于海外开发者来说，注册、绑卡、调用，三步即可轻松搞定。然而，国内开发者却面临着跨境网络波动、外币支付门槛、发票合规需求以及多厂商Key碎片化管理等诸多“非…
基于飞书与OpenAI构建企业级AI助手：架构、部署与深度优化指南
1. 项目概述：当飞书遇上AI，一个企业级智能助手的诞生 最近在折腾一个挺有意思的项目，叫“ConnectAI-E/feishu-openai”。简单来说，它就是一个桥梁，把飞书这个强大的企业协作平台，和以ChatGPT为代表的OpenA…
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案 【免费下载链接】MPC-BE MPC-BE – универсальный проигрыватель аудио и видеофайлов для операционной системы Windows. 项目地址:…
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南 【免费下载链接】STL-Volume-Model-Calculator STL Volume Model Calculator Python 项目地址: https://gitcode.com/gh_mirrors/st/STL-Volume-Model-Calculator 你是否曾经为3D打印项目…
通过Taotoken CLI工具一键配置团队开发环境与模型密钥
通过Taotoken CLI工具一键配置团队开发环境与模型密钥 1. CLI工具安装与基本使用 Taotoken提供的CLI工具可通过npm全局安装或直接使用npx运行。对于需要频繁使用CLI的团队，推荐全局安装： npm install -g taotoken/taotoken对于临时使用或项目级配置&a…