1. 项目概述MD_OnePin 是一个面向资源受限嵌入式系统的轻量级单线串行通信协议库其核心设计目标是仅使用一个通用数字 I/O 引脚外加共地即可实现主从式点对点双向数据传输。该库完全基于软件模拟bit-banging实现不依赖任何硬件 UART、USART 或专用串行外设因此可部署于几乎任意 Cortex-M0/M0/M3/M4、8051、AVR、ESP32、nRF52 等微控制器平台尤其适用于 MCU UART 资源已耗尽、或需为低成本传感器/执行器节点预留引脚的工业与物联网边缘场景。与传统 UART 的双线TX/RX或三线TX/RX/GND方案不同MD_OnePin 将发送与接收复用在同一根物理信号线上通过精确的时序控制与半双工协商机制规避冲突。其本质是一种主控同步、从机响应、单线双向、无硬件依赖的定制化串行链路层协议而非标准 UART 的电气替代方案如 RS-232、RS-485。它不兼容 UART 波特率自动检测、起始位/停止位硬件采样等机制而是采用固定帧结构、显式同步头与曼彻斯特编码风格的边沿触发逻辑确保在极低主频如 STM32F0308MHz、ATmega328P1MHz下仍具备可靠通信能力。该库的工程价值在于填补了“超简硬件接口”与“可靠数据交换”之间的空白当系统需连接数十个分布式温湿度传感器、LED 驱动模块、继电器板或定制 ADC 子板而每个节点仅能提供 1~2 个 GPIO 时MD_OnePin 提供了一种可扩展、易集成、免布线的通信范式。其典型应用包括工业现场中PLC 主站通过单线总线轮询多个低成本温度探头智能家居网关以菊花链方式串联多组 RGBW LED 控制器电池供电的无线传感器节点如 nRF52832通过单线向主控 MCU 回传采集数据节省 RF 模块引脚教学实验平台中学生使用 STM32F103 最小系统与 Arduino UNO 构建主从通信系统无需交叉接线。值得注意的是MD_OnePin 并非通用总线协议如 I²C、1-Wire它不支持多从机地址寻址与仲裁其拓扑严格限定为1 主 N 从N ≥ 1的点对点链路集合——即每个从机独占一根单线连接至主机或通过硬件线与门如 74HC32 或二极管 OR实现逻辑“线与”由主机逐个轮询。这种设计牺牲了总线共享能力却极大降低了从机端的软硬件复杂度从机无需中断服务程序、无需定时器资源、甚至可在休眠模式下被主机唤醒并立即响应。2. 协议原理与电气特性2.1 物理层设计哲学MD_OnePin 的物理层摒弃了传统 UART 的电平持续时间判别法如检测 10×Tbit 的低电平作为起始位转而采用边沿驱动、同步采样、脉宽编码三位一体的设计单线双向复用信号线默认由主机上拉或下拉至空闲电平Idle Level通信时主机主动驱动该线完成发送从机仅在主机明确授予权限后才短暂拉低或拉高该线进行应答。空闲电平极性可配置ONEPIN_IDLE_HIGH或ONEPIN_IDLE_LOW适配不同 MCU 的开漏/推挽输出特性。主控同步机制所有通信均由主机发起。主机首先输出一个同步前导码Sync Preamble该前导码由连续 8 个等宽窄脉冲组成典型宽度 100μs用于向从机宣告通信开始为从机提供精确的时钟基准校准其内部延时循环消除因 MCU 主频差异导致的累积时序误差。曼彻斯特风格编码每个数据位bit被编码为一个固定周期内的电平跳变。例如在ONEPIN_IDLE_HIGH模式下逻辑0编码为高→低跳变下降沿后维持低电平约 1/2 周期再上升沿返回高电平逻辑1编码为低→高跳变上升沿后维持高电平约 1/2 周期再下降沿返回低电平。 此设计确保每个位周期内至少存在一次有效跳变使从机可通过 GPIO 中断或轮询边沿精准捕获位边界彻底规避长连0或1导致的时钟漂移问题。2.2 帧结构定义MD_OnePin 定义了紧凑的四段式帧格式总长度固定为 32 位4 字节无起始位、停止位、校验位全部由协议逻辑保障可靠性字段长度bit内容说明示例值十六进制Sync Header8固定同步字节0x55二进制01010101其交替的0/1模式天然构成曼彻斯特编码所需的连续跳变是接收方锁定时序的黄金标准0x55Address Field8从机地址0x00 ~ 0xFF。主机发送此字段指定目标从机从机收到后比对自身地址仅匹配者进入响应流程。地址0x00保留为广播地址所有从机均响应0x0ACommand Field8命令码定义操作类型。常见值0x01读寄存器、0x02写寄存器、0x03获取状态、0x04触发动作0x01Data Field8有效载荷数据。对于读操作此字段为主机期望读取的寄存器地址对于写操作此字段为待写入的数据值对于状态查询可为保留值0x000x1F关键设计考量32 位固定帧长极大简化了从机端的解析逻辑。从机无需动态计算帧边界只需在同步头确认后严格按 8 位/段、共 4 段的节奏采样即可。这使得从机固件可精简至不足 200 字节机器码甚至可在 8 位 MCU 上用纯汇编实现。2.3 时序参数与波特率MD_OnePin 不使用“波特率”概念而是以基础时钟周期Tbase为单位定义所有时序。Tbase 典型值为 100μs对应 10 kbps 等效速率但可通过宏ONEPIN_TBASE_US在编译时调整。各关键时序如下表所示以ONEPIN_TBASE_US 100为例时序事件持续时间说明Sync Pulse Width1 × Tbase同步前导码中每个窄脉冲的宽度高→低→高或低→高→低Bit Period4 × Tbase一个完整数据位含跳变与保持的总周期即 400μs等效 2.5 kbpsEdge Setup/Hold≥ 0.5 × Tbase边沿跳变前后电平需稳定的时间确保 GPIO 输入滤波器可靠捕获Response Delay≤ 2 × Tbase从机在正确识别地址后启动响应帧的最大延迟从 Sync Header 结束起计工程实践提示Tbase 的选择需在通信可靠性与 MCU 负载间权衡。过小的 Tbase如 20μs虽提升速率但要求 MCU 具备更高主频与更短中断响应延迟过大的 Tbase如 500μs则降低吞吐量。实测表明在 STM32F030F4P648MHz上Tbase100μs 可稳定支持 5 米线缆长度在 ATmega328P16MHz上Tbase200μs 是更稳妥的选择。3. API 接口详解与使用范式MD_OnePin 库提供一组精简、无阻塞、可重入的 C 函数接口核心 API 均围绕OnePin_HandleTypeDef句柄展开符合 STM32 HAL 库的设计哲学便于在现有 HAL 项目中无缝集成。3.1 核心数据结构与初始化typedef struct { GPIO_TypeDef* Instance; // GPIO 端口如 GPIOA uint16_t Pin; // 引脚号如 GPIO_PIN_9 uint32_t Tbase_us; // 基础时钟周期单位微秒 uint8_t IdleLevel; // 空闲电平ONEPIN_IDLE_HIGH 或 ONEPIN_IDLE_LOW uint8_t TxState; // 发送状态ONEPIN_TX_IDLE / ONEPIN_TX_BUSY uint8_t RxState; // 接收状态ONEPIN_RX_IDLE / ONEPIN_RX_BUSY } OnePin_HandleTypeDef; // 初始化函数配置 GPIO 引脚为推挽/开漏输出并设置空闲电平 HAL_StatusTypeDef OnePin_Init(OnePin_HandleTypeDef *honepin); // 反初始化恢复 GPIO 为浮空输入 HAL_StatusTypeDef OnePin_DeInit(OnePin_HandleTypeDef *honepin);初始化关键步骤调用__HAL_RCC_GPIOx_CLK_ENABLE()使能对应 GPIO 时钟配置honepin-Instance和honepin-Pin设置honepin-Tbase_us推荐 100~200设置honepin-IdleLevel若 MCU 支持开漏且外接上拉电阻选ONEPIN_IDLE_HIGH若用推挽且需强驱动选ONEPIN_IDLE_LOW调用OnePin_Init()完成底层 GPIO 初始化。3.2 主机端核心 API主机通过以下函数发起通信所有操作均为同步阻塞式调用返回即表示该帧传输完成成功或超时// 主机发送一帧请求并等待从机响应带超时 // timeout_ms: 响应超时时间毫秒典型值 10~50 HAL_StatusTypeDef OnePin_Master_TransmitReceive( OnePin_HandleTypeDef *h, uint8_t addr, uint8_t cmd, uint8_t *tx_data, // 指向待发送的 Data 字段1 字节 uint8_t *rx_data, // 指向接收缓冲区1 字节存储从机返回的数据 uint32_t timeout_ms); // 主机仅发送请求无响应适用于广播命令或触发类操作 HAL_StatusTypeDef OnePin_Master_TransmitOnly( OnePin_HandleTypeDef *h, uint8_t addr, uint8_t cmd, uint8_t tx_data, uint32_t timeout_ms);典型主机调用示例STM32 HAL 环境OnePin_HandleTypeDef hOnePin; uint8_t sensor_addr 0x05; uint8_t cmd_read_temp 0x01; uint8_t reg_addr 0x00; // 温度寄存器地址 uint8_t temp_value; // 初始化单线引脚假设为 PA9 hOnePin.Instance GPIOA; hOnePin.Pin GPIO_PIN_9; hOnePin.Tbase_us 100; hOnePin.IdleLevel ONEPIN_IDLE_HIGH; if (HAL_OK ! OnePin_Init(hOnePin)) { Error_Handler(); // 处理初始化失败 } // 向地址 0x05 的传感器读取温度 if (HAL_OK OnePin_Master_TransmitReceive(hOnePin, sensor_addr, cmd_read_temp, reg_addr, temp_value, 20)) { printf(Sensor %02X: Temp %d°C\n, sensor_addr, temp_value); } else { printf(Comm timeout with sensor %02X\n, sensor_addr); }3.3 从机端核心 API从机端 API 设计为事件驱动需在主循环或定时器中断中周期性调用OnePin_Slave_Process()由库内部完成同步检测、地址比对与响应生成// 从机处理函数必须在主循环中高频调用建议 ≥ 10kHz // 返回值ONEPIN_SLAVE_IDLE空闲、ONEPIN_SLAVE_RESPONDING正在响应、ONEPIN_SLAVE_ERROR帧错误 uint8_t OnePin_Slave_Process(OnePin_HandleTypeDef *h, uint8_t my_addr, void (*callback)(uint8_t cmd, uint8_t data, uint8_t *response)); // 从机回调函数原型cmd 为接收到的命令data 为接收到的数据字段 // response 指针用于填充 1 字节响应数据将被自动发送回主机 void MySlaveCallback(uint8_t cmd, uint8_t data, uint8_t *response) { switch(cmd) { case 0x01: // 读寄存器 *response ReadTemperatureRegister(data); // data 是寄存器地址 break; case 0x02: // 写寄存器 WriteConfigRegister(data, data); // 简化示例 *response 0x00; // ACK break; default: *response 0xFF; // NACK } }从机主循环示例裸机环境OnePin_HandleTypeDef hOnePin; uint8_t my_address 0x05; // 初始化同主机 hOnePin.Instance GPIOB; hOnePin.Pin GPIO_PIN_12; hOnePin.Tbase_us 100; hOnePin.IdleLevel ONEPIN_IDLE_HIGH; OnePin_Init(hOnePin); while(1) { // 高频轮询处理单线事件 uint8_t state OnePin_Slave_Process(hOnePin, my_address, MySlaveCallback); // 可在此处添加低功耗管理若 state ONEPIN_SLAVE_IDLE可进入 Sleep 模式 if (state ONEPIN_SLAVE_IDLE) { __WFI(); // 等待中断若启用 GPIO 中断或简单延时 } }4. 源码实现逻辑剖析MD_OnePin 的核心代码位于src/onepin.c其精妙之处在于以最小代码量实现高鲁棒性。以下解析关键模块4.1 同步头检测算法从机端的同步头检测不依赖外部中断而是采用GPIO 电平轮询 状态机避免中断抖动干扰// 简化版状态机逻辑实际代码含更多防抖 typedef enum { SYNC_WAIT_LOW, // 等待第一个下降沿Idle High 时 SYNC_WAIT_HIGH, // 等待第一个上升沿 SYNC_COUNT_PULSES // 计数连续跳变 } SyncState; static SyncState sync_state SYNC_WAIT_LOW; static uint8_t pulse_count 0; void OnePin_Slave_Process(...) { uint8_t pin_level HAL_GPIO_ReadPin(h-Instance, h-Pin); switch(sync_state) { case SYNC_WAIT_LOW: if (pin_level GPIO_PIN_RESET) { // 检测到下降沿 sync_state SYNC_WAIT_HIGH; pulse_count 1; delay_us(h-Tbase_us / 2); // 等待至脉冲中点 } break; case SYNC_WAIT_HIGH: if (pin_level GPIO_PIN_SET) { // 检测到上升沿 pulse_count; if (pulse_count 8) { sync_state SYNC_COUNT_PULSES; // 启动后续 32 位采样... } else { sync_state SYNC_WAIT_LOW; } } break; // ... 其他状态 } }该设计确保即使在强电磁干扰环境下也能通过连续 8 次跳变确认同步误触发概率趋近于零。4.2 位采样与解码位采样采用中点采样法Mid-bit Sampling在每个位周期的中间时刻即2 × Tbase_us后读取 GPIO 电平结合前一时刻电平判断跳变方向从而解码0或1。此方法对 RC 滤波引起的信号延时具有天然鲁棒性。4.3 响应帧生成从机响应帧的生成完全由软件延时控制不使用定时器。库内置高度优化的delay_us()函数针对不同 ARM Cortex-M 内核M0/M3/M4及 GCC/ARMCC 编译器自动生成精确的 NOP 循环。例如 M0 内核下delay_us(100)可能展开为 120 个周期的汇编指令误差 ±1μs。5. 实际工程部署指南5.1 硬件连接规范引脚选择优先选用支持外部中断的 GPIO如 STM32 的 EXTI0~15便于从机快速响应主机端无此要求。上拉/下拉电阻若配置ONEPIN_IDLE_HIGH必须在信号线上外接 4.7kΩ 上拉电阻至 VDD若ONEPIN_IDLE_LOW则需 4.7kΩ 下拉电阻至 GND。电阻值需根据线缆长度与 MCU 驱动能力调整长线缆选 2.2kΩ。ESD 保护在工业现场建议在单线入口处增加 TVS 二极管如 SMAJ5.0A抑制浪涌。共地质量主机与从机必须有低阻抗共地连接长距离通信时建议使用双绞线信号线GND。5.2 性能与可靠性调优问题现象根本原因解决方案从机偶发失步MCU 主频波动或中断延迟过大增大Tbase_us至 150~200禁用高优先级中断主机收不到响应从机响应延迟超时检查OnePin_Slave_Process()调用频率优化回调函数执行时间 50μs多从机通信冲突硬件未做“线与”处理为每个从机输出端加 1N4148 二极管阴极接单线阳极接从机 GPIO主机端统一上拉5.3 与 FreeRTOS 集成示例在 FreeRTOS 环境中可将主机通信封装为独立任务避免阻塞其他任务void OnePinMasterTask(void const * argument) { OnePin_HandleTypeDef hOnePin; // ... 初始化 hOnePin for(;;) { // 扫描所有从机地址 for(uint8_t addr 0x01; addr 0x0F; addr) { uint8_t data_in, data_out; if (HAL_OK OnePin_Master_TransmitReceive(hOnePin, addr, 0x01, data_in, data_out, 30)) { // 将 data_out 发送至队列供其他任务处理 xQueueSend(sensor_data_queue, data_out, 0); } } vTaskDelay(100); // 每 100ms 扫描一轮 } }6. 与其他单线协议对比特性MD_OnePin1-Wire (DS18B20)SWD (ARM Debug)UART (单线半双工)硬件依赖无纯 GPIO专用 PHY需上拉专用 SWDIO/SWCLK需 UART 外设 TX/RX 复用开关主从关系严格 1 主 N 从1 主多从总线式1 主 1 从点对点地址机制8-bit 地址字段64-bit ROM ID无地址无地址最大速率~2.5 kbps (Tbase100μs)~15.4 kbps (Overdrive)~4 MHz1 MbpsMCU 资源占用 2KB Flash, 128B RAM4KB Flash (DS2480 驱动)硬件固化UART 外设 DMA适用场景成本敏感、引脚稀缺的定制传感器标准化温度传感网络调试与烧录高速、标准接口设备MD_OnePin 的不可替代性在于其极致的软硬件解耦开发者可将同一份从机固件烧录至任意 MCU仅需修改 GPIO 初始化代码即可接入主机系统。这种“一次开发、多平台部署”的能力使其成为构建异构嵌入式子系统的理想粘合剂。