Zephyr 板级支持实战：基于 Apollo3 Blue 与 SX1262 的 RAK11720 WisBlock LoRa/BLE 模块
【免费下载链接】zephyrPrimary Git Repository for the Zephyr Project. Zephyr is a new generation, scalable, optimized, secure RTOS for multiple hardware architectures.项目地址: https://gitcode.com/GitHub_Trending/ze/zephyr
本篇技术指南以 Zephyr 仓库中 RAK11720 板级文档 为主体，结合仓库内的设备树、Kconfig 与构建脚本，系统讲解 RAK11720 WisBlock Core 模块的硬件特性、Zephyr 板级支持实现，以及从零构建、烧录hello_world并观察串口输出的完整流程。读完本文，你将掌握该板卡的资源布局（UART/SPI/I2C/GPIO/LoRa/BLE）、分区规划与 J-Link 烧录要点，能够在自己的 WisBlock 项目上快速落地 Zephyr 应用。
模块概览：RAK11720 是什么
RAK11720 是 RAK WisBlock 生态中的一款 WisBlock Core 模块（型号名rak11720，厂商rakwireless），其核心组成是：
- Ambiq Apollo3 Blue SoC（AMA3B1KK-KBR-B0）：超低功耗 MCU，集成蓝牙 5 低功耗控制器；
- Semtech SX1262 LoRa 收发器：低功耗、远距离 LoRa 无线通信。
根据 板级文档 的描述，AMA3B1KK-KBR-B0 内置的 BLE 收发器增强了模块的通信能力，而 RAK11720 stamp 模块与 RAK3172 模块采用相同的外形与封装（footprint），这意味着开发者可以基于既有 RAK3172 设计，直接升级到 RAK11720 以获得 BLE 能力，无需重新设计 PCB——这是该模块最具工程价值的特性之一。
在使用方式上，官方推荐通过WisBlock 模块化系统快速上手：以 WisBlock Base 板RAK19007作为供电与编程/调试载体，将RAK11722（内置 RAK11720 的 WisBlock Core 模块）插接到 Base 板上即可开始开发。
硬件规格
以下硬件要点完整摘录并整理自 板级文档：
- Apollo3 Blue SoC，最高96 MHz工作频率
- ARM Cortex-M4F内核
- 每核16 KB2 路组相联/直接映射 Cache
- 最多1 MBFlash（代码/数据）
- 最多384 KB低漏电/低功耗 RAM（代码/数据）
- 集成Bluetooth 5 低功耗控制器
- Semtech SX1262低功耗、高覆盖 LoRa 收发器
- 用于 LoRa 天线与 BLE 天线的iPEX 连接器
- RAK19007 WisBlock Base 板上的2 颗用户 LED
- 供电方式：Micro USB、3.7V 可充电电池、或 5V 太阳能板端口
这些参数与仓库中的板级定义完全对应：rak11720.yaml 声明arch: arm、ram: 384（KB）、flash: 976（KB），并将 SoC 指向apollo3_blue。
板级支持的文件构成
在 Zephyr 仓库中，RAK11720 的完整板级支持位于 boards/rakwireless/rak11720/，由以下文件协作完成：
| 文件 | 作用 |
|---|---|
| rak11720.yaml | 板卡元数据：架构、RAM/Flash 容量、工具链、受支持外设 |
| board.yml | 板卡注册信息（vendor、SoC 名称） |
| Kconfig.rak11720 | 板级 Kconfig 入口，选择SOC_APOLLO3_BLUE |
| Kconfig.defconfig | 板级默认 Kconfig（系统时钟等） |
| rak11720_defconfig | 默认使能串口控制台 |
| rak11720.dts | 设备树：外设实例、引脚分配、Flash 分区 |
| rak11720_apollo3-pinctrl.dtsi | 引脚复用（pinctrl）定义 |
| board.cmake | 烧录器（runner）配置 |
Kconfig 与默认配置
Kconfig.rak11720 定义板卡符号BOARD_RAK11720并select SOC_APOLLO3_BLUE，将板卡与 Ambiq Apollo3 Blue SoC 绑定。
Kconfig.defconfig 中给出了一个值得注意的时钟细节：
config SYS_CLOCK_HW_CYCLES_PER_SEC default 32768 if AMBIQ_STIMER_TIMER即当使用 Ambiq 的 STIMER 作为系统时钟源时，硬件时钟周期频率为32768 Hz（32.768 kHz 低速晶振），这与设备树中&stimer0 { clk-source = <3>; };的配置相呼应，也体现了该平台面向低功耗场景的典型时钟设计。
rak11720_defconfig 默认开启：
CONFIG_CONSOLE=y CONFIG_UART_CONSOLE=y CONFIG_SERIAL=y CONFIG_UART_INTERRUPT_DRIVEN=y这套组合保证了开箱即可通过 UART0 输出控制台信息（hello_world的打印依赖于此）。
支持的 Zephyr 功能特性
rak11720.yaml 中supported字段声明了该板卡支持的外设子系统：
- uart（串口）
- watchdog（看门狗）
- counter（计数器）
- gpio（通用 IO）
- spi（串行外设接口）
- i2c（I2C 总线）
- lora（LoRa 无线）
同时testing.ignore_tags包含net，表明该板卡的测试矩阵不会运行网络（net）类测试。在工具链方面支持zephyr与gnuarmemb两种工具链。
从源码结构看，这些特性在设备树中均有对应实现（详见下一节），例如 LoRa 对应&iom1下挂载的semtech,sx1262节点，counter 对应多个被使能的 timer 实例。
设备树深入：外设资源是如何布局的
rak11720.dts 是理解该板卡资源布局的关键。它通过#include <ambiq/ambiq_apollo3_blue.dtsi>引入 SoC 级设备树，并覆盖了以下内容：
chosen 与别名
chosen节点将 Zephyr 子系统绑定到具体外设：
- 控制台与 shell、mcumgr、uart-pipe 均指向uart0
- 内存与 Flash：
zephyr,itcm = &tcm、zephyr,sram = &sram0、zephyr,flash = &flash0 - 蓝牙控制器：
zephyr,bt-hci = &bt_hci_apollo（指向 Apollo3 Blue 集成 BLE 控制器） - OTA 代码分区：
zephyr,code-partition = &slot0_partition
aliases则提供了watchdog0、led0/led1、lora0、mcuboot-led0等通用别名，方便应用层与 Bootloader 引用。
用户 LED
两颗 LED 定义在gpio-leds节点中，均位于gpio32_63控制器上且为高电平有效：
| 别名 | GPIO | 标签 |
|---|---|---|
led0（蓝） | gpio32_63 pin 13 | "Blue LED" |
led1（绿） | gpio32_63 pin 12 | "Green LED" |
这正好对应文档中提到的 RAK19007 Base 板上的 2 颗用户 LED。
通信外设：UART、SPI、I2C
- UART0：
current-speed = <115200>，使用uart0_defaultpinctrl。其引脚在 rak11720_apollo3-pinctrl.dtsi 中定义为TX=P39、RX=P40。 - SPI：
iom0提供spi0（CS 为 gpio0_31 pin1），iom1提供spi1（CS 为 gpio0_31 pin11），初始时钟频率均为 1 MHz。 - I2C：
iom2上挂载i2c2，标准速率（100 kHz）。pinctrl 文件中同时定义了 i2c0~i2c5、spi0~spi5 等更完整的引脚组，供扩展使用（例如连接 WisBlock 传感器板）。
LoRa 射频：Semtech SX1262
LoRa 收发器作为spi1总线上的子节点出现（lora@0，compatiblesemtech,sx1262），关键配置包括：
reset-gpios：gpio0_31 pin 17（低电平有效）busy-gpios：gpio0_31 pin 16dio1-gpios：gpio0_31 pin 15antenna-enable-gpios：gpio0_31 pin 18（低电平有效）dio2-tx-enable：启用 DIO2 作为 TX 使能dio3-tcxo-voltage = <SX126X_DIO3_TCXO_3V3>：DIO3 输出 3.3V 为外部 TCXO 供电tcxo-power-startup-delay-ms = <5>：TCXO 上电稳定延时 5 msspi-max-frequency = <DT_FREQ_M(1)>：SPI 时钟 1 MHz
以上参数对实际 LoRa 通信的射频指标与稳定性有直接影响——TCXO 供电电压与启动延时若配置不当，可能导致晶振起振异常。Zephyr 的 LoRa 驱动会据此完成 SX1262 的初始化时序。
定时器与计数器
设备树使能了timer0、timer1、timer2、timer4~timer7共 7 个定时器实例作为 counter 使用（counter0~counter6），为应用提供丰富的定时/计数资源。
Flash 分区布局
rak11720.dts 在&flash0上定义了完整的可引导分区（1 MB Flash 的划分）：
| 分区 | 地址 | 大小 | 用途 |
|---|---|---|---|
internal_bootloader | 0x00000000 | 0xc000 (48 KB) | 内部引导程序 |
mcuboot | 0x0000c000 | 0xc000 (48 KB) | MCUboot 引导加载器 |
slot0（image-0） | 0x00018000 | 0x72000 (456 KB) | 主应用镜像 |
slot1（image-1） | 0x0008a000 | 0x72000 (456 KB) | 升级镜像 |
storage | 0x000fc000 | 0x4000 (16 KB) | 设置/存储区（位于 Flash 末尾） |
这一布局支持MCUboot 双槽位 A/B 升级，为基于 RAK11720 的 LPWAN 设备远程固件升级（FOTA）预留了标准化的存储结构。其中storage_partition的注释明确说明其在 1024 KB Flash 末尾保留了 16 KB。
蓝牙与引脚复用
&bleif节点被使能，对应 Apollo3 Blue 的 BLE 接口控制器，其引脚（SCK=P30、MISO=P31、MOSI=P32、CSN=P33、STATUS=P35、IRQ=P41）在 pinctrl 的bleif_default中定义——这是板载 BLE 射频栈与 SoC 之间的硬件通道。
构建与烧录
环境准备
烧录依赖SEGGER J-Link 软件（J-Link OB 调试器）以及 Python 的pylink模块，二者需提前安装在宿主机上。
board.cmake 中已配置好 J-Link runner 参数：
board_runner_args(jlink "--device=AMA3B1KK-KBR" "--iface=swd" "--speed=1000")即使用 J-Link 通过SWD 接口、以1000 kHz速度连接目标芯片AMA3B1KK-KBR，并引入boards/common/jlink.board.cmake。板级文档同时说明：该板应连接 Segger Embedded Debugger（J-Link OB），它提供了对 Apollo3 Blue 芯片的调试接口。
编译并烧录 hello_world
文档以samples/hello_world为例演示完整流程。首先用 USB 线将设备（J-Link OB 的 USB 口）连接至宿主机，然后执行：
west build -b rak11720 samples/hello_world west flash其中-b rak11720指定目标板卡，west flash会调用上文中配置好的 J-Link runner 完成烧录。关于该示例应用的源码，可参考 samples/hello_world/src/main.c。
串口输出验证
烧录完成后，使用 minicom、putty 等串口终端工具连接对应串口，参数为：
- 波特率：115200
- 数据位：8
- 校验：None
- 停止位：1
复位板卡后，串口应输出：
Hello World! rak11720/apollo3_blue输出中的rak11720/apollo3_blue是板卡标识与 SoC 型号的组合，既验证了应用已正常运行，也确认了 UART 控制台链路（UART0 的 P39/P40 引脚、115200 波特率配置）工作正常。
调试与注意事项小结
- 烧录接口：通过 J-Link OB 的 USB 口连接宿主机，runner 使用 SWD 协议，目标设备号
AMA3B1KK-KBR。 - 控制台：默认绑定 UART0（115200-8-N-1），并在
rak11720_defconfig中开启串口控制台，应用无需额外配置即可输出日志。 - 升级能力：Flash 已按 MCUboot 双槽位布局划分，
zephyr,code-partition指向slot0_partition，为后续引入安全固件升级留好接口。 - 低功耗设计：系统时钟在 STIMER 模式下为 32.768 kHz，配合 Apollo3 Blue 的 384 KB 低功耗 RAM 与 96 MHz Cortex-M4F，适合电池供电的远距离传感与 LPWAN 场景。
如需深入了解该板卡的完整定义，可继续阅读仓库中的 rak11720.dts、rak11720_apollo3-pinctrl.dtsi 以及 rak11720.yaml，它们共同构成了 RAK11720 在 Zephyr 中的完整板级支撑。
【免费下载链接】zephyrPrimary Git Repository for the Zephyr Project. Zephyr is a new generation, scalable, optimized, secure RTOS for multiple hardware architectures.项目地址: https://gitcode.com/GitHub_Trending/ze/zephyr
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
