QMK Firmware Serial 驱动完全指南为分体键盘选择与配置 Bitbang / USART 半双工 / USART 全双工通信【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本文以 QMK Firmware 官方驱动文档为主体系统讲解serial驱动在分体键盘Split Keyboard中的三种实现——Bitbang、USART Half-duplex 与 USART Full-duplex覆盖各自适用的 AVR/ARM 平台、引脚接线、rules.mk与config.h配置、ChibiOS 子系统选择、波特率与时延调优及常见问题排障。读完本文你将能够为自己的分体键盘正确选择通信驱动并完成从硬件接线到固件配置的完整落地。1. 概览三种驱动的选择矩阵serial驱动为 Split Keyboard分体键盘 功能提供左右两半之间的数据传输。仓库中提供了针对不同 MCU 平台与硬件能力实现的多种驱动变体。请注意这些驱动都不支持超过两半的分体键盘即只支持左右各一块主控的拓扑。驱动AVRARM两半之间的连接方式Bitbang单线通信一根线同时负责接收与发送USART Half-duplex高效单线通信一根线同时负责接收与发送USART Full-duplex高效双线通信接收与发送各用一根独立的线术语提醒这里的 Serial 应当理解为一次一位地传输信息bit-serial而非特指实现 UART / USART / RS485 / RS232 等具体标准。QMK 的 serial 驱动正是用自己的帧协议在这类底层电气通道上完成左右半的通信。从源码看构建系统在 builddefs/common_features.mk 中只接受三种合法取值VALID_SERIAL_DRIVER_TYPES : bitbang usart vendor SERIAL_DRIVER ? bitbang也就是说默认驱动是bitbang缺少配置时即采用该驱动非法取值会在编译期直接报错。选定后构建系统会追加-DSERIAL_DRIVER_大写名称宏并链接对应的serial_driver.c实现见 builddefs/common_features.mk。2. Bitbang 软件模拟串口这是默认驱动缺少配置即假定使用本驱动。其原理是用 CPU 对 GPIO 引脚进行位拆/软件模拟bit banging逐位翻转电平来模拟串口时序因此效率不如使用专用硬件外设的半双工/全双工驱动。在 ARM 平台上bitbang 驱动与 bitbang 版 WS2812 驱动同时使用时会引起连接问题。强烈建议为 serial 和 WS2812 都改选其他非 bitbang驱动。2.1 引脚配置LEFT RIGHT ------- SERIAL ------- | SSP |-----------------| SSP | | | VDD | | | |-----------------| | | | GND | | | |-----------------| | ------- -------Bitbang 驱动只需要一个 GPIO 引脚因为接收与发送共用同一根线。该引脚在配置中被称为SOFT_SERIAL_PINSSP。一条 TRS 或 USB 线缆提供的导体数量足以支撑该驱动工作串口信号线 VDD GND。在 AVR 实现 platforms/avr/drivers/serial.c 中可以看到SOFT_SERIAL_PIN会被映射到具体的外部中断如INT0_vect对应 D0、INT1_vect对应 D1驱动借助引脚中断来捕捉起始位并采样数据位——这正是用 CPU 模拟的底层体现。文件开头还注明该实现对时序高度敏感仅在特定 AVR 系列如 ATmega32U4、AT90USB1286 等上受支持若选用的 MCU 不受支持会直接编译报错。2.2 启用步骤第 1 步在键盘目录的rules.mk中修改SERIAL_DRIVERSERIAL_DRIVER bitbang第 2 步在config.h中配置 GPIO 引脚#define SOFT_SERIAL_PIN D0 // 或 D1, D2, D3, E6需要留意的是若 AVR 平台同时启用了 I2CUSE_AVR_I2C则不能把SOFT_SERIAL_PIN设为 D0 或 D1源码中对此有显式校验见 platforms/avr/drivers/serial.c。不同 AVR 系列可用的中断引脚不同例如 ATmega32U4 系列支持 D0–D3 与 E6而 AT90USB 系列支持 E4–E7选取前请对照主控手册。第 3 步仅 ARM 平台必须开启 ChibiOS PAL 回调。创建或修改键盘的halconf.h#pragma once #define PAL_USE_CALLBACKS TRUE #include_next halconf.h3. USART Half-duplex 半双工该驱动面向基于 ChibiOS 的 ARM 主控将通信卸载到支持半双工操作的 USART 硬件外设上。与 bitbang 相比优势在于快速、精准的时序以及更低的 CPU 占用。因此如果 MCU 支持半双工且无法使用全双工例如缺少可用 GPIO 引脚或 PCB 设计不兼容应优先选择 Half-duplex 而非 Bitbang。3.1 引脚配置LEFT RIGHT ------- | | ------- | | R R | | | | | SERIAL | | | | TX |-----------------| TX | | | VDD | | | |-----------------| | | | GND | | | |-----------------| | ------- -------Half-duplex 驱动只需要一个 GPIO 引脚收发共用一根线该引脚在配置中被称为SERIAL_USART_TX_PIN。所选引脚必须能够作为主控 USART 外设的 TX 引脚工作。一条 TRS 或 USB 线缆提供的导体即可满足需求。由于分体连接被配置为开漏open-drain模式需要一个外部上拉电阻将线路保持在高电平已知 1.5kΩ 至 8.2kΩ 的阻值均可正常工作。对于使用 PIO 子系统的 RP2040 主控不需要外部上拉电阻RP2040 PIO 实现默认利用内置上拉与 GPIO 操作将线路拉高。3.2 启用步骤第 1 步在rules.mk中修改SERIAL_DRIVERSERIAL_DRIVER usart然后跳到第 3 步。第 2 步仅 RP2040 PIO在rules.mk中改为SERIAL_DRIVER vendor第 3 步在config.h中配置硬件#define SERIAL_USART_TX_PIN B6 // 用于分体通信的 GPIO 引脚对于 STM32 MCU还可以修改若干 GPIO 配置选项参见下文 “常用 STM32 MCU 的复用功能表”#define USART1_REMAP // 在 STM32F103 MCU 上重映射 USART TX/RX 引脚见下表 #define SERIAL_USART_TX_PAL_MODE 7 // 引脚复用功能号请按 MCU 数据手册选择合适值默认: 7第 4 步选择SERIAL、SIO或PIO子系统见“驱动子系统的选择”。从源码 platforms/chibios/drivers/serial_usart.c 可以看到半双工模式的实现方式STM32 上通过在 USART 控制寄存器 CR3 中置位USART_CR3_HDSEL激活半双工AT32 上则对应USART_CTRL3_SLBEN。驱动在发送后还会主动把输入队列中自己写回的数据丢弃见同文件serial_transport_send中 half-duplex 分支的清理逻辑这是半双工收发同线在软件层的体现。4. USART Full-duplex 全双工该驱动面向基于 ChibiOS 的 ARM 主控将通信卸载到 USART 硬件外设。与 bitbang 相比优势同样是快速、精准的时序与低 CPU 占用因此在条件允许时优先推荐选择本驱动。由于内部设计Full-duplex 比 Half-duplex 略微高效但 Full-duplex 主要应在外设不支持半双工操作时选用。4.1 引脚配置LEFT RIGHT ------- ------- | | SERIAL | | | TX |-----------------| RX | | | SERIAL | | | RX |-----------------| TX | | | VDD | | | |-----------------| | | | GND | | | |-----------------| | ------- -------Full-duplex 驱动需要两个 GPIO 引脚收发各一根独立线。发送数据的引脚为TX在配置中被称为SERIAL_USART_TX_PIN接收数据的引脚为RX被称为SERIAL_USART_RX_PIN。注意主半的TX必须连接从半的RX主半的RX必须连接从半的TX交叉连接通常这个引脚互换必须在 MCU 之外完成例如通过线缆或在 PCB 上实现。部分 MCU如 Proton-C 上使用的 STM32F303允许在 MCU 内部直接完成引脚互换。一条 TRRS 或 USB 线缆提供的导体足以支撑该驱动工作。要使用该驱动USART 外设的TX与RX引脚必须配置为正确的复用功能Alternate Function。如果使用 Proton-C 开发板一切已配置就绪STM32F103 MCU 同样如此。对于使用现代灵活 GPIO 配置的 MCU需要通过SERIAL_USART_TX_PAL_MODE与SERIAL_USART_RX_PAL_MODE指定可查阅对应 MCU 数据手册或下文“常用 STM32 MCU 的复用功能表”。4.2 启用步骤第 1 步在rules.mk中修改SERIAL_DRIVERSERIAL_DRIVER usart然后跳到第 3 步。第 2 步仅 RP2040 PIO在rules.mk中改为SERIAL_DRIVER vendor第 3 步在config.h中配置硬件#define SERIAL_USART_FULL_DUPLEX // 启用全双工操作模式 #define SERIAL_USART_TX_PIN B6 // USART TX 引脚 #define SERIAL_USART_RX_PIN B7 // USART RX 引脚对于 STM32 MCU还可以修改若干 GPIO 配置选项包括TX/RX引脚互换能力见“常用 STM32 MCU 的复用功能表”#define SERIAL_USART_PIN_SWAP // 键盘为主半时交换 TX 与 RX 引脚仅部分 MCU 支持 #define USART1_REMAP // 在 STM32F103 MCU 上重映射 USART TX/RX 引脚见下表 #define SERIAL_USART_TX_PAL_MODE 7 // 引脚复用功能号请按 MCU 数据手册选择合适值默认: 7第 4 步选择SERIAL、SIO或PIO子系统见下节。源码中SERIAL_USART_PIN_SWAP与 USART 复用/重映射宏USART1_REMAP、USART2_REMAP、USART3_PARTIALREMAP、USART3_FULLREMAP等的处理位于 platforms/chibios/drivers/serial_usart.h它们会通过 AFIO 寄存器STM32或 IOMUX 寄存器AT32完成引脚重映射。5. 引脚默认值与参数默认值速查在深入配置之前先汇总 platforms/chibios/drivers/serial_usart.h 中定义的默认值便于对照自己的config.h是否命中默认行为配置项默认值说明SERIAL_USART_TX_PIN若定义了SOFT_SERIAL_PIN则取其值否则为A9USART 发送引脚SERIAL_USART_RX_PINA10USART 接收引脚SELECT_SOFT_SERIAL_SPEED1速度档位见波特率小节SERIAL_USART_TIMEOUT20单次通信超时毫秒SERIAL_USART_TX_PAL_MODE/SERIAL_USART_RX_PAL_MODE7引脚复用功能号仅USE_GPIOV1之外的平台SERIAL_USART_DRIVERSD1HAL_USE_SERIAL/SIOD1HAL_USE_SIO使用的 ChibiOS USART 驱动实例其中SERIAL_USART_DRIVER的取值由 HAL 子系统决定启用HAL_USE_SERIAL时使用SD1启用HAL_USE_SIO时使用SIOD1见 platforms/chibios/drivers/serial_usart.h。6. 驱动子系统的选择6.1SERIAL子系统SERIAL子系统支持绝大多数 ChibiOS MCU只要受支持就应优先使用。按以下步骤激活第 1 步在 ChibiOS HAL 中启用 SERIAL 子系统。向键盘的halconf.h添加必要时创建该文件#pragma once #define HAL_USE_SERIAL TRUE #include_next halconf.h第 2 步激活 MCU 上使用的 USART 外设。示例针对 STM32 MCU其他厂商的 MCU 不适用正确的名称可在随 ChibiOS 一起发布的主控mcuconf.h文件中找到。向键盘的mcuconf.h添加必要时创建该文件#pragma once #include_next mcuconf.h #undef STM32_SERIAL_USE_USARTn #define STM32_SERIAL_USE_USARTn TRUE其中n对应所选 USART 外设的编号。第 3 步如果使用的 USART 外设不属于默认选中的SD1驱动则需要覆盖默认的 USARTSERIAL驱动。例如若选择了STM32_SERIAL_USE_USART3对应的驱动为SD3。向键盘的config.h添加#define SERIAL_USART_DRIVER SD36.2SIO子系统SIO子系统随 ChibiOS 21.11 版本引入仅部分 MCU 支持应仅在 MCU 不支持SERIAL子系统时选用。激活步骤第 1 步在 ChibiOS HAL 中启用 SIO 子系统。向键盘的halconf.h添加#pragma once #define HAL_USE_SIO TRUE #include_next halconf.h第 2 步激活 USART 外设。向键盘的mcuconf.h添加#pragma once #include_next mcuconf.h #undef STM32_SIO_USE_USARTn #define STM32_SIO_USE_USARTn TRUE其中n对应所选 USART 外设的编号。第 3 步如果使用的 USART 外设不属于默认选中的SIOD1驱动覆盖默认驱动。例如选择了STM32_SERIAL_USE_USART3时对应SIOD3。向键盘的config.h添加#define SERIAL_USART_DRIVER SIOD36.3PIO子系统RP2040 专用PIO子系统是 Raspberry Pi RP2040 特有的实现利用 RP2040 集成的 PIO 外设因此仅适用于该 MCU。由于 PIO 外设的高度灵活性任意GPIO 引脚都可以作为TX或RX引脚使用。该驱动完整支持半双工与全双工两种模式。半双工模式默认利用 RP2040 的内置上拉与 GPIO 操作将线路拉高因此无需外部上拉电阻。可选地可以通过config.h中的以下宏更换用于分体通信的 PIO 外设#define SERIAL_PIO_USE_PIO1 // 强制使用 PIO1 外设默认串口实现使用 PIO0 外设在源码 platforms/chibios/drivers/vendor/RP/RP2040/serial_vendor.c 中可以看到SERIAL_PIO_USE_PIO1决定驱动绑定pio1及其对应的中断句柄RP_PIO1_IRQ_0_HANDLER未定义时默认使用pio0。同文件还给出了 TX/RX 的 PIO 程序指令uart_tx_program、uart_rx_program全双工与半双工模式下的 TX 程序仅在out pins/out pindirs指令上有所差异。资源占用提示Serial PIO 程序使用2 个状态机state machines、13 条指令并占用其所运行 PIO 外设的全部中断处理程序。7. 高级配置以下高级配置项均可定义在键盘的config.h中。7.1 波特率Baudrate如果遇到通信问题或需要更高的波特率可以通过波特率来控制串行通信速度。如果出现传输失败应降低波特率#define SELECT_SOFT_SERIAL_SPEED n其中n取值为速度BitbangHalf-duplex 与 Full-duplex0189000 baud实验性460800 baud1137000 baud默认230400 baud默认275000 baud115200 baud339000 baud57600 baud426000 baud38400 baud520000 baud19200 baud该速度表在源码中有完整对应USART 侧见 platforms/chibios/drivers/serial_usart.h其中SERIAL_USART_SPEED由SELECT_SOFT_SERIAL_SPEED映射默认 230400Bitbang 侧见 platforms/avr/drivers/serial.c默认 137000。两处对非法速度值都会在编译期报错。或者你也可以通过直接定义SERIAL_USART_SPEED来指定波特率该方式会优先于SELECT_SOFT_SERIAL_SPEED生效供高级用户直接指定#define SERIAL_USART_SPEED 2304007.2 超时Timeout这是单次成功通信必须完成的默认时间窗口毫秒。通常不需要修改该值但如需调整可在键盘的config.h中定义#define SERIAL_USART_TIMEOUT 20 // USART 驱动超时时间默认 20该宏在 platforms/chibios/drivers/serial_usart.h 中定义了默认值20并实际应用于serial_transport_send/serial_transport_receive的读写超时见 platforms/chibios/drivers/serial_usart.c。8. 故障排查Troubleshooting如果串行通信出现问题可以启用调试消息来了解通信的哪个环节失败。在键盘的config.h中添加#define SERIAL_DEBUG这些消息将输出到CONSOLE输出。更多信息请参阅 Debugging/Troubleshooting QMK。启用后请结合 QMK 控制台工具如qmk console观察输出定位是发送端还是接收端、是时序还是硬件连接导致的失败。9. 常用 STM32 MCU 的复用功能表以下是 USART 外设的可用引脚、复用功能Mode及引脚互换支持情况汇总。选择 USART 引脚前务必确认所选引脚可用的复用功能号与数据手册一致。9.1 STM32F303 / Proton-C支持引脚互换Pin Swap引脚功能ModeUSART1PA9TXAF7PA10RXAF7PB6TXAF7PB7RXAF7PC4TXAF7PC5RXAF7PE0TXAF7PE1RXAF7USART2PA2TXAF7PA3RXAF7PA14TXAF7PA15RXAF7PB3TXAF7PB4RXAF7PD5TXAF7PD6RXAF7USART3PB10TXAF7PB11RXAF7PC10TXAF7PC11RXAF7PD8TXAF7PD9RXAF79.2 STM32F072支持引脚互换Pin Swap引脚功能ModeUSART1PA9TXAF1PA10RXAF1PB6TXAF0PB7RXAF0USART2PA2TXAF1PA3RXAF1PA14TXAF1PA15RXAF1USART3PB10TXAF4PB11RXAF4PC4TXAF1PC5RXAF1PC10TXAF1PC11RXAF1PD8TXAF0PD9RXAF0USART4PA0TXAF4PA1RXAF49.3 STM32F103 中密度C8–CB支持引脚互换Pin SwapN/A任何 USART 外设的 TX 引脚始终为复用功能推挽Alternate Function Push-PullRX 引脚始终为普通输入引脚。STM32F103 无需额外的复用功能配置QMK 已经配置完毕。引脚重映射说明USART 外设的引脚使用默认引脚可通过 AFIO 寄存器重映射到其他引脚。默认引脚以加粗标出。将对应的宏定义添加到config.h中即可完成重映射。引脚功能ModeUSART_REMAPUSART1PA9TXAFPPPA10RXINPB6TXAFPPUSART1_REMAPPB7RXINUSART1_REMAPUSART2PA2TXAFPPPA3RXINPD5TXAFPPUSART2_REMAPPD6RXINUSART2_REMAPUSART3PB10TXAFPPPB11RXINPC10TXAFPPUSART3_PARTIALREMAPPC11RXINUSART3_PARTIALREMAPPD8TXAFPPUSART3_FULLREMAPPD9RXINUSART3_FULLREMAP例如要在 STM32F103 上把 USART1 从默认的 PA9/PA10 重映射到 PB6/PB7只需在config.h中添加#define USART1_REMAP10. 配置决策小结AVR 主控只能使用bitbangSERIAL_DRIVER bitbang配置SOFT_SERIAL_PIN注意避开与 I2C 冲突的 D0/D1。ARM 主控ChibiOS优先 Full-duplex需两个引脚且外设支持其次 Half-duplex单引脚 外部上拉电阻两者均使用SERIAL_DRIVER usart若外设不支持半双工且引脚充足全双工是最优选择。RP2040首选SERIAL_DRIVER vendor走 PIO 实现任意引脚可用半双工无需上拉电阻可用SERIAL_PIO_USE_PIO1切换 PIO 外设。子系统选择HAL_USE_SERIAL通用→HAL_USE_SIO21.11 的部分 MCU→ PIO仅 RP2040并在mcuconf.h中激活对应 USART必要时通过SERIAL_USART_DRIVER覆盖驱动实例。稳定性优先出现传输失败时先降低波特率SELECT_SOFT_SERIAL_SPEED并可用SERIAL_DEBUG开启 CONSOLE 调试输出定位问题环节。11. 延伸阅读Split Keyboard 分体键盘功能serial 驱动的上层使用者包含左右半通信的完整功能说明Debugging/Troubleshooting QMKCONSOLE 调试与问题排查驱动源码platforms/avr/drivers/serial.cBitbang/AVR、platforms/chibios/drivers/serial.cBitbang/ARM、platforms/chibios/drivers/serial_usart.cUSART 半双工/全双工、platforms/chibios/drivers/vendor/RP/RP2040/serial_vendor.cRP2040 PIO构建入口builddefs/common_features.mk驱动类型校验与链接【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 QMK Firmware Serial 驱动完全指南：为分体键盘选择与配置 Bitbang / USART 半双工 / USART 全双工通信
QMK Firmware Serial 驱动完全指南为分体键盘选择与配置 Bitbang / USART 半双工 / USART 全双工通信【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本文以 QMK Firmware 官方驱动文档为主体系统讲解serial驱动在分体键盘Split Keyboard中的三种实现——Bitbang、USART Half-duplex 与 USART Full-duplex覆盖各自适用的 AVR/ARM 平台、引脚接线、rules.mk与config.h配置、ChibiOS 子系统选择、波特率与时延调优及常见问题排障。读完本文你将能够为自己的分体键盘正确选择通信驱动并完成从硬件接线到固件配置的完整落地。1. 概览三种驱动的选择矩阵serial驱动为 Split Keyboard分体键盘 功能提供左右两半之间的数据传输。仓库中提供了针对不同 MCU 平台与硬件能力实现的多种驱动变体。请注意这些驱动都不支持超过两半的分体键盘即只支持左右各一块主控的拓扑。驱动AVRARM两半之间的连接方式Bitbang单线通信一根线同时负责接收与发送USART Half-duplex高效单线通信一根线同时负责接收与发送USART Full-duplex高效双线通信接收与发送各用一根独立的线术语提醒这里的 Serial 应当理解为一次一位地传输信息bit-serial而非特指实现 UART / USART / RS485 / RS232 等具体标准。QMK 的 serial 驱动正是用自己的帧协议在这类底层电气通道上完成左右半的通信。从源码看构建系统在 builddefs/common_features.mk 中只接受三种合法取值VALID_SERIAL_DRIVER_TYPES : bitbang usart vendor SERIAL_DRIVER ? bitbang也就是说默认驱动是bitbang缺少配置时即采用该驱动非法取值会在编译期直接报错。选定后构建系统会追加-DSERIAL_DRIVER_大写名称宏并链接对应的serial_driver.c实现见 builddefs/common_features.mk。2. Bitbang 软件模拟串口这是默认驱动缺少配置即假定使用本驱动。其原理是用 CPU 对 GPIO 引脚进行位拆/软件模拟bit banging逐位翻转电平来模拟串口时序因此效率不如使用专用硬件外设的半双工/全双工驱动。在 ARM 平台上bitbang 驱动与 bitbang 版 WS2812 驱动同时使用时会引起连接问题。强烈建议为 serial 和 WS2812 都改选其他非 bitbang驱动。2.1 引脚配置LEFT RIGHT ------- SERIAL ------- | SSP |-----------------| SSP | | | VDD | | | |-----------------| | | | GND | | | |-----------------| | ------- -------Bitbang 驱动只需要一个 GPIO 引脚因为接收与发送共用同一根线。该引脚在配置中被称为SOFT_SERIAL_PINSSP。一条 TRS 或 USB 线缆提供的导体数量足以支撑该驱动工作串口信号线 VDD GND。在 AVR 实现 platforms/avr/drivers/serial.c 中可以看到SOFT_SERIAL_PIN会被映射到具体的外部中断如INT0_vect对应 D0、INT1_vect对应 D1驱动借助引脚中断来捕捉起始位并采样数据位——这正是用 CPU 模拟的底层体现。文件开头还注明该实现对时序高度敏感仅在特定 AVR 系列如 ATmega32U4、AT90USB1286 等上受支持若选用的 MCU 不受支持会直接编译报错。2.2 启用步骤第 1 步在键盘目录的rules.mk中修改SERIAL_DRIVERSERIAL_DRIVER bitbang第 2 步在config.h中配置 GPIO 引脚#define SOFT_SERIAL_PIN D0 // 或 D1, D2, D3, E6需要留意的是若 AVR 平台同时启用了 I2CUSE_AVR_I2C则不能把SOFT_SERIAL_PIN设为 D0 或 D1源码中对此有显式校验见 platforms/avr/drivers/serial.c。不同 AVR 系列可用的中断引脚不同例如 ATmega32U4 系列支持 D0–D3 与 E6而 AT90USB 系列支持 E4–E7选取前请对照主控手册。第 3 步仅 ARM 平台必须开启 ChibiOS PAL 回调。创建或修改键盘的halconf.h#pragma once #define PAL_USE_CALLBACKS TRUE #include_next halconf.h3. USART Half-duplex 半双工该驱动面向基于 ChibiOS 的 ARM 主控将通信卸载到支持半双工操作的 USART 硬件外设上。与 bitbang 相比优势在于快速、精准的时序以及更低的 CPU 占用。因此如果 MCU 支持半双工且无法使用全双工例如缺少可用 GPIO 引脚或 PCB 设计不兼容应优先选择 Half-duplex 而非 Bitbang。3.1 引脚配置LEFT RIGHT ------- | | ------- | | R R | | | | | SERIAL | | | | TX |-----------------| TX | | | VDD | | | |-----------------| | | | GND | | | |-----------------| | ------- -------Half-duplex 驱动只需要一个 GPIO 引脚收发共用一根线该引脚在配置中被称为SERIAL_USART_TX_PIN。所选引脚必须能够作为主控 USART 外设的 TX 引脚工作。一条 TRS 或 USB 线缆提供的导体即可满足需求。由于分体连接被配置为开漏open-drain模式需要一个外部上拉电阻将线路保持在高电平已知 1.5kΩ 至 8.2kΩ 的阻值均可正常工作。对于使用 PIO 子系统的 RP2040 主控不需要外部上拉电阻RP2040 PIO 实现默认利用内置上拉与 GPIO 操作将线路拉高。3.2 启用步骤第 1 步在rules.mk中修改SERIAL_DRIVERSERIAL_DRIVER usart然后跳到第 3 步。第 2 步仅 RP2040 PIO在rules.mk中改为SERIAL_DRIVER vendor第 3 步在config.h中配置硬件#define SERIAL_USART_TX_PIN B6 // 用于分体通信的 GPIO 引脚对于 STM32 MCU还可以修改若干 GPIO 配置选项参见下文 “常用 STM32 MCU 的复用功能表”#define USART1_REMAP // 在 STM32F103 MCU 上重映射 USART TX/RX 引脚见下表 #define SERIAL_USART_TX_PAL_MODE 7 // 引脚复用功能号请按 MCU 数据手册选择合适值默认: 7第 4 步选择SERIAL、SIO或PIO子系统见“驱动子系统的选择”。从源码 platforms/chibios/drivers/serial_usart.c 可以看到半双工模式的实现方式STM32 上通过在 USART 控制寄存器 CR3 中置位USART_CR3_HDSEL激活半双工AT32 上则对应USART_CTRL3_SLBEN。驱动在发送后还会主动把输入队列中自己写回的数据丢弃见同文件serial_transport_send中 half-duplex 分支的清理逻辑这是半双工收发同线在软件层的体现。4. USART Full-duplex 全双工该驱动面向基于 ChibiOS 的 ARM 主控将通信卸载到 USART 硬件外设。与 bitbang 相比优势同样是快速、精准的时序与低 CPU 占用因此在条件允许时优先推荐选择本驱动。由于内部设计Full-duplex 比 Half-duplex 略微高效但 Full-duplex 主要应在外设不支持半双工操作时选用。4.1 引脚配置LEFT RIGHT ------- ------- | | SERIAL | | | TX |-----------------| RX | | | SERIAL | | | RX |-----------------| TX | | | VDD | | | |-----------------| | | | GND | | | |-----------------| | ------- -------Full-duplex 驱动需要两个 GPIO 引脚收发各一根独立线。发送数据的引脚为TX在配置中被称为SERIAL_USART_TX_PIN接收数据的引脚为RX被称为SERIAL_USART_RX_PIN。注意主半的TX必须连接从半的RX主半的RX必须连接从半的TX交叉连接通常这个引脚互换必须在 MCU 之外完成例如通过线缆或在 PCB 上实现。部分 MCU如 Proton-C 上使用的 STM32F303允许在 MCU 内部直接完成引脚互换。一条 TRRS 或 USB 线缆提供的导体足以支撑该驱动工作。要使用该驱动USART 外设的TX与RX引脚必须配置为正确的复用功能Alternate Function。如果使用 Proton-C 开发板一切已配置就绪STM32F103 MCU 同样如此。对于使用现代灵活 GPIO 配置的 MCU需要通过SERIAL_USART_TX_PAL_MODE与SERIAL_USART_RX_PAL_MODE指定可查阅对应 MCU 数据手册或下文“常用 STM32 MCU 的复用功能表”。4.2 启用步骤第 1 步在rules.mk中修改SERIAL_DRIVERSERIAL_DRIVER usart然后跳到第 3 步。第 2 步仅 RP2040 PIO在rules.mk中改为SERIAL_DRIVER vendor第 3 步在config.h中配置硬件#define SERIAL_USART_FULL_DUPLEX // 启用全双工操作模式 #define SERIAL_USART_TX_PIN B6 // USART TX 引脚 #define SERIAL_USART_RX_PIN B7 // USART RX 引脚对于 STM32 MCU还可以修改若干 GPIO 配置选项包括TX/RX引脚互换能力见“常用 STM32 MCU 的复用功能表”#define SERIAL_USART_PIN_SWAP // 键盘为主半时交换 TX 与 RX 引脚仅部分 MCU 支持 #define USART1_REMAP // 在 STM32F103 MCU 上重映射 USART TX/RX 引脚见下表 #define SERIAL_USART_TX_PAL_MODE 7 // 引脚复用功能号请按 MCU 数据手册选择合适值默认: 7第 4 步选择SERIAL、SIO或PIO子系统见下节。源码中SERIAL_USART_PIN_SWAP与 USART 复用/重映射宏USART1_REMAP、USART2_REMAP、USART3_PARTIALREMAP、USART3_FULLREMAP等的处理位于 platforms/chibios/drivers/serial_usart.h它们会通过 AFIO 寄存器STM32或 IOMUX 寄存器AT32完成引脚重映射。5. 引脚默认值与参数默认值速查在深入配置之前先汇总 platforms/chibios/drivers/serial_usart.h 中定义的默认值便于对照自己的config.h是否命中默认行为配置项默认值说明SERIAL_USART_TX_PIN若定义了SOFT_SERIAL_PIN则取其值否则为A9USART 发送引脚SERIAL_USART_RX_PINA10USART 接收引脚SELECT_SOFT_SERIAL_SPEED1速度档位见波特率小节SERIAL_USART_TIMEOUT20单次通信超时毫秒SERIAL_USART_TX_PAL_MODE/SERIAL_USART_RX_PAL_MODE7引脚复用功能号仅USE_GPIOV1之外的平台SERIAL_USART_DRIVERSD1HAL_USE_SERIAL/SIOD1HAL_USE_SIO使用的 ChibiOS USART 驱动实例其中SERIAL_USART_DRIVER的取值由 HAL 子系统决定启用HAL_USE_SERIAL时使用SD1启用HAL_USE_SIO时使用SIOD1见 platforms/chibios/drivers/serial_usart.h。6. 驱动子系统的选择6.1SERIAL子系统SERIAL子系统支持绝大多数 ChibiOS MCU只要受支持就应优先使用。按以下步骤激活第 1 步在 ChibiOS HAL 中启用 SERIAL 子系统。向键盘的halconf.h添加必要时创建该文件#pragma once #define HAL_USE_SERIAL TRUE #include_next halconf.h第 2 步激活 MCU 上使用的 USART 外设。示例针对 STM32 MCU其他厂商的 MCU 不适用正确的名称可在随 ChibiOS 一起发布的主控mcuconf.h文件中找到。向键盘的mcuconf.h添加必要时创建该文件#pragma once #include_next mcuconf.h #undef STM32_SERIAL_USE_USARTn #define STM32_SERIAL_USE_USARTn TRUE其中n对应所选 USART 外设的编号。第 3 步如果使用的 USART 外设不属于默认选中的SD1驱动则需要覆盖默认的 USARTSERIAL驱动。例如若选择了STM32_SERIAL_USE_USART3对应的驱动为SD3。向键盘的config.h添加#define SERIAL_USART_DRIVER SD36.2SIO子系统SIO子系统随 ChibiOS 21.11 版本引入仅部分 MCU 支持应仅在 MCU 不支持SERIAL子系统时选用。激活步骤第 1 步在 ChibiOS HAL 中启用 SIO 子系统。向键盘的halconf.h添加#pragma once #define HAL_USE_SIO TRUE #include_next halconf.h第 2 步激活 USART 外设。向键盘的mcuconf.h添加#pragma once #include_next mcuconf.h #undef STM32_SIO_USE_USARTn #define STM32_SIO_USE_USARTn TRUE其中n对应所选 USART 外设的编号。第 3 步如果使用的 USART 外设不属于默认选中的SIOD1驱动覆盖默认驱动。例如选择了STM32_SERIAL_USE_USART3时对应SIOD3。向键盘的config.h添加#define SERIAL_USART_DRIVER SIOD36.3PIO子系统RP2040 专用PIO子系统是 Raspberry Pi RP2040 特有的实现利用 RP2040 集成的 PIO 外设因此仅适用于该 MCU。由于 PIO 外设的高度灵活性任意GPIO 引脚都可以作为TX或RX引脚使用。该驱动完整支持半双工与全双工两种模式。半双工模式默认利用 RP2040 的内置上拉与 GPIO 操作将线路拉高因此无需外部上拉电阻。可选地可以通过config.h中的以下宏更换用于分体通信的 PIO 外设#define SERIAL_PIO_USE_PIO1 // 强制使用 PIO1 外设默认串口实现使用 PIO0 外设在源码 platforms/chibios/drivers/vendor/RP/RP2040/serial_vendor.c 中可以看到SERIAL_PIO_USE_PIO1决定驱动绑定pio1及其对应的中断句柄RP_PIO1_IRQ_0_HANDLER未定义时默认使用pio0。同文件还给出了 TX/RX 的 PIO 程序指令uart_tx_program、uart_rx_program全双工与半双工模式下的 TX 程序仅在out pins/out pindirs指令上有所差异。资源占用提示Serial PIO 程序使用2 个状态机state machines、13 条指令并占用其所运行 PIO 外设的全部中断处理程序。7. 高级配置以下高级配置项均可定义在键盘的config.h中。7.1 波特率Baudrate如果遇到通信问题或需要更高的波特率可以通过波特率来控制串行通信速度。如果出现传输失败应降低波特率#define SELECT_SOFT_SERIAL_SPEED n其中n取值为速度BitbangHalf-duplex 与 Full-duplex0189000 baud实验性460800 baud1137000 baud默认230400 baud默认275000 baud115200 baud339000 baud57600 baud426000 baud38400 baud520000 baud19200 baud该速度表在源码中有完整对应USART 侧见 platforms/chibios/drivers/serial_usart.h其中SERIAL_USART_SPEED由SELECT_SOFT_SERIAL_SPEED映射默认 230400Bitbang 侧见 platforms/avr/drivers/serial.c默认 137000。两处对非法速度值都会在编译期报错。或者你也可以通过直接定义SERIAL_USART_SPEED来指定波特率该方式会优先于SELECT_SOFT_SERIAL_SPEED生效供高级用户直接指定#define SERIAL_USART_SPEED 2304007.2 超时Timeout这是单次成功通信必须完成的默认时间窗口毫秒。通常不需要修改该值但如需调整可在键盘的config.h中定义#define SERIAL_USART_TIMEOUT 20 // USART 驱动超时时间默认 20该宏在 platforms/chibios/drivers/serial_usart.h 中定义了默认值20并实际应用于serial_transport_send/serial_transport_receive的读写超时见 platforms/chibios/drivers/serial_usart.c。8. 故障排查Troubleshooting如果串行通信出现问题可以启用调试消息来了解通信的哪个环节失败。在键盘的config.h中添加#define SERIAL_DEBUG这些消息将输出到CONSOLE输出。更多信息请参阅 Debugging/Troubleshooting QMK。启用后请结合 QMK 控制台工具如qmk console观察输出定位是发送端还是接收端、是时序还是硬件连接导致的失败。9. 常用 STM32 MCU 的复用功能表以下是 USART 外设的可用引脚、复用功能Mode及引脚互换支持情况汇总。选择 USART 引脚前务必确认所选引脚可用的复用功能号与数据手册一致。9.1 STM32F303 / Proton-C支持引脚互换Pin Swap引脚功能ModeUSART1PA9TXAF7PA10RXAF7PB6TXAF7PB7RXAF7PC4TXAF7PC5RXAF7PE0TXAF7PE1RXAF7USART2PA2TXAF7PA3RXAF7PA14TXAF7PA15RXAF7PB3TXAF7PB4RXAF7PD5TXAF7PD6RXAF7USART3PB10TXAF7PB11RXAF7PC10TXAF7PC11RXAF7PD8TXAF7PD9RXAF79.2 STM32F072支持引脚互换Pin Swap引脚功能ModeUSART1PA9TXAF1PA10RXAF1PB6TXAF0PB7RXAF0USART2PA2TXAF1PA3RXAF1PA14TXAF1PA15RXAF1USART3PB10TXAF4PB11RXAF4PC4TXAF1PC5RXAF1PC10TXAF1PC11RXAF1PD8TXAF0PD9RXAF0USART4PA0TXAF4PA1RXAF49.3 STM32F103 中密度C8–CB支持引脚互换Pin SwapN/A任何 USART 外设的 TX 引脚始终为复用功能推挽Alternate Function Push-PullRX 引脚始终为普通输入引脚。STM32F103 无需额外的复用功能配置QMK 已经配置完毕。引脚重映射说明USART 外设的引脚使用默认引脚可通过 AFIO 寄存器重映射到其他引脚。默认引脚以加粗标出。将对应的宏定义添加到config.h中即可完成重映射。引脚功能ModeUSART_REMAPUSART1PA9TXAFPPPA10RXINPB6TXAFPPUSART1_REMAPPB7RXINUSART1_REMAPUSART2PA2TXAFPPPA3RXINPD5TXAFPPUSART2_REMAPPD6RXINUSART2_REMAPUSART3PB10TXAFPPPB11RXINPC10TXAFPPUSART3_PARTIALREMAPPC11RXINUSART3_PARTIALREMAPPD8TXAFPPUSART3_FULLREMAPPD9RXINUSART3_FULLREMAP例如要在 STM32F103 上把 USART1 从默认的 PA9/PA10 重映射到 PB6/PB7只需在config.h中添加#define USART1_REMAP10. 配置决策小结AVR 主控只能使用bitbangSERIAL_DRIVER bitbang配置SOFT_SERIAL_PIN注意避开与 I2C 冲突的 D0/D1。ARM 主控ChibiOS优先 Full-duplex需两个引脚且外设支持其次 Half-duplex单引脚 外部上拉电阻两者均使用SERIAL_DRIVER usart若外设不支持半双工且引脚充足全双工是最优选择。RP2040首选SERIAL_DRIVER vendor走 PIO 实现任意引脚可用半双工无需上拉电阻可用SERIAL_PIO_USE_PIO1切换 PIO 外设。子系统选择HAL_USE_SERIAL通用→HAL_USE_SIO21.11 的部分 MCU→ PIO仅 RP2040并在mcuconf.h中激活对应 USART必要时通过SERIAL_USART_DRIVER覆盖驱动实例。稳定性优先出现传输失败时先降低波特率SELECT_SOFT_SERIAL_SPEED并可用SERIAL_DEBUG开启 CONSOLE 调试输出定位问题环节。11. 延伸阅读Split Keyboard 分体键盘功能serial 驱动的上层使用者包含左右半通信的完整功能说明Debugging/Troubleshooting QMKCONSOLE 调试与问题排查驱动源码platforms/avr/drivers/serial.cBitbang/AVR、platforms/chibios/drivers/serial.cBitbang/ARM、platforms/chibios/drivers/serial_usart.cUSART 半双工/全双工、platforms/chibios/drivers/vendor/RP/RP2040/serial_vendor.cRP2040 PIO构建入口builddefs/common_features.mk驱动类型校验与链接【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考