RIOT 中的 SODAQ SARA AFF 开发板：构建烧录、STDIO 与外设配置实战指南-育师

RIOT 中的 SODAQ SARA AFF 开发板：构建烧录、STDIO 与外设配置实战指南

【免费下载链接】RIOTRIOT - The friendly OS for IoT项目地址: https://gitcode.com/GitHub_Trending/riot/RIOT

SODAQ SARA AFF 是一块面向 NB-IoT / LTE-M 蜂窝物联网与 GPS 定位场景的 Arduino 兼容开发板。本文以 RIOT 仓库中 boards/sodaq-sara-aff/doc.md 为骨架，结合该板卡目录下的构建脚本、外设配置与板级初始化源码，系统讲解如何在 RIOT 中完成 SARA AFF 的应用构建、USB 烧录、串口调试，并深入剖析其 UART/ADC/I2C/USB、板载 NB-IoT 与 GPS 电源管理、Arduino 引脚映射等底层实现，帮助读者直接上手并用好这块板卡。

板卡概览：SODAQ SARA AFF 在 RIOT 中的定位

SODAQ SARA AFF（SARA AFF）是 SODAQ 面向蜂窝物联网应用推出的开发板，核心特性集中在板载的 NB-IoT 蜂窝模块（SODAQ SARA R410M 系列）与 GPS 接收器上，特别适合远程遥测、资产追踪、环境监测等低功耗联网场景。RIOT 将其作为官方支持板卡收录于 boards/ 目录下，文档定义于 boards/sodaq-sara-aff/doc.md，板级实现代码则分布在 boards/sodaq-sara-aff/ 的board.c、Makefile*与include/头文件中。

硬件平台与核心特性

从 boards/sodaq-sara-aff/Makefile.features 可以看到，该板卡采用的 MCU 型号为：

CPU_MODEL = samd21j18a

并继承了boards/common/sodaq/Makefile.features中定义的公共特性集合。汇总下来，SARA AFF 在 RIOT 中提供的外设能力包括：

特性	说明
`periph_adc`	模拟量采集，板载 11 路 ADC 通道
`periph_i2c`	I2C 总线，默认挂载于 SERCOM1
`periph_rtc`/`periph_rtt`	实时时钟与低功耗定时器
`periph_spi`	SPI 总线（注意与板载 LED 引脚复用）
`periph_timer`	硬件定时器
`periph_uart`	两路 UART（USB 串口与 Serial1）
`periph_usbdev`	USB 设备，用于烧录与 STDIO
`arduino_pins`	Arduino 兼容引脚映射
`highlevel_stdio`	高层级标准 I/O 支持

板级外设亮点包括：RGB 三色 LED（红/绿/蓝）、NB-IoT 模块（SARA R410M）的使能/复位/发射使能/模式切换控制引脚，以及 GPS 模块的使能与时间脉冲（TimePulse）引脚，这些引脚定义均可在 boards/sodaq-sara-aff/include/board.h 中查到。

构建与烧录：用`make BOARD=sodaq-sara-aff`一键完成

SODAQ SARA AFF 与其他 RIOT 板卡一样，使用统一的make构建流程。板卡文档给出的最小烧录示例如下：

make BOARD=sodaq-sara-aff -C examples/basic/hello-world flash

该命令以hello-world示例应用为例，指定BOARD=sodaq-sara-aff完成编译并烧录到板卡。-C examples/basic/hello-world表示进入该示例目录执行构建。

USB 烧录背后的机制：bossac 引导加载程序

SARA AFF 的烧录并不需要 JTAG/SWD 调试器，而是通过板载的 USB 引导加载程序完成。boards/sodaq-sara-aff/Makefile.include 揭示了这一机制：

# Add board common includes INCLUDES += -I$(RIOTBOARD)/common/sodaq/include # Include all definitions for flashing with bossa over USB include $(RIOTBOARD)/common/samdx1-arduino-bootloader/Makefile.include

该板卡复用了boards/common/samdx1-arduino-bootloader/提供的烧录基础设施，即通过 Atmel 的 bossac 工具经 USB 写入固件（与 Arduino Zero 系列的引导方式一致）。因此：

正常状态下，插入 USB 即可直接执行make flash完成烧录；
若应用崩溃或引导失败，USB 自动重烧可能失效，此时需要双击复位按钮让板卡进入引导加载程序模式，再重新执行烧录命令（文档@note中特别强调了这一点）。

烧录相关的构建细节

boards/sodaq-sara-aff/Makefile 还体现了模块化的依赖处理：当应用启用了 Arduino 引导加载程序模块（boards_common_samdx1-arduino-bootloader）时，会将对应目录加入构建路径：

ifneq (,$(filter boards_common_samdx1-arduino-bootloader,$(USEMODULE))) # Add the samdx1-arduino-bootloader directory to the build DIRS += $(RIOTBOARD)/common/samdx1-arduino-bootloader endif

通过 USB 访问 STDIO：UART 调试与`TERM_DELAY`

SODAQ SARA AFF 的 STDIO（标准输入输出）直接通过 USB 端口提供给开发者，无需额外串口转 USB 芯片接线。当应用启动后，RIOT 的printf、puts等标准输出会经 USB CDC（通过cfg_usbdev_default.h中定义的 USB 设备配置）转发到主机串口终端。

TERM_DELAY：串口终端打开前的延时控制

由于 USB 枚举需要时间，RIOT 提供TERM_DELAY环境变量，用于在打开串口终端前插入一段延时（单位为秒），确保终端工具能够稳定附着到 USB 串口设备上：

TERM_DELAY=3 make BOARD=sodaq-sara-aff -C examples/basic/hello-world term

文档明确指出该变量的默认值为 2 秒，在大多数情况下足够完成设备枚举。若在部分主机上遇到终端打开失败、输出丢失等问题，可适当调大该值（例如TERM_DELAY=5）重试。

板载 USB 外设配置

SODAQ 公共板级目录 boards/common/sodaq/include/cfg_usbdev_default.h 定义了 USB 数据引脚：

static const sam0_common_usb_config_t sam_usbdev_config[] = { { .dm = GPIO_PIN(PA, 24), .dp = GPIO_PIN(PA, 25), .d_mux = GPIO_MUX_G, .device = &USB->DEVICE, .gclk_src = SAM0_GCLK_MAIN, } };

即 USB D-/D+ 分别位于 PA24/PA25，由periph_usbdev驱动管理，为烧录与 STDIO 提供底层通道。

外设配置深度解析：UART、ADC、I2C

板级外设的具体引脚与参数全部集中在 boards/sodaq-sara-aff/include/periph_conf.h，它引用了boards/common/sodaq/include/下的默认时钟、RTC、RTT、SPI、Timer 与 USB 配置，并自行定义了 UART、ADC 与 I2C。

双 UART：USB 串口（D0/D1）与 Serial1

SARA AFF 配置了两路 UART（UART_NUMOF为 2）：

通道	SERCOM	RX	TX	说明
UART(0)	SERCOM5	PB30（D0）	PB31（D1）	与 USB 虚拟串口关联的主调试口
UART(1)	SERCOM0	PA5	PA6	对应 Arduino 的 Serial1

两路均采用GPIO_MUX_D复用、时钟源为SAM0_GCLK_MAIN，且当启用MODULE_PERIPH_UART_HW_FC硬件流控时，RTS/CTS 引脚被配置为GPIO_UNDEF（即默认不使能硬件流控）。对应中断映射为isr_sercom5/isr_sercom0。

ADC：从 A0 到电池电压检测

periph_conf.h中定义了 11 路 ADC 通道（ADC_NUMOF= 11），覆盖模拟输入与板载传感点：

ADC 索引	MUXPOS	板载丝印/用途
0–3	PB00–PB03	A0–A3
4–5	PA08–PA09	A4–A5
6–7	PA10–PA11	GROVE1/A6、GROVE2/A7
8	PB05	BAT_VOLT/A8（电池电压）
9	PA02	D2/DAC（数模转换）
10	PA03	AREF（参考电压）

ADC 默认参数为：分频ADC_PRESCALER_DIV512、负输入接 GND、增益GAIN_DIV2、参考电压INTVCC1。这意味着采样前无需额外配置即可直接通过 RIOT 的adc驱动读取模拟量。

I2C：单总线挂载于 SERCOM1

I2C 总线复用 SERCOM1 外设，SCL/SDA 位于 PA17/PA16，默认速率I2C_SPEED_NORMAL（100 kbit/s），引脚复用为GPIO_MUX_C。这为外接温湿度、气压等 I2C 传感器提供了标准挂载点。

板载电源管理：NB-IoT 与 GPS 默认关闭

SODAQ SARA AFF 面向蜂窝物联网场景，但 NB-IoT 模块与 GPS 接收器都属于高功耗外设。因此 boards/sodaq-sara-aff/board.c 中的board_init()在系统启动时默认将两者断电，以降低空闲功耗：

void board_init(void) { /* set NB-IoT device off by default */ NB_IOT_DISABLE; gpio_init(NB_IOT_ENABLE_PIN, GPIO_OUT); NB_IOT_TX_EN_OFF; gpio_init(NB_IOT_TX_EN_PIN, GPIO_OUT); NB_IOT_TOGGLE_ON; gpio_init(NB_IOT_TOGGLE_PIN, GPIO_OUT); /* set GPS off by default */ GPS_ENABLE_OFF; gpio_init(GPS_ENABLE_PIN, GPIO_OUT); }

结合 boards/sodaq-sara-aff/include/board.h 的引脚定义，板载外设控制引脚归纳如下：

功能	引脚	宏定义
NB-IoT 使能	PA27	`NB_IOT_ENABLE_PIN`/`NB_IOT_ENABLE`/`NB_IOT_DISABLE`
NB-IoT 复位	PB14	`NB_IOT_RESET_PIN`/`NB_IOT_RESET_ON`/`NB_IOT_RESET_OFF`
NB-IoT 发射使能	PB13	`NB_IOT_TX_EN_PIN`/`NB_IOT_TX_EN_ON`/`NB_IOT_TX_EN_OFF`
NB-IoT 模式切换	PB17	`NB_IOT_TOGGLE_PIN`/`NB_IOT_TOGGLE_ON`/`NB_IOT_TOGGLE_OFF`
GPS 使能	PA28	`GPS_ENABLE_PIN`/`GPS_ENABLE_ON`/`GPS_ENABLE_OFF`
GPS 时间脉冲	PA7（输入）	`GPS_TIMEPULSE_PIN`/`GPS_TIMEPULSE_MODE`

应用层需要启用蜂窝通信或 GPS 时，可直接调用gpio_set(NB_IOT_ENABLE_PIN)、gpio_set(GPS_ENABLE_PIN)等接口按需上电。

板载 RGB LED 与 SPI 的引脚复用

板卡提供 4 颗可控 LED（含一颗 RGB 三色灯），其引脚定义同样位于board.h：

LED	引脚	极性
LED0（内置）	PA21	高电平点亮
LED1（红）	PA12	低电平点亮
LED2（绿）	PB15	低电平点亮
LED3（蓝）	PA13	低电平点亮

注意一个关键约束：boards/sodaq-sara-aff/Makefile.dep 指出 LED0 引脚（PA21）同时被 SPI 时钟（SCK）复用：

ifneq (,$(filter periph_spi,$(USEMODULE))) # The LED pin is also used for SPI DISABLE_MODULE += periph_init_led0 endif

因此在启用periph_spi的应用中，系统会自动禁用periph_init_led0模块，避免 LED 初始化干扰 SPI 通信——这也是 boards/sodaq-sara-aff/include/arduino_iomap.h 中 D48（SCK）与 LED_BUILTIN 共用 PA21 的由来。

Arduino 兼容：D0–D54 完整引脚映射

SODAQ SARA AFF 提供arduino_pins特性，使 RIOT 的 Arduino API（如arduino_api包）可以直接运行。完整的引脚映射定义于 boards/sodaq-sara-aff/include/arduino_iomap.h，共 54 个数字引脚（ARDUINO_PIN_LAST = 54），分组如下：

D0–D1：SERCOM/UART（Serial），PB31/PB30；
D2–D15：数字 I/O；
D16–D18：RGB LED（PA12/PB15/PA13）；
D19–D25：板载外设输入（含 PA7 GPS TimePulse 等）；
D26–D30：板载外设输出（PA28 GPS 使能、PA27 NB-IoT 使能、PB14 复位、PB13 TX_EN、PB12）；
D31–D36：模拟输入 A0–A5；
D37–D40：其他模拟输入（含 BAT_VOLT）；
D41–D42：Serial1（PA6/PA5）；
D43–D44：I2C（SDA PA16 / SCL PA17）；
D45–D48：SPI（ICSP：MISO PA22、SS PA23、MOSI PA20、SCK PA21）；
D49–D50：USB D-/D+；
D51–D52：DAC（PA2）与 SARA_R4XX_TOGGLE（PB17）；
D53–D54：第二路 I2C（PA8/PA9）。

同时提供了模拟引脚别名ARDUINO_PIN_A0~ARDUINO_PIN_A5，以及 ADC 线路映射ARDUINO_A0~ARDUINO_A8，与periph_conf.h中的 ADC 通道一一对应。ARDUINO_LED被定义为 17，即 RGB 灯的绿色通道作为 Arduino 内建 LED。

SAUL GPIO 支持：LED 直接暴露给 RIOT 设备模型

SODAQ SARA AFF 还将板载 LED 注册到了 RIOT 的 SAUL（Sensor Actuator Ubiquitous Language）设备模型中，定义于 boards/sodaq-sara-aff/include/gpio_params.h：

SAUL 名称	引脚	标志
LED Builtin	LED0_PIN（PA21）	无
LED Red	LED1_PIN（PA12）	`SAUL_GPIO_INVERTED \\| SAUL_GPIO_INIT_CLEAR`
LED Green	LED2_PIN（PB15）	`SAUL_GPIO_INVERTED \\| SAUL_GPIO_INIT_CLEAR`
LED Blue	LED3_PIN（PA13）	`SAUL_GPIO_INVERTED \\| SAUL_GPIO_INIT_CLEAR`

红/绿/蓝三色 LED 均标记为反相输出（低电平点亮）并在初始化时清零，与board.h中的极性定义一致。启用saul_gpio模块后，即可通过 SAUL registry 以统一的设备接口开关这些 LED，方便上层应用与命令行工具交互。

Kconfig 集成与构建系统支持

在启用 Kconfig 配置系统的构建中，boards/sodaq-sara-aff/Kconfig 将板卡接入配置树：

config BOARD_SODAQ_SARA_AFF bool default y select BOARD_COMMON_SODAQ select CPU_MODEL_SAMD21J18A

BOARD_SODAQ_SARA_AFF会自动选中公共板级配置BOARD_COMMON_SODAQ与 CPU 型号CPU_MODEL_SAMD21J18A，并引入boards/common/sodaq/Kconfig中定义的公共选项。这意味着无论使用传统Makefile还是 Kconfig 配置流程，BOARD=sodaq-sara-aff都能得到一致的板级支持。

快速上手三步走

综合以上内容，从拿到一块 SODAQ SARA AFF 到跑通第一个 RIOT 应用，只需三步：

构建并烧录：连接 USB，执行make BOARD=sodaq-sara-aff -C examples/basic/hello-world flash；
打开串口终端：执行make BOARD=sodaq-sara-aff -C examples/basic/hello-world term，观察 STDIO 输出；若终端附着失败，用TERM_DELAY（默认 2 秒）增大延时；
异常恢复：若应用崩溃导致 USB 无法自动重烧，双击板载复位按钮进入引导加载程序模式后重试烧录。

在此基础上，开发者可参考 boards/sodaq-sara-aff/include/periph_conf.h 使用 UART/ADC/I2C 外设，参考 boards/sodaq-sara-aff/include/arduino_iomap.h 编写 Arduino 兼容代码，并通过 boards/sodaq-sara-aff/board.c 中暴露的 GPIO 宏按需控制 NB-IoT 与 GPS 的电源，进而构建完整的蜂窝物联网应用。

【免费下载链接】RIOTRIOT - The friendly OS for IoT项目地址: https://gitcode.com/GitHub_Trending/riot/RIOT

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

RIOT 中的 SODAQ SARA AFF 开发板：构建烧录、STDIO 与外设配置实战指南