# microros

**Repository Path**: lvbs/microros

## Basic Information

- **Project Name**: microros
- **Description**: micro‑ros RT‑Thread工程
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Micro-ROS on RT-Thread（STM32 机器人节点）

本工程是基于 **RT-Thread** 实时操作系统的 **Micro-ROS**（ROS 2 的嵌入式子集）演示/开发项目，
目标是在 STM32 单片机上运行一个 ROS 2 节点，通过 micro-ROS Agent 与上位机 ROS 2 通信，
把板载传感器数据（电压、IMU、里程计、环境光/接近、温湿度等）实时发布到 ROS 2 话题。

## 1. 项目概览

| 项目 | 说明 |
| --- | --- |
| 工程目录 | `d:/RT-ThreadStudio/workspace/microros` |
| 实时系统 | RT-Thread（版本 4.1.1，见 `applications/main.c` 中的 board 信息） |
| 硬件平台 | STM32F407ZG（差速两轮底盘，编码器 + 六轴 IMU） |
| Micro-ROS 版本 | **humble-gcc-10**（包目录 `packages/micro_ros-humble-gcc-10`） |
| 通信方式 | 支持 **串口(Serial)** 与 **UDP over WiFi** 两种传输，由宏切换 |
| WiFi 模组 | RW007（`packages/rw007-v2.1.0`） |

## 2. 目录结构

```
microros/
├── applications/
│   └── main.c                # 应用主逻辑：WiFi 连接、Micro-ROS 节点、传感器采集与发布
├── packages/
│   ├── micro_ros-humble-gcc-10/   # Micro-ROS 静态库 + 头文件（humble 版，gcc-10 编译）
│   ├── rw007-v2.1.0/         # WiFi 驱动包
│   ├── icm20608-v1.0.0/      # 六轴 IMU 驱动
│   ├── ap3216c-v2.0.0/       # 环境光/接近传感器驱动
│   └── pkgs.json             # 已启用软件包清单
├── rt-thread/                # RT-Thread 内核与组件源码
├── libraries/                # STM32 HAL/外设库
├── drivers/                  # 板级驱动（串口、ADC、I2C、TIM 等）
├── rtconfig.h                # RT-Thread 全局配置（含 MICRO_ROS_USE_SERIAL/UDP 等开关）
├── Kconfig / SConscript / SConstruct / makefile.targets  # 构建配置
└── README.md                 # 本文档
```

## 3. 功能特性

`applications/main.c` 实现了一个完整的机器人节点 `stm32_robot_node`，开机自动启动（
`INIT_APP_EXPORT(micro_ros_auto_start)`），主要能力如下：

### 3.1 传输通道（二选一）
- `MICRO_ROS_USE_SERIAL`：通过串口 `set_microros_transports()` 连接 Agent。
- `MICRO_ROS_USE_UDP`：先连 WiFi（`MICRO_ROS_AGENT_IP` / `MICRO_ROS_AGENT_PORT`，
  默认 `192.168.71.204:8888`），再 `set_microros_udp_transports()` 连接 Agent。
- 两个宏在 `rtconfig.h` 中定义，决定编译哪套传输。

### 3.2 发布的 ROS 2 话题

| 话题名 | 消息类型 | 数据来源 |
| --- | --- | --- |
| `stm32/battery` | `sensor_msgs/msg/BatteryState` | ADC 读取外部总线电压 `V_bus` |
| `stm32/imu` | `sensor_msgs/msg/Imu` | ICM20608 六轴（加速度 g、角速度 dps） |
| `odom` | `nav_msgs/msg/Odometry` | 左右轮编码器 TIM 直读 + 差速航位推算 |
| `stm32/info` | `std_msgs/msg/String` | 版本/传感器/状态 JSON 汇总 |
| `sensor/light` | `std_msgs/msg/Float32` | AP3216C 环境光 lux |
| `sensor/proximity` | `std_msgs/msg/UInt16` | AP3216C 接近原始值 |

### 3.3 传感器与运动学
- **编码器**：TIM2/TIM3 配置为编码器模式 3（正交解码 ×4），直读左右轮脉冲，
  按 `PPR × 减速比 × 4` 换算行走距离，差速模型推算 `x/y/yaw`。
- **ADC 电压**：`adc1` 通道 0，分压系数 `VOLT_DIV_COEFF`（默认 2.0）。
- **IMU**：ICM20608（I2C2，0x68），带 4 次重试规避上电时序偶发失败。
- **AP3216C**：I2C2，0x1e，环境光/接近。
- **AHT10**（可选）：I2C1，0x38，温湿度。

### 3.4 健壮性设计（Agent 自愈）
- 线程内 `rclc_executor_spin_some` 周期驱动发布（默认 50Hz，`ODOM_PUBLISH_PERIOD_MS=20`）。
- 定期 `rmw_uros_ping_agent` 探活，连续失败 3 次即销毁全部 rcl 实体并整组重建，
  实现 UDP 会话断流后的自动恢复。
- 初始连接带有最多 30s 的 ping 重试（`micro_ros_create_entities`）。
- 启动全程探针 `[boot] init start` + 各阶段 `rt_kprintf`，便于确认固件加载与初始化进度。

## 4. 构建与运行

### 4.1 配置传输方式
在 `rtconfig.h` 中启用其一：
- 串口：`#define MICRO_ROS_USE_SERIAL`
- UDP/WiFi：`#define MICRO_ROS_USE_UDP`（并确认 WiFi SSID/密码与 Agent IP 已设置）

WiFi 凭据在 `main.c` 顶部：`WIFI_SSID` / `WIFI_PASSWORD`（默认 `HUAWEI-3106`）。

### 4.2 编译
使用 RT-Thread 的 scons 构建（或 RT-Thread Studio 图形界面）：
```
scons
```

### 4.3 启动上位机 micro-ROS Agent
- 串口方式：
  ```
  docker run -it --privileged -v /dev:/dev microros/micro-ros-agent:humble serial --dev /dev/ttyUSB0
  ```
- UDP 方式：
  ```
  docker run -it -p 8888:8888/udp --privileged microros/micro-ros-agent:humble udp4 --port 8888
  ```
  > 注意：官方包 README 中示例为 `galactic` 版，本工程静态库为 `humble`，
  > 实际请使用 `microros/micro-ros-agent:humble` 镜像及对应端口。

### 4.4 烧录与验证
1. 下载固件到 STM32，上电后节点会自动连接 WiFi（UDP 模式）并等待 Agent ping 通。
2. 在上位机查看话题：
   ```
   ros2 topic echo /odom
   ros2 topic echo /stm32/imu
   ros2 topic echo /stm32/battery
   ```

## 5. 可调整项
- 编码器引脚/定时器、底盘半径/轮距/PPR/减速比：见 `main.c` 顶部宏。
- 发布频率：`ODOM_PUBLISH_PERIOD_MS`。
- Agent 地址：`MICRO_ROS_AGENT_IP` / `MICRO_ROS_AGENT_PORT`。
- 通过 `PKG_USING_ICM20608` / `PKG_USING_AP3216C` / `PKG_USING_AHT10` 宏启用/移除传感器。

## 6. 备注
- 本工程 README 原为空，本文档依据 `applications/main.c`、`packages/pkgs.json` 与
  `packages/micro_ros-humble-gcc-10/README.md` 整理而成（整理于 2026-08-26）。
- `main()` 主循环仅作占位（10s 空转），所有业务逻辑在 `micro_ros` 线程中运行。