SX126x LoRa驱动移植与避坑指南：从SPI时序到收发状态机

简介：这份资源面向嵌入式与物联网开发者，提供Semtech新一代LoRa芯片SX1261、SX1262、SX1268的驱动源码，解决从硬件初始化到收发控制、信道检测的底层对接问题，适合具备C语言与STM32基础、正在做远距离低功耗无线通信项目的中级开发者。压缩包共611个文件，约3.64MB，以328个.h头文件和261个.c源文件为主体，涵盖驱动接口声明与实现，并附带STM32各系列HAL库文件、6个.s启动汇编、Keil工程文件（uvprojx/uvoptx）及链接脚本，另含一份PDF文档与CAD示例固件，便于直接编译验证。资源已有2374人学习下载，参考价值较为明确。读者可从中获得完整的驱动分层结构、参数配置思路（频率、功率、扩频因子、编码率）以及CAD信道活动检测的示例代码，用于理解待机低功耗设计与收发状态管理，并在此基础上裁剪适配自己的硬件平台，减少从零搭建驱动的调试成本。

1. 拿到一份 SX126x 驱动源码，先别急着编译

去年帮一个做农业传感器的团队调 LoRa 链路，他们从某芯片原厂拿到一份 SX1262 驱动包，扔进工程里编译过了，但一上电就卡在sx126x_wait_on_busy里出不来。翻了两天才发现，是 SPI 的 NSS 引脚在初始化前被拉低，芯片根本没进配置模式。这件事让我形成一个习惯：拿到任何一份 SX126x 驱动源码，先看它怎么处理 BUSY 引脚和复位时序，而不是先看能不能编译通过。

这份资源是一套面向 SX1262、SX1268 的 LoRa 收发驱动源码，覆盖射频初始化、寄存器配置、包收发、中断处理这几块。它适合两类人：一类是手上已经有 SX126x 模组、想快速把点对点链路跑起来的嵌入式开发者；另一类是想把驱动移植到自己 MCU 平台、需要一份结构清晰的参考实现的人。下面按「这项目是什么 → 怎么跑起来 → 怎么改」的顺序拆。

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

2.1 分层结构：硬件抽象层与射频逻辑层怎么切

这份驱动的分层思路比较典型，大致可以分成三层。最底下是硬件抽象层，负责 SPI 读写、GPIO 控制（NSS、RESET、BUSY、DIO1）、延时函数，这一层通常放在sx126x_hal.c或类似文件里，和具体 MCU 强相关。中间是寄存器与命令层，把 SX126x 的命令集封装成函数，比如sx126x_set_standby、sx126x_set_rf_freq、sx126x_set_pkt_params，这一层只依赖 HAL 提供的读写接口。最上面是收发逻辑层，处理发送、接收、超时、中断回调。

这种切法的好处是移植成本低。换 MCU 时只改 HAL 层那几个函数，上层逻辑基本不动。我一般会先确认 HAL 层暴露了哪些接口，常见的是这几个：

/* sx126x_hal.h —— 硬件抽象层接口，移植时主要改这里 */ int32_t sx126x_hal_write(const void *context, const uint8_t *cmd, uint16_t cmd_len, const uint8_t *data, uint16_t data_len); int32_t sx126x_hal_read(const void *context, const uint8_t *cmd, uint16_t cmd_len, uint8_t *data, uint16_t data_len); int32_t sx126x_hal_reset(const void *context); int32_t sx126x_hal_wakeup(const void *context);

context一般指向一个包含 SPI 句柄和 GPIO 描述的结构体，这样驱动本身不依赖全局变量。sx126x_hal_write的语义是「先发命令字节，再发数据字节」，中间 NSS 保持低电平；sx126x_hal_read则是「发命令字节，然后读回数据」。这两个函数的实现质量直接决定驱动稳不稳，后面避坑章节会细说。

2.2 初始化链路：复位、待机、校准的顺序不能乱

SX126x 上电后的初始化顺序是有讲究的。比较稳妥的流程是：硬件复位 → 等待 BUSY 拉低 → 进入 STDBY_RC 模式 → 设置 regulator 模式 → 配置 TCXO（如果模组带 TCXO）→ 校准 → 设置频点和调制参数。这份驱动里对应的调用链大致如下：

/* 初始化主流程，参数按模组实际情况填 */ sx126x_reset(&dev); /* 拉低 RESET 再释放，等 BUSY */ sx126x_wait_on_busy(&dev); /* 必须等，超时要报错 */ sx126x_set_standby(&dev, SX126X_STANDBY_CFG_RC); sx126x_set_reg_mode(&dev, SX126X_REG_MODE_DCDC); /* 模组用电感则选 DCDC */ sx126x_set_dio3_as_tcxo_ctrl(&dev, SX126X_TCXO_CTRL_1_8V, 320); /* 32ms 超时 */ sx126x_cal(&dev, SX126X_CAL_ALL); sx126x_set_rf_freq(&dev, 868000000); /* 单位 Hz，SX1262 常用 868M */ sx126x_set_pkt_type(&dev, SX126X_PKT_TYPE_LORA); sx126x_set_mod_params(&dev, SX126X_LORA_SF9, SX126X_LORA_BW_125, SX126X_LORA_CR_4_5, SX126X_LORA_LDW_ON);

这里几个参数值得展开。SX126X_REG_MODE_DCDC和SX126X_REG_MODE_LDO的选择取决于模组电源设计，选错不一定立刻挂，但发射效率会差一截。set_dio3_as_tcxo_ctrl的第三个参数是 TCXO 起振等待时间，单位是 15.625us 的倍数，320 对应约 5ms，实际要按 TCXO 规格留余量。set_rf_freq传的是 Hz，不是 MHz，我第一次移植时就因为传了 868 而不是 868000000，芯片一直不出载波。

2.3 收发状态机：中断驱动还是轮询

驱动对收发的处理有两种常见风格：轮询 DIO1 和中断驱动。这份源码两种都留了接口，但主流程推荐中断驱动。发送侧调用sx126x_set_tx后进入 TX 状态，TX_DONE 中断到来时读 IRQ 状态并清标志；接收侧调用sx126x_set_rx后等 RX_DONE，然后读缓冲区长度和内容。

/* 中断回调里处理 IRQ，注意先读再清 */ void sx126x_on_dio1_irq(sx126x_t *dev) { uint16_t irq = 0; sx126x_get_irq_status(dev, &irq); if (irq & SX126X_IRQ_TX_DONE) { sx126x_clear_irq_status(dev, SX126X_IRQ_TX_DONE); dev->tx_done = true; } if (irq & SX126X_IRQ_RX_DONE) { uint8_t len = 0; sx126x_get_rx_buffer_status(dev, &len, NULL); sx126x_read_buffer(dev, 0, dev->rx_buf, len); sx126x_clear_irq_status(dev, SX126X_IRQ_RX_DONE); dev->rx_len = len; } if (irq & SX126X_IRQ_TIMEOUT) { sx126x_clear_irq_status(dev, SX126X_IRQ_TIMEOUT); dev->rx_timeout = true; } }

get_irq_status必须在clear_irq_status之前调用，否则标志被清掉就读不到了。read_buffer的偏移传 0 表示从 RX 缓冲区头部读，长度来自get_rx_buffer_status。这段代码看着简单，但中断上下文里做 SPI 读要注意别和主循环的 SPI 访问打架，常见做法是加互斥或者把处理挪到任务里。

3. 跑通第一条链路：编译、接线与参数配置

3.1 工程组织与编译入口

驱动源码通常以「一对 .c/.h」的形式给出，核心文件是sx126x.c、sx126x.h，外加sx126x_hal.c、sx126x_hal.h和一份sx126x_regs.h寄存器定义。移植到自己的工程时，把这几个文件加进编译列表，然后在 HAL 层实现前面说的四个函数。如果用的是某款常见 MCU 的 HAL 库，SPI 收发可以这样写：

/* 以某 MCU HAL 为例，NSS 用软件控制 */ int32_t sx126x_hal_write(const void *ctx, const uint8_t *cmd, uint16_t cmd_len, const uint8_t *data, uint16_t data_len) { const hal_ctx_t *h = (const hal_ctx_t *)ctx; gpio_write(h->nss_port, h->nss_pin, 0); /* NSS 拉低 */ spi_transmit(h->spi, cmd, cmd_len); if (data && data_len) spi_transmit(h->spi, data, data_len); gpio_write(h->nss_port, h->nss_pin, 1); /* NSS 拉高 */ return 0; }

注意 NSS 必须在整条命令期间保持低电平，不能每发一个字节就翻转。有些 SPI 外设支持硬件 NSS，但 SX126x 对时序比较敏感，我一般还是用软件控制，时序更可控。编译时如果报sx126x_regs.h找不到，检查头文件搜索路径有没有加上驱动目录。

3.2 接线检查清单与上电自检

接线错了是新手最常见的翻车点。SX126x 模组至少需要这些线：SPI 的 SCK、MOSI、MISO、NSS，加上 RESET、BUSY、DIO1，如果模组带 TCXO 还要确认 TCXO 供电使能。上电后先做一次自检：读芯片版本号或者状态，能读通说明 SPI 链路没问题。

/* 上电自检：读 status，确认 SPI 通路 */ uint8_t status = 0; sx126x_get_status(&dev, &status); if ((status & 0x0F) == 0x00) { /* 读不到有效状态，优先查 NSS、SCK、MISO */ }

BUSY 引脚一定要接，而且要有上拉或明确电平，浮空会导致wait_on_busy随机超时。DIO1 不接的话中断驱动就跑不起来，只能轮询。我见过有人把 BUSY 和 DIO1 接反，现象是初始化偶尔过、收发全乱，查起来很费时间。

3.3 频点、扩频因子与带宽的搭配

LoRa 参数不是随便填的。频点要跟模组和当地规范匹配，SX1262 常见 868M，SX1268 常见 470M。扩频因子 SF 越大，灵敏度越高但速率越低；带宽 BW 越宽，速率越高但灵敏度下降。点对点测试建议先用 SF9、BW125、CR4/5 这组折中参数，链路通了再按距离需求调。

发送和接收两端的这些参数必须完全一致，包括前导码长度和是否开启 CRC。参数不一致的典型现象是接收方偶尔收到乱码或者完全收不到，但 RSSI 看着正常。

4. 核心代码逐段看：发送、接收与低功耗

4.1 发送流程：从写缓冲区到 TX_DONE

一次完整发送包含：切到 STDBY → 设置包参数 → 写 payload 到缓冲区 → 设置 TX 超时 → 启动 TX → 等 TX_DONE。驱动里通常封装成sx126x_send，内部再拆成几个小函数。

int sx126x_send(sx126x_t *dev, const uint8_t *buf, uint8_t len, uint32_t timeout_ms) { sx126x_set_standby(dev, SX126X_STANDBY_CFG_RC); sx126x_set_pkt_params(dev, 8, SX126X_LORA_HEADER_EXPLICIT, len, SX126X_LORA_CRC_ON, SX126X_LORA_IQ_STD); sx126x_write_buffer(dev, 0, buf, len); /* 偏移 0 写 TX 缓冲 */ sx126x_set_tx(dev, timeout_ms * 1000); /* 单位 us，内部换算 */ return sx126x_wait_tx_done(dev, timeout_ms); /* 轮询或等中断 */ }

set_pkt_params里的前导码长度、包头类型、payload 长度、CRC 开关、IQ 极性要跟接收端对齐。set_tx的超时参数单位是 15.625us 的倍数，驱动内部一般会做换算，传毫秒更直观。wait_tx_done如果走轮询，要定期读 IRQ 状态，别死等 DIO1。

4.2 接收流程：缓冲区读取与超时处理

接收侧的关键是设置好 RX 超时，避免无限等待。单次接收可以用set_rx带超时，连续接收则用set_rx_duty_cycle或者收到一包后重新进入 RX。

int sx126x_recv(sx126x_t *dev, uint8_t *buf, uint8_t *len, uint32_t timeout_ms) { sx126x_set_rx(dev, timeout_ms * 1000); if (sx126x_wait_rx_done(dev, timeout_ms) != 0) return -1; /* 超时 */ uint8_t payload_len = 0; sx126x_get_rx_buffer_status(dev, &payload_len, NULL); sx126x_read_buffer(dev, 0, buf, payload_len); *len = payload_len; sx126x_clear_irq_status(dev, SX126X_IRQ_RX_DONE); return 0; }

get_rx_buffer_status返回的 payload 长度是实际收到的字节数，可能小于配置的最大长度。读缓冲区之前一定要先拿这个长度，否则会读到脏数据。超时后要清 TIMEOUT 标志并重新进入 RX，不然下一次接收可能直接返回旧状态。

4.3 低功耗模式：睡眠与唤醒的时序

电池供电场景会用到 sleep。SX126x 支持冷启动和温启动两种睡眠，温启动保留配置，唤醒快。进入睡眠前要确保没有正在进行的收发，唤醒后要重新等 BUSY 并恢复必要配置。

/* 温启动睡眠，唤醒后配置基本保留 */ sx126x_set_sleep(dev, SX126X_SLEEP_CFG_WARM_START); /* 唤醒：拉低 NSS 一段时间再释放，然后等 BUSY */ sx126x_wakeup(dev); sx126x_wait_on_busy(dev);

唤醒时序如果不对，芯片可能不响应后续命令。常见做法是 NSS 拉低至少 20us 再拉高，然后等 BUSY 拉低。温启动虽然快，但某些寄存器在睡眠中会丢，唤醒后建议重新设置频点和包参数，别图省事。

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

5.1 BUSY 引脚一直高，初始化卡死

现象是程序停在wait_on_busy循环里，超时后返回错误。原因通常是复位时序不对，或者 BUSY 引脚接错、浮空。解决方法是先用示波器看 RESET 释放后 BUSY 有没有拉低的过程，确认引脚定义和硬件原理图一致；软件上给wait_on_busy加明确超时并打印错误码，别用死循环。

5.2 能发不能收，或收包长度异常

现象是发送侧 TX_DONE 正常，接收侧一直超时，或者收到的长度是 0 或 255。原因多半是收发两端包参数不一致，比如前导码长度、CRC 开关、IQ 极性不同；也可能是读缓冲区前没取 payload 长度。解决方法是把两端参数打印出来逐项比对，接收流程严格按「读 IRQ → 取长度 → 读缓冲 → 清标志」的顺序走。

5.3 发射功率上不去或模块发热

现象是设置 22dBm 但实测距离很短，或者模组发烫。原因是 regulator 模式选错（该用 DCDC 却用了 LDO），或者天线阻抗不匹配。解决方法是确认模组电源设计后选对set_reg_mode，用功率计或频谱看实际输出，天线端确认匹配网络。发热严重时先降功率排查，别硬扛。

5.4 中断里做 SPI 导致偶发死机

现象是跑一段时间后卡死或数据错乱。原因是在 DIO1 中断里直接做 SPI 读写，和主循环的 SPI 访问冲突。解决方法是在中断里只置标志，把 IRQ 处理和缓冲区读取放到主循环或任务里；如果必须在中 interrupt 里读，加互斥保护并确保 SPI 外设支持重入。

5.5 睡眠唤醒后收不到包

现象是低功耗唤醒后第一次接收必超时。原因是唤醒后没有重新等 BUSY 或没有恢复 RX 配置。解决方法是在唤醒流程里固定加wait_on_busy，并在唤醒后重新调用一次set_rx，别假设睡眠前的状态还在。

6. 二次开发：把驱动改成适合自己项目的形态

移植和改造时，我一般先做一件事：把驱动里所有「等待」都换成带超时和错误码的版本，然后把收发封装成项目自己的接口，不让业务代码直接碰寄存器。比如业务层只调lora_send_packet和lora_poll_recv，底层是轮询还是中断由驱动内部决定，这样换平台时业务代码不用动。

一个具体的改造点是参数配置表化。把频点、SF、BW、功率这些做成结构体，从配置文件或下行命令里读，而不是写死在初始化函数里。这样现场调试时改参数不用重新烧固件。验证方法也简单：准备两台设备，一台固定参数发递增序号，另一台收并打印 RSSI 和 SNR，跑够几百包看丢包率，再改参数对比。

有个教训我印象很深：早期图省事，把wait_on_busy写成while(busy);，结果一次硬件接触不良直接让设备假死，现场没法恢复。从那以后我每次移植这类射频驱动，都强制给每个等待点加超时和错误上报，宁可多写几行，也不留死循环。希望这份拆解能帮到你，少走几个我踩过的坑。

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