简介这份资源是面向嵌入式与物联网开发者的sx126x系列LoRa芯片驱动代码包聚焦Semtech sx1262等调制解调器在STM32平台上的集成与使用帮助开发者快速搭建远距离、低功耗的LoRa/LoRaWAN通信节点。压缩包共6个文件包含3个.h头文件与3个.c源文件整体约29KB头文件用于声明寄存器配置、射频参数与对外接口源文件则实现初始化、SPI数据收发、中断处理及HAL层适配结构精简便于移植到不同MCU工程。资源已有672人学习下载适合需要将LoRa模块接入实际项目的工程师参考。通过阅读与调试这些代码读者可掌握频率、扩频因子、带宽等参数配置方法理解数据收发流程与低功耗管理思路并在此基础上集成LoRaWAN协议栈完成设备注册、上下行通信与可靠性优化为构建稳定高效的物联网无线方案提供可直接复用的驱动基础。1. LoRa模块sx126x驱动从寄存器手册到能跑通的收发链路拿到一块贴着 sx126x 的 LoRa 模块很多人第一反应是找现成驱动库编译、烧录、串口打印然后卡在“发送成功但收不到”或者“RSSI 一直是 -127”上。这个标题讲的就是把 sx126x 这颗射频芯片从寄存器层面驱动起来让 MCU 能通过 SPI 完成配置、发送、接收、中断处理这一整条链路。它解决的不是“LoRa 是什么”的问题而是“我手里这块模块怎么让它真的收发数据”。适合已经能点灯、能跑 SPI、但面对 sx126x 那一百多页寄存器手册不知道从哪下手的嵌入式工程师。下面按我实际调通的顺序把选型、初始化、收发、避坑和进阶验证拆开讲。2. 先搞清楚 sx126x 的驱动边界哪些事芯片做哪些事你必须做2.1 sx126x 不是“串口透传模块”别拿 AT 指令那套套市面上很多 LoRa 模块出厂就带 MCU对外是串口 AT 指令你发ATSEND它就帮你把射频配置好了。但 sx126x 是纯射频收发器SPI 从机没有内置协议栈没有自动重传没有地址过滤。它只负责把你要发的字节按 LoRa 调制发出去把收到的字节放进 FIFO 并拉一个 DIO 中断。剩下的组包、CRC 校验、应答、重传、休眠唤醒全是你 MCU 的事。这个边界不搞清楚驱动写出来就是“我调了 SetTx怎么没反应”。因为 sx126x 的很多操作是“命令 等待 BUSY 拉低 读状态”的时序不是发一条 SPI 就完事。常见做法是封装一层sx126x_wait_busy()每次写命令前先等 BUSY 引脚变低否则命令会被芯片忽略。2.2 硬件连接SPI 四线加 BUSY、DIO1、NSS、RESET以常见 STM32 接法为例sx126x 至少需要这些引脚引脚方向作用容易接错的地方SCK/MISO/MOSISPI数据时钟模式要 CPOL0 CPHA0NSSMCU 输出片选必须软件控制不能一直拉低BUSYMCU 输入芯片忙标志上电默认可能高要等它低DIO1MCU 输入中断输出映射到 TxDone/RxDone/TimeoutRESETMCU 输出硬复位低电平至少 100usNRESET—同上有的模块标 NRESET我一般先写一个sx126x_hw_init()把 RESET 拉低 200us 再拉高然后循环读 BUSY直到它为低才继续。这一步不做后面所有 SPI 读写都是玄学。2.3 驱动分层寄存器层、命令层、业务层我的习惯是分三层写寄存器层sx126x_write_reg()、sx126x_read_reg()、sx126x_write_buffer()、sx126x_read_buffer()只负责 SPI 时序和 BUSY 等待。命令层sx126x_set_standby()、sx126x_set_packet_type()、sx126x_set_rf_freq()、sx126x_set_tx_params()、sx126x_set_rx()每个函数对应手册里一条命令。业务层lora_send()、lora_receive()、lora_config()处理 FIFO 读写和中断标志。这样分层的好处是调不通的时候你能快速定位是 SPI 时序问题、命令参数问题还是业务逻辑问题。血泪经验很多人把三层揉在一起最后连“到底有没有写进寄存器”都验证不了。3. 用 SPI 把 sx126x 从复位带到 Standby最小可跑通命令序列3.1 复位后必须做的三件事等 BUSY、设 Standby、设 PacketType下面这段代码是我在 STM32 HAL 库上跑通的最小初始化片段SPI 速率先降到 1MHz 以下稳定后再提。// sx126x_min_init.c // 假设 spi_transfer() 已实现NSS 由软件控制 #include sx126x.h #define SX126X_CMD_SET_STANDBY 0x80 #define SX126X_CMD_SET_PACKET_TYPE 0x8A #define SX126X_CMD_SET_RF_FREQ 0x86 #define SX126X_CMD_SET_TX_PARAMS 0x8E #define SX126X_CMD_SET_MOD_PARAMS 0x8B #define SX126X_CMD_SET_PKT_PARAMS 0x8C #define SX126X_CMD_SET_BUFFER_BASE 0x8F #define SX126X_CMD_SET_DIO_IRQ 0x08 #define SX126X_CMD_SET_RX 0x82 #define SX126X_CMD_SET_TX 0x83 #define SX126X_CMD_GET_IRQ_STATUS 0x12 #define SX126X_CMD_CLR_IRQ_STATUS 0x02 #define SX126X_CMD_WRITE_BUFFER 0x0E #define SX126X_CMD_READ_BUFFER 0x1E static void sx126x_wait_busy(void) { uint32_t timeout 100000; while (HAL_GPIO_ReadPin(BUSY_GPIO_Port, BUSY_Pin) GPIO_PIN_SET) { if (--timeout 0) break; // 实际项目要报错 } } static void sx126x_cmd(uint8_t cmd, uint8_t *param, uint16_t len) { sx126x_wait_busy(); NSS_LOW(); spi_transfer(cmd); for (uint16_t i 0; i len; i) spi_transfer(param[i]); NSS_HIGH(); } void sx126x_min_init(void) { // 1. 硬复位 HAL_GPIO_WritePin(RESET_GPIO_Port, RESET_Pin, GPIO_PIN_RESET); HAL_Delay(1); HAL_GPIO_WritePin(RESET_GPIO_Port, RESET_Pin, GPIO_PIN_SET); HAL_Delay(10); sx126x_wait_busy(); // 2. 进入 Standby RC uint8_t standby 0x00; sx126x_cmd(SX126X_CMD_SET_STANDBY, standby, 1); // 3. 设 LoRa 包类型 uint8_t pkt_type 0x01; // 0x01 LoRa sx126x_cmd(SX126X_CMD_SET_PACKET_TYPE, pkt_type, 1); }逻辑说明sx126x_wait_busy()是后面所有命令的前提BUSY 高时芯片不接收 SPI 命令。SET_STANDBY参数 0x00 是 RC 振荡器功耗低且启动快。SET_PACKET_TYPE设成 0x01 表示 LoRa 模式设成 0x00 是 FSK别搞反。参数说明SPI 速率建议先 1MHz调通后可以到 8MHz 甚至 16MHz但要看你的走线和 MCU 能力。RESET 低电平时间手册要求最小 100us我一般给 1ms 余量。3.2 设频率、发射功率、调制参数四个必调参数频率不是随便填sx126x 的SetRfFrequency参数是freq (RF_freq_hz 25) / 32e6。比如 470MHz// 470MHz 对应寄存器值 uint32_t rf_freq (uint32_t)((470000000.0 * 25.0) / 32000000.0); uint8_t buf[4] { (uint8_t)(rf_freq 24), (uint8_t)(rf_freq 16), (uint8_t)(rf_freq 8), (uint8_t)(rf_freq) }; sx126x_cmd(SX126X_CMD_SET_RF_FREQ, buf, 4);发射功率用SetTxParams参数是功率 dBm 和 ramp time。比如 14dBmuint8_t tx_params[2] {14, 0x04}; // 0x04 200us ramp sx126x_cmd(SX126X_CMD_SET_TX_PARAMS, tx_params, 2);调制参数SetModulationParams三个关键值SF、BW、CR。SF7~SF12BW 常用 125kHzCR 用 4/5。对应字节uint8_t mod_params[8] { 0x07, // SF7 0x04, // BW 125kHz 0x01, // CR 4/5 0x00, // LDRO 关 0x00, 0x00, 0x00, 0x00 // 保留 }; sx126x_cmd(SX126X_CMD_SET_MOD_PARAMS, mod_params, 8);包参数SetPacketParams设前导码长度、包头类型、payload 长度、CRC 开关。显式包头、CRC 开uint8_t pkt_params[9] { 0x00, 0x08, // 前导码 8 符号 0x00, // 显式包头 0x10, // payload 长度 16 0x01, // CRC 开 0x00, // 标准 IQ 0x00, 0x00, 0x00 }; sx126x_cmd(SX126X_CMD_SET_PKT_PARAMS, pkt_params, 9);这四个参数不匹配收发双方就是互相听不见。我一般把双方配置打印出来逐字节对比猜快得多。3.3 中断映射与清除DIO1 到底该拉在哪个事件上sx126x 的中断源很多TxDone、RxDone、CRCErr、Timeout、CadDone 等。通过SetDioIrqParams把你要的事件映射到 DIO1// 使能 TxDone 和 RxDone 到 DIO1 uint16_t irq_mask 0x0002 | 0x0004; // TxDonebit1, RxDonebit2 uint8_t irq_params[8] { (uint8_t)(irq_mask 8), (uint8_t)(irq_mask), (uint8_t)(irq_mask 8), (uint8_t)(irq_mask), 0x00, 0x00, 0x00, 0x00 }; sx126x_cmd(SX126X_CMD_SET_DIO_IRQ, irq_params, 8);中断来了之后必须读GetIrqStatus再ClearIrqStatus否则下次中断不会触发。这是新手最容易翻车的地方以为清了标志其实没清然后卡死在等待里。4. 收发链路跑通从 FIFO 写入到 DIO1 中断读数据4.1 发送写 Buffer、设 Tx、等 TxDone发送流程是SetStandby→SetBufferBase→WriteBuffer→SetPacketParams更新长度→SetTx→ 等 DIO1 TxDone →ClearIrqStatus。void lora_send(uint8_t *data, uint8_t len) { uint8_t base 0x00; sx126x_cmd(SX126X_CMD_SET_BUFFER_BASE, base, 1); sx126x_wait_busy(); NSS_LOW(); spi_transfer(SX126X_CMD_WRITE_BUFFER); spi_transfer(0x00); // offset for (uint8_t i 0; i len; i) spi_transfer(data[i]); NSS_HIGH(); // 更新 payload 长度 uint8_t pkt_params[9] {0x00, 0x08, 0x00, len, 0x01, 0x00, 0x00, 0x00, 0x00}; sx126x_cmd(SX126X_CMD_SET_PKT_PARAMS, pkt_params, 9); // 启动发送超时 0 表示不限 uint8_t tx_buf[3] {0x00, 0x00, 0x00}; sx126x_cmd(SX126X_CMD_SET_TX, tx_buf, 3); // 等 DIO1 拉高实际项目用中断或轮询 while (HAL_GPIO_ReadPin(DIO1_GPIO_Port, DIO1_Pin) GPIO_PIN_RESET); uint8_t irq[2]; sx126x_read_cmd(SX126X_CMD_GET_IRQ_STATUS, irq, 2); sx126x_cmd(SX126X_CMD_CLR_IRQ_STATUS, irq, 2); }逻辑说明WriteBuffer的 offset 一般填 0x00表示从 FIFO 起始写。SetTx三个字节是超时值全 0 表示不超时实际项目建议设一个合理超时比如 3000ms 对应值。等 DIO1 这里用轮询是为了演示真实项目用 EXTI 中断更稳。参数说明payload 长度要和实际写入字节数一致不一致会导致发出去的数据被截断或补零。CRC 开了之后接收端 CRC 错误会置 CRCErr 标志不会触发 RxDone。4.2 接收设 Rx、等 RxDone、读 Buffer接收流程SetStandby→SetBufferBase→SetRx→ 等 DIO1 RxDone →GetRxBufferStatus拿长度和偏移 →ReadBuffer。uint8_t lora_receive(uint8_t *out, uint8_t max_len) { uint8_t base 0x00; sx126x_cmd(SX126X_CMD_SET_BUFFER_BASE, base, 1); // 进入接收超时值 0xFFFFFF 表示长接收 uint8_t rx_buf[3] {0xFF, 0xFF, 0xFF}; sx126x_cmd(SX126X_CMD_SET_RX, rx_buf, 3); while (HAL_GPIO_ReadPin(DIO1_GPIO_Port, DIO1_Pin) GPIO_PIN_RESET); uint8_t irq[2]; sx126x_read_cmd(SX126X_CMD_GET_IRQ_STATUS, irq, 2); uint16_t status (irq[0] 8) | irq[1]; if (status 0x0004) { // RxDone uint8_t rx_status[2]; sx126x_read_cmd(0x13, rx_status, 2); // GetRxBufferStatus uint8_t len rx_status[0]; uint8_t offset rx_status[1]; if (len max_len) len max_len; sx126x_wait_busy(); NSS_LOW(); spi_transfer(SX126X_CMD_READ_BUFFER); spi_transfer(offset); spi_transfer(0x00); // 占位 for (uint8_t i 0; i len; i) out[i] spi_transfer(0x00); NSS_HIGH(); sx126x_cmd(SX126X_CMD_CLR_IRQ_STATUS, irq, 2); return len; } sx126x_cmd(SX126X_CMD_CLR_IRQ_STATUS, irq, 2); return 0; }逻辑说明GetRxBufferStatus命令码是 0x13返回两个字节payload 长度和 FIFO 偏移。ReadBuffer要先发命令码、再发偏移、再发一个 dummy 字节然后才开始读数据。这个时序错了读出来全是 0xFF。参数说明SetRx的超时值三个字节0xFFFFFF 表示无限等待实际项目建议设成周期接收比如 1000ms 超时后重新进 Rx避免死等。4.3 用 DIO1 中断替代轮询EXTI 配置与中断服务函数轮询只适合验证真实产品必须用中断。配置 MCU 的 EXTI 下降沿或上升沿触发看模块 DIO1 极性在中断里置一个标志主循环处理。volatile uint8_t lora_irq_flag 0; void HAL_GPIO_EXTI_Callback(uint16_t GPIO_Pin) { if (GPIO_Pin DIO1_Pin) { lora_irq_flag 1; } } // 主循环 if (lora_irq_flag) { lora_irq_flag 0; uint8_t irq[2]; sx126x_read_cmd(SX126X_CMD_GET_IRQ_STATUS, irq, 2); // 根据 irq 处理 TxDone 或 RxDone sx126x_cmd(SX126X_CMD_CLR_IRQ_STATUS, irq, 2); }注意中断里不要做 SPI 读写SPI 可能被其他任务占用。置标志、主循环处理这是最稳的做法。5. 避坑与排查sx126x 驱动最常见的五个翻车点5.1 现象SPI 读出来全是 0x00 或 0xFF原因BUSY 没等或者 NSS 时序不对或者 SPI 模式设成了 CPHA1。sx126x 要求 SPI 模式 0CPOL0CPHA0NSS 在传输期间保持低传输完拉高。解决先用示波器看 SCK 和 MOSI确认有波形再把 SPI 速率降到 100kHz检查sx126x_wait_busy()是否在每次命令前调用。我遇到过 NSS 拉低后没延时直接发数据芯片没反应过来加 1us 延时就好了。5.2 现象发送完成但接收端无数据RSSI 为 -127原因频率、SF、BW、CR、前导码、包头类型、CRC 配置不一致。最常见的是频率算错比如 470MHz 算成了 470000 而不是 470000000。解决双方打印所有射频参数逐项对比。用GetRssiInst命令读瞬时 RSSI如果一直是 -127说明根本没收到信号检查天线和频率。5.3 现象进不了 RxDone 中断或中断只触发一次原因中断标志没清或者 DIO1 映射没设对或者SetRx超时值设成了 0。解决每次中断后必须ClearIrqStatus。检查SetDioIrqParams的 irq_mask 是否包含了 RxDone。SetRx超时值不要设 0设一个合理值比如 0xFFFFFF。5.4 现象发送距离短一堵墙就断原因发射功率没设对或者天线匹配没做好或者 SF 太低、BW 太宽。解决SetTxParams功率设到模块允许的最大值常见 14dBm 或 22dBm看模块 PA。SF 从 7 提到 9 或 10BW 从 250kHz 降到 125kHz。天线要接对没有天线不要发射容易烧 PA。5.5 现象低功耗模式下电流降不下来原因没进 Sleep 模式或者 DIO1 还使能着中断或者 SPI 引脚漏电。解决不用的时候发SetSleep命令参数 0x04 表示冷启动。把 DIO1 中断关掉SPI 引脚设成模拟输入或输出低。实测 Sleep 模式电流可以到 1uA 以下但要看模块外围电路。6. 进阶验证用 RSSI 和 SNR 判断链路质量再决定要不要上 CAD6.1 读 RSSI 和 SNR两个比“收到没”更有用的指标RxDone 之后除了读数据还可以读包状态GetPacketStatus命令码 0x14返回三字节RSSI、SNR、信号 RSSI。RSSI 是负值单位 dBm越接近 0 越强。SNR 是信噪比LoRa 能在负 SNR 下解调SF12 可以到 -20dB。uint8_t pkt_status[3]; sx126x_read_cmd(0x14, pkt_status, 3); int8_t rssi -(int8_t)(pkt_status[0] / 2); int8_t snr (int8_t)pkt_status[1] / 4;我一般把这两个值通过串口打出来移动节点看变化。RSSI 低于 -120dBm 基本就到极限了SNR 低于 -15 误码率会明显上升。6.2 用 CAD 做信道活动检测省电接收的前置判断CADChannel Activity Detection可以在不完整接收的情况下判断信道有没有 LoRa 前导码。适合电池供电的节点周期唤醒做 CAD有信号才进 Rx。// 设 CAD 参数 uint8_t cad_params[7] {0x02, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}; sx126x_cmd(0x88, cad_params, 7); // SetCadParams // 启动 CAD uint8_t cad_tx[0]; sx126x_cmd(0xC5, cad_tx, 0); // SetCad // 等 DIO1 CadDone读 IrqStatus 判断 CadDetectedCAD 不是万能的它只能检测前导码不能保证数据一定能解出来。我一般用在“平时休眠定时 CAD有前导码再开 Rx”的场景实测能省不少电。6.3 一个我常做的验证习惯先回环再拉距每次改完驱动我先把一块板子设成发送另一块设成接收距离一米看能不能收到。通了之后把发送端放远每 10 米记一次 RSSI 和 SNR画一条曲线。这样你能知道你的配置在什么距离下开始丢包比盲目调参数靠谱。最后说一句sx126x 驱动不难难的是耐心对时序、对参数、对中断标志。希望帮到你。本文还有配套的精品资源点击获取
