简介：这份驱动源码面向嵌入式与物联网开发者，聚焦Semtech新一代LoRa芯片SX1261、SX1262与SX1268的底层控制，解决从硬件初始化到收发数据、信道检测的完整驱动实现问题，适合具备C语言与STM32基础、希望快速上手远距离低功耗无线方案的中级开发者。压缩包共611个文件，约3.64MB，以328个.h头文件与261个.c源文件为主体，辅以6个汇编启动文件、Keil工程与调试配置及少量链接脚本、说明文档和示例固件，覆盖STM32L0/L1/L4多个HAL外设驱动，便于按芯片型号裁剪移植。资源中附带的CAD示例程序演示了信道活动检测的用法，可帮助理解扩频参数配置、发送接收流程、错误处理与状态管理等关键模块。目前已有2374人学习下载，可作为搭建LoRa节点、验证链路预算与优化功耗的实用参考。

1. 从一块调不通的 LoRa 模块说起

去年帮一个做环境监测的朋友收拾烂摊子，他们买了一批 SX1262 模组，SPI 能读到版本号，但一进发送就卡死，接收端永远收不到包。翻他们代码，驱动是从某开源仓库抄来的，寄存器地址还是 SX127x 那一套，射频开关控制脚干脆没接。这类问题在 LoRa 项目里太常见了：芯片手册几百页，时序图密密麻麻，驱动写错一个位就表现为「玄学不通」。这份 SX126x 驱动源码就是来解决这件事的——它把 SX1262、SX1268 这两颗新一代 LoRa 芯片的初始化、收发、中断、休眠全流程封装好了，适合正在做低功耗远距离通信、又不想从寄存器手册第一页啃起的嵌入式开发者。下面我按「这项目是什么、怎么跑起来、怎么改」的顺序拆一遍，中间夹着我踩过的坑。

2. 驱动架构拆解：从 SPI 时序到收发状态机

2.1 分层结构与文件职责

这套驱动的组织方式很典型，属于「硬件抽象 + 协议逻辑」两层。硬件抽象层只干一件事：把 MCU 的 SPI、GPIO、延时函数对接进来，换平台时只改这一层。协议逻辑层负责命令组包、状态机推进、中断解析，跟具体 MCU 无关。目录大致是这样：

sx126x_driver/ ├── src/ │ ├── sx126x.c # 核心驱动：命令、状态机、收发 │ ├── sx126x_hal.c # 硬件抽象：SPI 读写、复位、天线开关 │ └── sx126x_regs.h # 寄存器与命令操作码定义 ├── inc/ │ ├── sx126x.h # 对外 API │ └── sx126x_hal.h # HAL 接口声明 └── example/ └── main.c # 最小收发示例

核心文件是sx126x.c，它内部维护一个 radio 状态结构体，记录当前是待机、发送还是接收，所有 API 调用前都会校验状态，避免在错误状态下发命令导致芯片挂死。sx126x_hal.c里最容易被忽略的是天线开关（RF switch）控制，SX1262 本身不管射频通路切换，模组上通常有 TX/RX 两路开关，靠 GPIO 拉高拉低，这一步漏了就是「能发不能收」或者「收发都弱」。

2.2 命令交互模型：为什么每次操作都要等 BUSY

SX126x 跟老一代最大的区别是引入了 BUSY 引脚。芯片执行任何命令期间 BUSY 拉高，此时 SPI 不接受新命令。驱动里所有底层操作都包了一层等待：

/* sx126x_hal.c 片段：带 BUSY 等待的 SPI 写命令 */ int32_t sx126x_hal_write(const void *context, const uint8_t *cmd, uint16_t cmd_len, const uint8_t *data, uint16_t data_len) { const hal_context_t *ctx = (const hal_context_t *)context; /* 命令下发前必须等 BUSY 释放，否则芯片丢弃本次 SPI 帧 */ while (gpio_read(ctx->busy_pin) == 1) { if (--timeout == 0) return SX126X_HAL_TIMEOUT; } gpio_write(ctx->nss_pin, 0); /* 片选拉低 */ spi_transfer(cmd, NULL, cmd_len); /* 先发操作码 + 参数 */ if (data_len > 0) spi_transfer(data, NULL, data_len); gpio_write(ctx->nss_pin, 1); /* 片选拉高，帧结束 */ return SX126X_HAL_OK; }

这段的关键点有三个。第一，busy_pin的轮询必须有超时，我见过有人写成死循环while(busy);，芯片一旦异常拉高就整机卡死，现场只能断电。第二，片选nss_pin的拉低拉高必须包住整帧，中途松开会被芯片当成两帧解析。第三，spi_transfer的发送和接收要分开处理，SX126x 的读命令是「先发操作码，再发 dummy 字节换回数据」，写命令则是「操作码 + 数据」一口气发完，两者帧格式不同，混用就会读到全 0xFF。

2.3 收发状态机与中断映射

发送流程是：置待机 → 配包参数 → 写 FIFO → 发SET_TX命令 → 等TX_DONE中断。接收流程对称：置待机 → 配包参数 → 发SET_RX→ 等RX_DONE或TIMEOUT中断。驱动把 DIO1 中断引脚映射成事件回调，示例里是这样接的：

/* example/main.c 片段：中断回调里分发事件 */ void on_dio1_irq(void) { sx126x_irq_mask_t irq = sx126x_get_irq_status(&radio); if (irq & SX126X_IRQ_TX_DONE) { sx126x_clear_irq_status(&radio, SX126X_IRQ_TX_DONE); app_state = APP_TX_DONE; } if (irq & SX126X_IRQ_RX_DONE) { sx126x_clear_irq_status(&radio, SX126X_IRQ_RX_DONE); /* 读 FIFO 前先取长度和起始指针，别直接读 */ uint8_t len = sx126x_get_rx_payload_length(&radio); sx126x_read_buffer(&radio, offset, buf, len); app_state = APP_RX_DONE; } if (irq & SX126X_IRQ_TIMEOUT) { sx126x_clear_irq_status(&radio, SX126X_IRQ_TIMEOUT); app_state = APP_RX_TIMEOUT; } }

中断状态是「读后需手动清」的，不清就会反复进中断，表现为程序一直在回调里打转、主循环饿死。另外RX_DONE之后读 FIFO 要先拿 payload length 和 buffer 起始偏移，这两个值在RX_DONE时刻才有效，提前读是脏数据。状态机的好处是主循环只关心app_state，不用在中断里做耗时操作，把读 FIFO 这种几十微秒的动作放到主循环更稳。

3. 跑通第一个包：环境搭建与最小收发验证

3.1 硬件连线与平台适配清单

先把线接对，这一步错了后面全是白费。SX1262 模组到 MCU 至少需要这些连接：

SPI 模式必须是 0（CPOL=0, CPHA=0），我见过用模式 3 结果读回全错的案例。BUSY 和 DIO1 是最容易省掉的两根线，省了 BUSY 就得靠固定延时硬等，省了 DIO1 就得轮询寄存器，功耗和实时性都差一截。

3.2 移植 HAL 层：四个函数搞定换平台

换 MCU 时只需要实现sx126x_hal.h里声明的几个函数，核心是读写、复位、延时：

/* 移植模板：以某 Cortex-M 平台为例 */ int32_t sx126x_hal_reset(const void *context) { gpio_write(reset_pin, 0); delay_ms(1); /* 手册要求复位低电平至少 100us，取 1ms 稳妥 */ gpio_write(reset_pin, 1); delay_ms(10); /* 复位后等芯片内部起振 */ return SX126X_HAL_OK; } uint32_t sx126x_hal_get_tick(void) { return systick_get_ms(); /* 返回毫秒计数，用于超时判断 */ }

delay_ms的精度不用太高，但复位后的 10ms 别省，芯片内部 RC 起振和校准需要时间，省了会偶发初始化失败——这种偶发最坑，十次里错一次，产线抽检根本发现不了。SPI 读写函数里记得处理data_len为 0 的情况，很多读命令只有操作码没有数据段。

3.3 最小收发示例与验证方法

初始化顺序建议照抄示例：复位 → 配待机模式 → 设调制参数（频点、扩频因子、带宽、编码率）→ 设包参数（前导码长度、包头类型、CRC 开关）→ 设 DIO 映射 → 进接收。验证时先别急着发数据，用下面这段读版本号，能读回非 0 值说明 SPI 通路是通的：

uint16_t ver = 0; sx126x_read_register(&radio, SX126X_REG_VERSION_STRING, (uint8_t *)&ver, 2); printf("chip version: 0x%04X\n", ver);

版本号读通后再跑收发。两个模组对发时，频点和扩频因子必须完全一致，带宽和编码率也要一致，任何一项不同都表现为「收不到」。我一般先用 SF7、BW125、CR4/5 这组保守参数跑通，再往远距离参数调。发送端发完看TX_DONE，接收端看RX_DONE和 payload 长度，两边日志一对，链路就通了。

4. 避坑与排查：那些让链路时通时断的细节

4.1 现象：能发不能收，或接收灵敏度极差

原因几乎都出在天线开关。SX1262 芯片本身没有射频开关控制逻辑，模组上的 TX/RX 通路切换靠外部 GPIO。驱动里sx126x_set_rf_switch这类函数如果没在发送前切到 TX、接收前切到 RX，信号就走错通路，表现为发射功率正常但接收端收不到，或者接收灵敏度比手册低十几 dB。解决方法是把开关控制挂进状态切换：进 TX 前置 TX 使能、进 RX 前置 RX 使能，并在待机时两路都关掉省电。

4.2 现象：偶发初始化失败，重启又好了

多半是复位时序或电源问题。复位低电平时间不够、复位后等待不足、或者供电在发射瞬间跌落，都会导致芯片内部校准失败。排查时先用示波器看 NRESET 波形和 VDD 在发射瞬间的跌落幅度，再确认sx126x_hal_reset里的延时是否被编译器优化掉（delay_ms要用带volatile的循环或硬件定时器）。电源侧在模组 VDD 脚就近加 10uF + 100nF，发射电流峰值能到 100mA 以上，走线细了必跌。

4.3 现象：中断进不去，或进去出不来

进不去先查 DIO1 有没有配成外部中断、触发沿是上升沿还是下降沿（SX126x 默认高有效），再查中断映射有没有把对应事件映射到 DIO1。出不来就是中断标志没清，注意sx126x_clear_irq_status要清的是「读到的那个位」，别一股脑全清，否则会丢掉同时到达的其他事件。还有一种隐蔽情况：在中断里调用了带 BUSY 等待的 API，BUSY 一直不释放导致中断卡死，正确做法是中断里只置标志，耗时操作放主循环。

4.4 现象：通信距离远低于预期

先排除参数问题：扩频因子调大、带宽调小能显著提升灵敏度，但速率会降。再查前导码长度，接收端前导码检测窗口太短会漏包，一般设 8 个符号以上。最后查晶振，SX126x 对 32MHz 晶振的负载电容和频偏敏感，频偏偏大会导致收发双方频点对不齐，表现为近距离能通、远距离丢包。用频谱仪看发射中心频率是否落在目标频点上，偏了就调负载电容。

5. 二次开发：把驱动接进自己的业务框架

驱动本身只到「收发一个包」这一层，真正落地要往上包协议。我的习惯是在驱动之上加一层轻量帧管理：固定帧头 + 长度 + 序号 + CRC，接收侧做超时重传和去重。改造时优先动sx126x.c的对外 API 层，别去改 HAL，HAL 保持薄，换平台才不痛。参数配置建议抽成结构体从配置文件读，频点和扩频因子按区域和场景区分，别硬编码在初始化函数里。

验证改造是否成功，我一般跑三步：单包收发确认链路、连续发 1000 包统计丢包率、低功耗模式下测休眠电流和唤醒时延。第三步最容易翻车，休眠前没把射频开关和 DIO 配好，唤醒后第一包必丢。从那以后我每次改完驱动，都强制走一遍「复位 → 读版本 → 单包 → 连发 → 休眠唤醒」这条回归链，少一步都不敢上板。希望帮到你。

本文还有配套的精品资源，点击获取