简介针对Semtech SX1268 LoRa射频芯片的SPI驱动源码包面向嵌入式软硬件工程师及物联网开发者解决基于STM32F10x平台远距离低功耗无线通信的移植与调试问题。压缩包共99个文件以42个C源文件、44个头文件为核心覆盖SX126xRadio、SX126xDriver等分层驱动代码并配备STM32F103ZET6的Keil工程、启动文件、固件库中文手册PDF、说明文档等整体约2.02MB目录整齐便于检索。驱动实现了芯片初始化、工作模式切换、频率/功率/扩频因子/编码率配置以及数据发送、接收缓冲区读取和中断回调等关键流程代码中包含寄存器操作与状态机管理注释较完整便于二次开发和教学参考。开发者可基于附带Demo快速验证硬件连接与通信参数并参考中文固件库手册理解STM32外设配置。已有1482人学习下载适合正在评估或量产LoRa方案的团队参考。1. SX1268驱动LoRa 项目里最容易在沉默中翻车的一段代码拆过的 LoRa 模块多了之后你会发现 SX1268 驱动是最容易被当成“能跑就行”去抄的一段代码。它看起来就是几行 SPI 读写加寄存器填值但它背后牵涉命令应答、BUSY 时序、DIO1 中断映射、TCXO 校准这些隐蔽环节任何一环没对齐板子就是不出信号。这份 sx126xdriver 源码包覆盖从 SPI 命令层到 radio 操作层的完整调用链特别适合正在做 STM32 LoRa 数传、想把 SX1268 从“买了模块”快速推进到“空中收发正常”的工程师。我拆过几份同类驱动能直接编译的不多能过频谱仪信号测试的更少所以这篇把关键机制和坑位都摊开讲。2. 驱动到底在驱动什么SPI 命令层、状态机与寄存器机制拿到驱动源码先别急着编译。SX1268 的驱动文件看着多其实逻辑上就三层最底下是物理层的 SPI 收发、GPIO 和延时中间是命令层每个函数对应 datasheet 上的一条命令比如 SetRfFrequency、SetPacketType最上层是操作层负责把多条命令拼成一个完整动作比如“发送一包数据”或者“进入连续接收”。大多数移植出问题都不是 SPI 坏了而是跨层调用时漏了某个前置命令。2.1 三块积木命令层、状态机与寄存器表SX1268 是 SPI 从机所有配置都要通过命令码完成。命令格式很固定NSS 拉低先发一字节命令码再发该命令的参数字节最后 NSS 拉高。对读写寄存器类的命令参数里就是寄存器地址加数据。这样一个 SPI 周期只允许一条命令不能把多条命令夹在同一个片选低电平里混着发。static int sx126x_cmd(uint8_t cmd, uint8_t *param, uint8_t size) { // 常见做法NSS拉低先发命令码再发参数字节 // 对读寄存器命令param里是“地址占位字节” hal_nss_low(); spi_write_byte(cmd); if (size) { spi_write_bytes(param, size); } hal_nss_high(); return 0; }这段代码是所有 SX1268 驱动的地基逻辑上没什么玄学NSS 拉低表示命令开始拉高表示命令结束中间时序必须完整。唯一容易踩的是参数长度比如 SetStandby 只有一个参数字节 0x01但 SetDioIrqParams 要带五组参数共 9 字节写错了芯片不会报错只是行为全都乱套。所以移植驱动时我一般先对着 datasheet 把所有命令的参数长度抄一遍贴到函数注释里方便后面对照。状态机这块是初用者最容易忽略的黑匣子。SX1268 内部有 IDLE、STDBY_RC、STDBY_XOSC、RX、TX 等状态改频率、改调制参数、写 FIFO 之前都要先用 SetStandby 回到 STDBY_RC。如果你的代码在连续收发几次后再配置参数偶尔失败不用怀疑芯片坏了大概率是上一次操作还没回 standby。2.2 参数配置映射频率、带宽、扩频因子对应哪几行驱动里最常被原样抄走的是一段 LoRa 默认配置代码它把频率、扩频因子、带宽、编码率、前导码都堆在几个函数调用里。很多人抄完不知道每一行在干什么出了问题只能整段回退所以我把关键参数和命令的对应关系列一下。配置项命令关键参数常见值工作频率SetRfFrequency (0x86)4 字节 RF 频点470000000 Hz调制方式SetPacketType (0x8A)1 字节包类型0x01 (LoRa)调制参数SetModulationParams (0x8B)SF、BW、CR、LDROSF7 / 125kHz / 4/5包参数SetPacketParams (0x8C)前导码、载荷长度、CRC8 字节前导码固定长度中断映射SetDioIrqParams (0x08)IRQ 掩码与 DIO1 掩码TX_DONE 映射到 DIO1这里必须提一个容易翻车的细节SetRfFrequency 的入参不是直接的 Hz 数而是一个由晶振频率换算出来的频点值公式是 Fstep 晶振频率 / 2^25。SX1268 的评估板和绝大多数国产模块用的都是 32MHz 晶振于是 Fstep 约等于 0.9537Hz配置 470MHz 时要先把 470000000 除以 0.9537 再取整。驱动里如果写死 26MHz 晶振的换算系数频谱仪上频率会偏出去好几兆。void lora_cfg_default(sx126x_radio_t *r, uint32_t freq_hz) { sx126x_set_standby(SX126X_STDBY_RC); // 改配置前必须回 standby sx126x_set_packet_type(SX126X_PACKET_TYPE_LORA); /* freq Fstep * RFfreq, Fstep 32MHz / 2^25 */ uint32_t rf_freq (uint32_t)(freq_hz / 0.9536743164 0.5); sx126x_set_rf_frequency(r, rf_freq); /* SF7、BW125、CR4/5、LDRO0 */ sx126x_set_modulation_params(r, SF7, BW125K, CR_4_5, 0); /* 前导码 8、固定长度、载荷 64、双字节 CRC、IQ 不翻转 */ sx126x_set_packet_params(r, 8, SX126X_HEADER_FIXED_LEN, 64, SX126X_CRC_2_BYTE, 0); }逻辑说明先 SetStandby 是因为频率和调制参数都不允许在 RX/TX 状态下修改这是 SX1268 比老款 SX1276 更“矫情”的地方。SetPacketType(0x01) 确保芯片处于 LoRa 模式而不是 FSK 模式如果上一手固件里跑过 FSK漏掉这行会导致后面所有参数都按 FSK 解释。RFfreq 后面的加 0.5 只是四舍五入避免频率偏几赫兹。2.3 移植到 STM32需要改的是四个挂点不是整个驱动上到实际项目里驱动自带的工程模板往往和你的板子对不上。不要试图重写整个驱动真正要动的只有四个挂点SPI 单字节收发、NSS 片选控制、DIO1 外部中断回调、毫秒延时函数。这四个点改完其余文件基本不用动。/* STM32 HAL 版移植示例 */ uint8_t hal_spi_xfer(uint8_t data) { uint8_t rx; // 注意SX1268 要求 SPI 模式 0即 CPOL0、CPHA0 HAL_SPI_TransmitReceive(hspi1, data, rx, 1, 10); return rx; } void sx1268_gpio_init(void) { // NSS、RESET、BUSY 配成推挽输出DIO1 配成输入 // DIO1 对应的 EXTI 线配置为上升沿中断 HAL_NVIC_SetPriority(EXTI9_5_IRQn, 2, 0); HAL_NVIC_EnableIRQ(EXTI9_5_IRQn); }逻辑说明SPI 模式 0 是硬性要求模式和 SX1276 一样。很多驱动为了省事不检查 BUSY 引脚直接用固定延时代替这在低速操作时没问题但连续收发时容易丢命令。我一般会把 BUSY 查询保留下来宁可多写几行也不能让命令撞车。参数说明hspi1 换成你工程里实际的 SPI 句柄DIO1 的 EXTI 配置要看芯片引脚连到哪条 EXTI 线上代码里的 EXTI9_5_IRQn 只是示例。移植完成后先用一个最简单的读寄存器操作验证通路调用驱动里的读寄存器函数读 0x0740 的同步字寄存器能读回默认值 0x1424说明 SPI 通路和驱动层都通了再进行收发调试。这一步能省掉后面一半的排查时间。3. 把包收回来发送、接收与中断链路的完整调用顺序驱动移植通过后下一步就是让数据真的从天线飞出去再收回来。SX1268 的收发链路比寄存器配置更依赖调用顺序因为中断映射、FIFO 操作和超时参数是联动的。很多人在这里翻车不是不懂 SPI而是没搞清“先等 BUSY 拉低再发下一条命令”的节奏。3.1 发送一条 LoRa 包从 SetTx 到 TX_DONE 的路径发送一包数据的标准顺序是先回 standby然后写 FIFO再配置 DIO1 中断映射最后调 SetTx 启动发射。代码看起来不长但每一步都有隐含前提。int radio_tx_packet(uint8_t *data, uint8_t len) { sx126x_set_standby(SX126X_STDBY_RC); sx126x_write_buffer(data, len); // 命令 0x0E从 FIFO 偏移 0x00 写起 sx126x_set_pa_config(0x04, 0x07, 0x01, 0x01); sx126x_set_tx_params(22, SX126X_RAMP_TIME_200U); sx126x_set_dio_irq_params(SX126X_IRQ_TX_DONE, SX126X_IRQ_TX_DONE, 0, 0, 0); sx126x_set_tx(0xFFFFFF); // 超时单位 15.625us最大即不超时 while (!dio1_flag); // DIO1 在 EXTI 回调里置位 uint16_t irq sx126x_get_irq_status(); sx126x_clear_irq_status(); dio1_flag 0; return (irq SX126X_IRQ_TX_DONE) ? 0 : -1; }逻辑说明WriteBuffer 命令必须先发偏移字节再发数据这里的偏移就是 FIFO 起始地址通常固定 0x00。SetPaConfig 和 SetTxParams 这两行是很多人看不懂的前者配置 PA 的通断占空比和高功率模式后者设置发射功率与升压时间。功率 22 是 dBm 数值但前提是 PA 配置和模块匹配网络一致否则虚标。等待 TX_DONE 时不能用死循环项目里我一般会加超时计数比如设一个 500ms 的上限超过就报错退出避免模块异常时把整个系统卡死。如果发送后 DIO1 一直没有拉高先别查中断用 GetIrqStatus 命令主动读一次中断状态看有没有 TX_DONE 标志。如果读到的中断是别的位说明芯片根本没进入发送状态问题在状态机前置条件上而不是中断配置。3.2 接收一条 LoRa 包连续 RX 与 DIO1 中断接收比发送简单但容易混淆的是两种接收模式单次接收和连续接收。单次接收在收到一包或超时后芯片自动回到 standby连续接收则一直停在 RX 状态直到你手动调 SetStandby 才退出。低功耗场景建议用前者主循环轮询用后者更省事。void radio_start_rx(void) { sx126x_set_standby(SX126X_STDBY_RC); sx126x_set_dio_irq_params(SX126X_IRQ_RX_DONE | SX126X_IRQ_CRC_ERROR, SX126X_IRQ_RX_DONE | SX126X_IRQ_CRC_ERROR, 0, 0, 0); sx126x_set_rx(0xFFFFFF); // 连续接收不超时 }收到 DIO1 中断后在主循环里读中断状态、清标志、再读 FIFO这个流程和发送是对称的。void radio_poll(void) { if (!dio1_flag) { return; } dio1_flag 0; uint16_t irq sx126x_get_irq_status(); if (irq SX126X_IRQ_RX_DONE) { uint8_t buf[256]; uint8_t len 0; sx126x_read_buffer(buf, len); sx126x_clear_irq_status(); // 到这里 len 是有效数据长度buf 里是完整载荷 handle_rx_packet(buf, len); } else if (irq SX126X_IRQ_CRC_ERROR) { sx126x_clear_irq_status(); // CRC 出错也要清中断否则一直卡 } }逻辑说明SX1268 在 CRC 错误时也会触发中断如果不主动 ClearIrqStatus中断标志会一直挂在状态寄存器里导致后续包全部无法进入。读 FIFO 时驱动内部会用 ReadBuffer 命令先读回长度字节再读载荷这与你往 FIFO 写的字节顺序一致。参数说明buf 大小至少 256 字节SX1268 FIFO 总共就 256 字节这是硬件上限别指望单包超过这个长度。关于 CAD 唤醒它用于低功耗接收前先探测信道是否有 LoRa 前导码命中后再切到 RX。连续接收也能用但电流会一直保持在 RX 状态电池供电时吃不消。驱动里一般会有 SetCad 命令但先用连续 RX 调通链路再去做 CAD 省电更稳妥。3.3 用逻辑分析仪确认 SPI 时序和 DIO1 中断收发链路调不通时别急着猜射频问题先用逻辑分析仪抓四根信号SCK、NSS、DIO1、MISO。重点看三件事一是 NSS 低电平期间 SCK 有没有多余脉冲二是 MISO 上的回读字节是否出现在正确位置三是 DIO1 在发送完成后是不是稳定拉高。SX1268 的读命令有个特点发完命令和地址后MISO 上的有效数据会在随后的第三个 SCK 周期开始返回来驱动里如果用 HAL 的 TransmitReceive 同步收发逻辑分析仪上能看到一次完整的 8 位交互。如果 MISO 一直为高说明 GPIO 配置不对或 SPI 速率过快如果数据错位优先查 SPI 模式的 CPOL/CPHA。BUSY 信号的检查也值得专门抓一下。SX1268 在执行某些命令时会拉高 BUSY 引脚常见表现是连续调用多条命令时第二条命令的返回数据全 FF。这不是芯片坏了而是上一条命令还没执行完。我一般会在每条命令前加一个 busy_poll 函数最多等 10ms超时返回错误比固定延时 100us 靠谱得多。4. SX1268 驱动调试避坑五个常见翻车现象与修法下面这几条是我和同行调 SX1268 时反复踩过的血泪经验。每条都是实际遇到过的现象原因和修法都按排掉后的结论写照着顺序查能少烧不少头发。4.1 现象频谱仪上频率偏了 3MHz或者完全没信号原因八个里面有七个是晶振频率和 Fstep 换算系数没对上。SX1268 驱动里 SetRfFrequency 的系数如果还是按 26MHz 晶振算的那配置 470MHz 时实际输出频率会偏出去。还有一个隐蔽原因是 TCXO 没配好DIO3 没有配置成 TCXO 供电脚芯片内部 RC 震荡替代了晶振频率就飘了。解决先确认板子上晶振型号再看驱动里 32MHz 换算系数是否匹配。然后初始化里调用 SetDIO3AsTCXOCtrl把 DIO3 电压设成模块实际需要的值同时把 TCXO 启动延时设到 10ms 以上给晶振留够稳定时间。修完再用频谱仪点频验证频率落在目标频点附近才算过。4.2 现象DIO1 中断永远不来代码卡死在等待发送完成原因SX1268 的 DIO1 引脚在芯片内部可以映射到任意中断事件默认映射不包含 TX_DONE 或 RX_DONE。你调用了 SetTx 却没用 SetDioIrqParams 把对应事件映射到 DIO1GPIO 口当然永远不会拉高。这是从 SX1276 迁移过来最容易踩的坑因为 SX127x 的 DIO0 映射规则完全不同。解决发送前调用 SetDioIrqParams把 IRQ 掩码和 DIO1 掩码都设成你要的事件比如 TX_DONE。设置完用读寄存器的方式确认映射寄存器 0x0C 和 0x0D 的值已经写入。如果还不触发就用逻辑分析仪看 DIO1 引脚是否有毛刺确认后检查 EXTI 的中断触发边沿和 NVIC 优先级配置。4.3 现象能接收但不能发送或者发送距离缩水到几十米原因两个点。第一是 PA 配置不对SX1268 的高功率路径需要 SetPaConfig 设置 duty cycle、HP max 和 LUT没设置就只能以低功率模式工作发射功率上不去。第二是同步字或 IQ 翻转配置不一致接收端和发送端若一个默认 0x1424 一个被改过丢包率会高得离谱。解决发送初始化里按模块参考设计配 PA常见参数是 paDutyCycle0x04、paHpMax0x07、paLut0x01、deviceSel0x01。同步字用 WriteRegister 写寄存器 0x0740收发两端都写成 0x1424。IQ 翻转保持一致绝大多数模块默认不翻转不要乱开 InvertIQ 开关。4.4 现象同一套代码从 SX1276 换到 SX1268 后丢包严重原因两个芯片的 FIFO 操作差异很大。SX127x 的 FIFO 映射到寄存器空间写前要设地址SX1268 用独立的 WriteBuffer/ReadBuffer 命令FIFO 偏移从 0x00 开始。老的写发送缓冲函数没换数据根本没写进 SX1268 的 FIFO或者写错位置了。解决发送和接收都改成新版驱动里的 WriteBuffer 和 ReadBuffer 函数不要再操作寄存器 0x00 地址那种老办法。改完后用回环模式验证发送前把接收模式打开让同块板子自己收自己发的包通了再上两块板联调。4.5 现象SPI 偶发超时、读状态寄存器读出来全是 0原因SPI 时钟太高或者 NSS 释放后到下一次操作的间隔太短。SX1268 对 SPI 时序有上限要求超过约 16MHz 后的读回数据会出现位错误。另一个常见原因是 BUSY 没等命令还在执行你就发了下一条芯片直接忽略新命令。解决把 SPI 预分频调到 8MHz 或更低SPI Mode 0。每次命令前加 busy_poll 等待超时设 10ms。如果项目用的 RTOS注意在 SPI 传输期间不要被高优先级任务打断否则波形会被切开推荐用互斥锁保护整条 SPI 总线的访问。5. 上板验证回环自检流程与 LoRa 参数速查驱动不是“编译过就完事”上板后先用回环自检把软硬件边界划清再去做空中距离测试。回环自检的逻辑很简单同块板子上同时跑发送和接收自己发自己收能收到就说明 SPI、FIFO、调制、中断全链路是通的。5.1 先做回环自检再上距离void radio_loopback_test(void) { sx126x_set_standby(SX126X_STDBY_RC); sx126x_calibrate_image(0x75, 0x81); // 430~510MHz 频段校准 sx126x_set_packet_type(SX126X_PACKET_TYPE_LORA); sx126x_set_rf_frequency(470000000); /* 先开接收再发一包看能否收到自己的数据 */ radio_start_rx(); radio_tx_packet((uint8_t*)ping, 4); }逻辑说明CalibrateImage 是按频段校准镜像抑制SX1268 每次上电运行一次即可参数 0x75 和 0x81 覆盖 430510MHz正好是国产模块常用的频段。先开接收再发送避免发送期间 chip 还停在 TX 状态导致丢包。回环通过后再把发送和接收放到两块板子上做空中验证判断标准是 RSSI 稳定且 CRC 错误计数不增长。5.2 调距离时用的参数速查表用途命令参数要点备注设置频率0x864 字节 RFfreq要先回 STDBY_RC配置 LoRa 调制0x8BSF、BW、CR、LDROSF 越大灵敏度越高配置包格式0x8C前导码、CRC、IQ收发两端必须一致映射中断0x08IRQ 掩码、DIO1 掩码DIO1 没有默认映射发送/接收0x83 / 0x823 字节超时0xFFFFFF 表示不超时频段校准0x980x75、0x81换频段必须重新校准调距离时优先拉大扩频因子SF 从 7 提到 9、10接收灵敏度提升明显但数据速率也会降下来。带宽同理125kHz 比 500kHz 更抗噪但速率低。这些参数在驱动里就是 SetModulationParams 的几个字节改了之后重新跑一遍回环确认两端配置一致再出门测距离。第一次用 SX1268 做 470MHz 模块时我调好了频率频谱仪上也能看到点频但实际对传距离始终只有几十米后来才发现是忘了做 CalibrateImage接收灵敏度掉了好几个 dB。从那以后我每次换频段都强制走一遍 CalibrateImage 加频谱仪点频确认再进联调这套习惯帮我避开了后来好几次隐蔽问题。希望帮到你。本文还有配套的精品资源点击获取