RIOT 对 u-blox C030-U201 蜂窝/GNSS 开发板的支持:外设配置、引脚映射与烧录实战
RIOT 对 u-blox C030-U201 蜂窝/GNSS 开发板的支持:外设配置、引脚映射与烧录实战
本文以 RIOT 仓库中 boards/ublox-c030-u201 板卡支持包为主线,系统讲解 u-blox C030-U201 这块面向蜂窝物联网(LTE-M / NB-IoT)与 GNSS 定位场景的开发板在 RIOT 中的硬件抽象、外设资源分配、Arduino 兼容映射与烧录调试方法。读完本文,你将掌握该板卡的 UART/SPI/I2C/ADC/DMA 资源布局、Modem/GPS 控制引脚用法,以及如何基于 RIOT 构建并烧录一个针对此板卡的固件。
板卡概述与定位
u-blox C030-U201 是一块集成了 STM32 微控制器与 u-blox 蜂窝/GNSS 模块的开发板。仓库文档 doc.md 明确指出其目标场景是蜂窝物联网用例(如 LTE-M、NB-IoT),并同时具备 GNSS 特性,适用于需要位置感知(location-aware)的应用。
RIOT 社区将其归类为 boards 组下的标准板卡支持(@defgroup boards_ublox-c030-u201),板卡支持包由以下文件构成:
- Makefile:声明模块构建
- Makefile.features:声明 CPU 型号与提供的外设特性
- Makefile.dep:模块依赖与默认模块
- Makefile.include:编译参数与烧录器配置
- Kconfig:Kconfig 菜单配置
- include/board.h:板级引脚定义(LED、按键、Modem/GPS、SD 卡)
- include/periph_conf.h:外设时钟与 UART/SPI/I2C/ADC/DMA 配置
- include/arduino_iomap.h:MCU 引脚到 Arduino 引脚的映射
- include/gpio_params.h:SAUL 直接映射 GPIO 参数
MCU 型号与提供的外设特性
从 Makefile.features 可以确认,板卡搭载的 MCU 为 STM32F437VG(Cortex-M4,来自 STM32 家族):
CPU = stm32
CPU_MODEL = stm32f437vg
RIOT 为该板卡声明提供以下外设特性(按字母序排列):
FEATURES_PROVIDED += periph_adc
FEATURES_PROVIDED += periph_dma
FEATURES_PROVIDED += periph_i2c
FEATURES_PROVIDED += periph_rtc
FEATURES_PROVIDED += periph_spi
FEATURES_PROVIDED += periph_timer
FEATURES_PROVIDED += periph_uart
FEATURES_PROVIDED += periph_uart_hw_fc
其中 periph_uart_hw_fc(硬件流控)值得注意:在 Makefile.dep 中,只要应用使用了 periph_uart 模块,就会强制要求 periph_uart_hw_fc 特性:
ifneq (,$(filter periph_uart,$(USEMODULE)))
FEATURES_REQUIRED += periph_uart_hw_fc
endif
这是因为板上的 Modem UART 实际使用了 CTS/RTS 硬件流控,这一依赖保证了应用在使用 UART 时能够获得正确的硬件支持。
Kconfig 侧同样同步声明了这些能力:BOARD_UBLOX_C030_U201 选择 CPU_MODEL_STM32F437VG,并声明板卡同时提供 HSE 与 LSE,且 HSE 频率为 12 MHz。
时钟配置:HSE 12 MHz 与 LSE
periph_conf.h 顶部明确了时钟源:
/* This board provides an LSE */
#define CONFIG_BOARD_HAS_LSE 1
/* This board provides an HSE */
#define CONFIG_BOARD_HAS_HSE 1
/* The HSE provides a 12MHz clock */
#define CONFIG_CLOCK_HSE MHZ(12)
- HSE(外部高速晶振):12 MHz,作为系统主时钟的参考源;
- LSE(外部低速晶振):32.768 kHz 级别,为 RTC 提供低功耗走时基准。
对应地,Kconfig 中 CLOCK_HSE 默认值为 12000000。HSE/LSE 双双具备,意味着应用可以依赖 RTC 长期走时和稳定的系统时钟,这在蜂窝/GNSS 定位场景中(例如需要精确时间戳、定期上报)很实用。
UART 资源分配:一条总线连接四种角色
该板卡最具特色之处在于 UART 的分配,periph_conf.h 共配置了 4 个 UART,分别服务调试、蜂窝 Modem、GNSS 和 Arduino 接口:
| 索引 | 外设 | 引脚(TX / RX) | 复用功能 | 总线 | 用途 |
|---|---|---|---|---|---|
| UART_0 | USART1 | PA9 / PA10 | AF7 | APB2 | 调试串口(stdio) |
| UART_1 | USART2 | PD5 / PD6 | AF7 | APB1 | Modem UART(蜂窝模块,带 CTS/RTS 硬件流控) |
| UART_2 | USART6 | PC6 / PC7 | AF8 | APB2 | GPS UART |
| UART_3 | USART3 | PD8 / PD9 | AF7 | APB1 | Arduino 端口 UART |
Modem UART:唯一启用硬件流控的串口
UART_1 的配置中明确给出了 CTS/RTS 引脚:
{ /* Modem UART */
.dev = USART2,
.rx_pin = GPIO_PIN(PORT_D, 6),
.tx_pin = GPIO_PIN(PORT_D, 5),
.rx_af = GPIO_AF7,
.tx_af = GPIO_AF7,
.bus = APB1,
.irqn = USART2_IRQn,
#ifdef MODULE_PERIPH_UART_HW_FC
.cts_pin = GPIO_PIN(PORT_D, 3),
.rts_pin = GPIO_PIN(PORT_D, 4),
.cts_af = GPIO_AF7,
.rts_af = GPIO_AF7,
#endif
这也解释了为什么 Makefile.dep 会强制 periph_uart_hw_fc:与蜂窝 Modem 通信时,硬件流控可以防止数据溢出、保证 AT 指令交互的可靠性。
其余三个 UART 的 cts_pin/rts_pin 均定义为 GPIO_UNDEF,未使用硬件流控。每个 UART 条目都预留了 DMA 字段(dma、dma_chan),当前均配置为 DMA_STREAM_UNDEF / UINT8_MAX,即默认不走 DMA。
SPI、I2C 与 ADC:板载外设总线
SPI:单实例 SPI4,服务于 SD 卡
SPI 仅配置了一个实例(SPI4),挂载在 APB2 总线上,并启用了 DMA 收发:
static const spi_conf_t spi_config[] = {
{
.dev = SPI4,
.mosi_pin = GPIO_PIN(PORT_E, 6),
.miso_pin = GPIO_PIN(PORT_E, 5),
.sclk_pin = GPIO_PIN(PORT_E, 2),
.cs_pin = GPIO_PIN(PORT_E, 11),
.mosi_af = GPIO_AF5,
.miso_af = GPIO_AF5,
.sclk_af = GPIO_AF5,
.cs_af = GPIO_AF5,
.rccmask = RCC_APB2ENR_SPI4EN,
.apbbus = APB2,
#ifdef MODULE_PERIPH_DMA
.tx_dma = 0,
.tx_dma_chan = 4,
.rx_dma = 1,
.rx_dma_chan = 4,
#endif
},
};
该 SPI 总线直接服务于板载 SD 卡插槽。在 board.h 中可以看到与 periph_conf.h 完全一致的引脚参数:
#define SDCARD_SPI_PARAM_SPI SPI_DEV(0)
#define SDCARD_SPI_PARAM_CS GPIO_PIN(PORT_E, 11)
#define SDCARD_SPI_PARAM_CLK GPIO_PIN(PORT_E, 2)
#define SDCARD_SPI_PARAM_MOSI GPIO_PIN(PORT_E, 6)
#define SDCARD_SPI_PARAM_MISO GPIO_PIN(PORT_E, 5)
同时 dma_config[] 中分配了 DMA2 的 Stream1/Stream0 分别对应 SPI4_TX 与 SPI4_RX:
static const dma_conf_t dma_config[] = {
{ .stream = 9 }, /* DMA2 Stream 1 - SPI4_TX */
{ .stream = 8 }, /* DMA2 Stream 0 - SPI4_RX */
};
对于需要将传感器数据或定位结果落盘到 SD 卡的蜂窝数据记录仪场景,这套 SPI+DMA 组合可以直接复用 sdcard_spi 驱动模块。
I2C:两个实例,一主一从
I2C 配置了两个实例,均运行在 I2C_SPEED_NORMAL(100 kbit/s)标准速率:
| 索引 | 外设 | SCL / SDA | 复用功能 | 总线 | 用途 |
|---|---|---|---|---|---|
| I2C_0 | I2C1 | PB6 / PB7 | AF4 | APB1 | 板载扩展/传感器 |
| I2C_1 | I2C3 | PA8 / PC9 | AF4 | APB1 | 板载 si7034 温湿度传感器 |
注意 I2C_1(I2C3)正是板上 si7034 温度/湿度传感器(u-blox 自家环境传感器)挂接的总线。board.h 中给出了对应参数:
#define SI70XX_PARAM_I2C_DEV I2C_DEV(1) /**< I2C device used for the temp sensor */
#define SI70XX_PARAM_ADDR (0x70) /**< I2C address */
#define SI70XX_SAUL_INFO { .name = "si7034" } /**< Saul Alias for the temp sensor */
ADC:6 路 Arduino 模拟口 + 内部 VBAT 监测
ADC 配置了 7 个通道,其中 6 个对应 Arduino 接头的 A0–A5,另加 1 个内部 VBAT 通道。源码注释明确说明:并非按 STM32F437 的 ADC 通道顺序排列,而是按使用场景重新组织:
static const adc_conf_t adc_config[] = {
{GPIO_PIN(PORT_A, 3), 0, 3}, /* A0 */
{GPIO_PIN(PORT_C, 0), 0, 10}, /* A1 */
{GPIO_PIN(PORT_C, 3), 0, 4}, /* A2 */
{GPIO_PIN(PORT_A, 4), 0, 14}, /* A3 */
{GPIO_PIN(PORT_B, 7), 0, 7}, /* A4 */
{GPIO_PIN(PORT_B, 6), 0, 6}, /* A5 */
{GPIO_UNDEF, 0, 18}, /* VBAT */
};
#define VBAT_ADC ADC_LINE(6) /**< VBAT ADC line */
每个元组的格式为 {引脚, ADC 设备, 通道号}。第 7 项引脚为 GPIO_UNDEF,因为它对应 MCU 内部 VBAT 通道(通道 18),用于读取电池/供电电压——这对电池供电的蜂窝追踪器非常关键,应用可通过 ADC_LINE(6) 直接采样电源电压。
板载器件与 Modem/GPS 控制引脚
board.h 定义了板级器件:
LED 与用户按键
- LED0(红):PE3
- LED1(绿):PE4
- LED2(蓝):PE1
- 用户按键 BTN0:PC13,输入模式(
GPIO_IN)
LED 定义沿用了 STM32 通用 LED 宏(stm32_leds.h),因此应用可直接使用 LED0_TOGGLE、LED1_ON 等标准接口。
Modem/GPS 电源与复位控制
板卡将蜂窝 Modem 与 GNSS 模块的控制引脚集中定义如下:
#define UB_PWRON_PIN GPIO_PIN(PORT_E, 14) /**< Power On for the Modem/GPS */
#define UB_M_RST_PIN GPIO_PIN(PORT_B, 5) /**< Reset Pin for the Modem/GPS */
#define M_GPIO2_PIN GPIO_PIN(PORT_D, 1) /**< GPIO2 Pin of the Modem/GPS */
#define M_GPIO3_PIN GPIO_PIN(PORT_B, 4) /**< GPIO3 Pin of the Modem/GPS */
#define GPS_RST_PIN GPIO_PIN(PORT_C, 10) /**< Not connected */
UB_PWRON_PIN(PE14)用于给 Modem/GPS 供电上电;UB_M_RST_PIN(PB5)用于复位 Modem/GPS 模块;M_GPIO2_PIN(PD1)、M_GPIO3_PIN(PB4)为 Modem/GPS 的 GPIO 控制脚;GPS_RST_PIN(PC10)注释标明 Not connected(未连接)。
在蜂窝应用启动时,通常需要先拉高 UB_PWRON_PIN 给模块上电,再通过 UART_1 发送 AT 指令完成网络附着,这是一个典型的开机时序。由于仓库并未提供该板卡专属的 modem 驱动,这些引脚目前以 GPIO 方式暴露给应用层自行控制。
Arduino 兼容引脚映射
arduino_iomap.h 提供了完整的 MCU 引脚到 Arduino 引脚的映射,共 22 个数字引脚(0–21):
| Arduino 引脚 | MCU 引脚 | Arduino 引脚 | MCU 引脚 |
|---|---|---|---|
| D0 | PD9 | D11 | PE6 |
| D1 | PD8 | D12 | PE5 |
| D2 | PD11 | D13 | PE2 |
| D3 | PB14 | D14 | PB7 |
| D4 | PB1 | D15 | PB6 |
| D5 | PA5 | D16 (A0) | PA3 |
| D6 | PB8 | D17 (A1) | PC0 |
| D7 | PB15 | D18 (A2) | PC3 |
| D8 | PD15 | D19 (A3) | PA4 |
| D9 | PD12 | D20 (A4) | PB7 |
| D10 | PE11 | D21 (A5) | PB6 |
可以看到 D10–D13 与 SPI4(CS/CLK/MOSI/MISO)复用同一组引脚,D14/D15 与 I2C1(SDA/SCL)复用,这与 Arduino 生态中 SPI/I2C 引脚排布惯例一致。模拟引脚映射到 ADC 通道:
#define ARDUINO_A0 ADC_LINE(0)
#define ARDUINO_A1 ADC_LINE(1)
#define ARDUINO_A2 ADC_LINE(2)
#define ARDUINO_A3 ADC_LINE(3)
#define ARDUINO_A4 ADC_LINE(4)
#define ARDUINO_A5 ADC_LINE(5)
UART_3(USART3,PD8/PD9)作为 Arduino 端口 UART,对应 D1/D0,可直接驱动兼容 Arduino 的串行扩展板(如 GPS 模块、串口屏等)。
SAUL:板载资源自动注册
gpio_params.h 通过 SAUL(Sensor Actuator Ubiquitous Layer)框架将板载 GPIO 资源注册为可被上层统一访问的设备:
static const saul_gpio_params_t saul_gpio_params[] =
{
{ .name = "LD1(red)", .pin = LED0_PIN, .mode = GPIO_OUT,
.flags = SAUL_GPIO_INVERTED | SAUL_GPIO_INIT_CLEAR },
{ .name = "LD2(green)", .pin = LED1_PIN, .mode = GPIO_OUT,
.flags = SAUL_GPIO_INVERTED | SAUL_GPIO_INIT_CLEAR },
{ .name = "LD3(blue)", .pin = LED2_PIN, .mode = GPIO_OUT,
.flags = SAUL_GPIO_INVERTED | SAUL_GPIO_INIT_CLEAR },
{ .name = "Button(B1 User)", .pin = BTN0_PIN, .mode = BTN0_MODE },
};
三个 LED 均标记为 SAUL_GPIO_INVERTED(低电平点亮)并在初始化时清除输出(SAUL_GPIO_INIT_CLEAR)。启用 saul_default 模块后,这些 LED 与按键会自动出现在 SAUL 注册表中,配合 saul_reg 命令行命令即可查看。
Makefile.dep 中 saul_default 会附带启用 saul_gpio,而 si7034 温度传感器目前并未纳入 saul_default,源码中的 TODO 注释说明需等待 si70xx 驱动更新后再行加入。
构建、烧录与调试
烧录器配置:OpenOCD + ST-Link
Makefile.include 明确了烧录方式:
# this board uses openocd with st-link
PROGRAMMER ?= openocd
OPENOCD_DEBUG_ADAPTER ?= stlink
STLINK_VERSION ?= 2-1
# openocd programmer is supported
PROGRAMMERS_SUPPORTED += openocd
板卡默认使用 OpenOCD 配合 ST-Link(版本 2-1)进行调试与烧录,这也是 STM32 生态中最常见的方式。同时该板卡复用 boards/common/stm32 下的共享 STM32 配置片段:
INCLUDES += -I$(RIOTBOARD)/common/stm32/include
构建示例
假设应用目录位于 examples/ 下的某个蜂窝应用,在应用目录执行:
make BOARD=ublox-c030-u201 flash
BOARD=ublox-c030-u201指定目标板卡,构建系统会拉取 Makefile.features 中的 CPU 与特性声明、Makefile.include 中的编译与烧录参数;flash目标调用 OpenOCD 通过 ST-Link 写入固件;- 调试串口默认为 USART1(PA9/PA10),波特率等参数由应用或
stdio_uart配置决定。
如果需要使用 RIOT 的 saul_default 自动化资源注册,无需额外配置;若应用依赖 periph_uart,构建系统会自动按 Makefile.dep 强制启用 periph_uart_hw_fc。
典型应用组合建议
综合上述资源,可以勾勒出该板卡在 RIOT 中的典型用法:
- 蜂窝数据上报:UART_1(USART2)连接 Modem 发送 AT 指令完成 LTE-M/NB-IoT 附着与数据收发;
UB_PWRON_PIN负责模块上电时序;UB_M_RST_PIN用于异常复位。 - 定位追踪:UART_2(USART6)连接 GNSS 模块接收 NMEA 定位数据,与蜂窝链路叠加形成位置感知上报。
- 本地存储:SPI4 + DMA 驱动 SD 卡,可缓存定位点或传感器数据,断网补传。
- 环境感知:I2C3 上的 si7034 传感器(地址 0x70)提供温湿度数据;6 路 ADC 可扩展外部模拟传感器,内部 VBAT 通道(
ADC_LINE(6))监测供电电压。 - 人机交互与扩展:三色 LED 与用户按键通过 SAUL 统一管理;Arduino 兼容接头(USART3、I2C1、SPI4)可挂载标准 Arduino 扩展板。
小结
u-blox C030-U201 的 RIOT 板卡支持包虽然体量不大,但外设配置非常贴合其"蜂窝 + GNSS"的定位:4 路 UART 各司其职、Modem 串口启用硬件流控、SPI 预留 DMA、ADC 提供 VBAT 监测,配合 Arduino 兼容映射与 SAUL 自动注册,开发者可以快速搭建 LTE-M/NB-IoT 位置上报类应用。核心配置集中在 periph_conf.h、board.h 与 arduino_iomap.h 三份文件中,是阅读和理解该板卡支持实现的入口。