---
# System prepended metadata

title: ESP32 + micro-ROS (USB Serial) （ROS 2 Humble / WSL）

---

# ESP32 + micro-ROS (USB Serial) （ROS 2 Humble / WSL）

## 需求

### 硬體：
* ESP32 板（例如 DevKitC、WROOM-32）
* USB 線連接電腦

### 軟體：
* Windows 10/11
* WSL 2 + Ubuntu 22.04 (ROS 2 Humble)
* Arduino IDE 或 PlatformIO
* micro-ROS Arduino 函式庫

## 步驟 0：準備 WSL / ROS 2
1. 確認 WSL 安裝：
    ```
    wsl --version
    ```
2. Ubuntu 22.04 安裝 ROS 2 Humble：  https://docs.ros.org/en/humble/Installation/Alternatives/Ubuntu-Development-Setup.html

3. 安裝 micro-ROS Agent：
    ```
    cd ~/ros2_ws/src
    git clone -b humble https://github.com/micro-ROS/micro_ros_setup.git
    cd ~/ros2_ws
    rosdep update
    rosdep install --from-paths src --ignore-src -r -y --rosdistro humble
    colcon build
    source install/local_setup.bash
    ```
4. 建立與編譯 micro-ROS Agent
    ```
    # 在 micro_ros_setup 資料夾裡建立 Agent workspace
    ros2 run micro_ros_setup create_agent_ws.sh
    ros2 run micro_ros_setup build_agent.sh
    ```
## 步驟 1：Arduino IDE 安裝 micro-ROS 函式庫
1. 選擇板子：
    * ```Tool``` → ```board:...``` → ```boeard manager``` → ```ESP32 Dev Module```
2. 選擇 COM port（Windows 裝置管理員查看）
3. ```Sketch``` → ```Include Library``` →  ```Add .ZIP Library```... 加入由 [Micro-ROS Arduino](https://github.com/micro-ROS/micro_ros_arduino/releases) 下載下來的 library zip 檔，詳細參考 [micro_ros_arduino Github](https://github.com/micro-ROS/micro_ros_arduino)
可以從 File → Examples 加入 Micro-ROS Arduino 的範例程式並燒錄到 ESP32 進行測試

## 步驟 2：ESP32 程式碼（Publisher 範例）
每秒發送一個整數給 micro-ROS Agent
```
#include <micro_ros_arduino.h>
#include <rcl/rcl.h>
#include <rclc/rclc.h>
#include <rclc/executor.h>
#include <std_msgs/msg/int32.h>

rcl_publisher_t publisher;
std_msgs__msg__Int32 msg;
rclc_executor_t executor;
rclc_support_t support;
rcl_allocator_t allocator;
rcl_node_t node;
rcl_timer_t timer;

#define LED_PIN 13
#define RCCHECK(fn) { rcl_ret_t rc = fn; if(rc != RCL_RET_OK) {while(1){digitalWrite(LED_PIN,!digitalRead(LED_PIN)); delay(100);}} }
#define RCSOFTCHECK(fn) { rcl_ret_t rc = fn; (void)rc; }

void timer_callback(rcl_timer_t * timer, int64_t last_call_time) {
  RCLC_UNUSED(last_call_time);
  if (timer != NULL) {
    RCSOFTCHECK(rcl_publish(&publisher, &msg, NULL));
    msg.data++;
  }
}

void setup() {
  Serial.begin(115200);         // 先初始化 Serial
  delay(1000);                  // 等 USB 連線穩定
  set_microros_transports();    // 初始化 micro-ROS transport

  pinMode(LED_PIN, OUTPUT);
  digitalWrite(LED_PIN, HIGH);

  allocator = rcl_get_default_allocator();
  RCCHECK(rclc_support_init(&support, 0, NULL, &allocator));
  RCCHECK(rclc_node_init_default(&node, "esp32_node", "", &support));
  RCCHECK(rclc_publisher_init_default(
    &publisher,
    &node,
    ROSIDL_GET_MSG_TYPE_SUPPORT(std_msgs, msg, Int32),
    "esp32_data"));

  RCCHECK(rclc_timer_init_default(
    &timer,
    &support,
    RCL_MS_TO_NS(1000),
    timer_callback));

  RCCHECK(rclc_executor_init(&executor, &support.context, 1, &allocator));
  RCCHECK(rclc_executor_add_timer(&executor, &timer));

  msg.data = 0;
}

void loop() {
  delay(100);
  RCSOFTCHECK(rclc_executor_spin_some(&executor, RCL_MS_TO_NS(100)));
}
```

## 步驟 3：燒錄 ESP32

1. 選板子 → ESP32 Dev Module
2. 選 COM port（Windows 裝置管理員）
3. 上傳程式
4. 上傳完成後按 EN 重啟 ESP32

## 步驟 4：在 WSL 啟動 micro-ROS Agent

1. 確認 USB 裝置：

```
ls /dev/ttyUSB*
```
通常會看到 /dev/ttyUSB0

> 若用 WSL 2，需用 usbipd-win attach USB 裝置（見下步驟 4a）

2. 啟動 Agent：

```
ros2 run micro_ros_agent micro_ros_agent serial --dev /dev/ttyUSB0 -v6
```

3. 成功 log 範例：

```
[info] Serial mode => /dev/ttyUSB0
[info] Client connected
[info] New topic: /esp32_data
```

## 步驟 4a（WSL 2 USB 掛載，如果 Agent 找不到 /dev/ttyUSB0）

在 Windows PowerShell（管理員）：
```
winget install usbipd-win      # 安裝 usbipd-win
usbipd list                     # 查看 ESP32 BusID
usbipd bind --busid <BUSID>    # 綁定 USB
usbipd attach --busid <BUSID> --wsl --distribution Ubuntu
```

回到 WSL 再執行 ```ls /dev/ttyUSB*``` 應該會看到 ```/dev/ttyUSB0```

## 步驟 5：檢查 Topic
在另一個 WSL 終端：
```
ros2 topic list
```

應該看到：
```
/micro_ros_arduino_node_publisher
/rosout
```

查看數據：
```
ros2 topic echo /micro_ros_arduino_node_publisher
```

會看到每秒遞增的數字：
```
data: 0
data: 1
data: 2
...
```
小提醒
* 每次拔插 USB → WSL 需要重新 attach
* ESP32 Reset 後會重新連線 Agent
* 若看到 LED 閃爍 → 程式出錯，檢查 micro-ROS transport