MicroROS Robot Setup Guide (Clean ROS2 Install)

What You Need to Know

You have a MicroROS control board (ESP32-S3) managing motors, IMU, and servos. It connects to ROS2 via a micro-ROS agent running on your RPI 5.

---

1. Install ROS2 Humble on RPI 5

# Set locale to UTF-8
sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8

# Add ROS2 repository
sudo apt install software-properties-common
sudo add-apt-repository universe
sudo apt update && sudo apt install curl gnupg lsb-release -y
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(source /etc/os-release && echo $UBUNTU_CODENAME) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null

# Install ROS2 Humble Desktop
sudo apt update
sudo apt upgrade
sudo apt install ros-humble-desktop python3-argcomplete python3-colcon-common-extensions

# Auto-source ROS2
echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc
source ~/.bashrc

---

2. Install micro-ROS Agent (Two Options)

Option A: Docker (Recommended)

# Install Docker if needed
sudo apt install docker.io
sudo usermod -aG docker $USER
# Log out and back in

# Run agent (WiFi connection to ESP32)
docker run -it --rm --net=host microros/micro-ros-agent:humble udp4 --port 8090 -v4

Option B: From Source

# Install dependencies
sudo apt install python3-rosdep
sudo rosdep init
rosdep update

# Create workspace
mkdir -p ~/uros_ws/src
cd ~/uros_ws
git clone -b humble https://github.com/micro-ROS/micro_ros_setup.git src/micro_ros_setup
rosdep install --from-paths src --ignore-src -y
colcon build
source install/local_setup.bash

# Build agent
ros2 run micro_ros_setup create_agent_ws.sh
ros2 run micro_ros_setup build_agent.sh

# Run agent
source ~/uros_ws/install/local_setup.sh
ros2 run micro_ros_agent micro_ros_agent udp4 --port 8090 -v4

---

3. Configure MicroROS Board

The ESP32 board needs:
- WiFi SSID/password
- Agent IP (your RPI 5 IP)
- Agent port (8090)
- ROS_DOMAIN_ID (default 20)

Two ways to configure:

A. Via Serial (type-C cable)

1. Connect board to RPI 5 via USB
2. Run config script:

python3 config_robot.py

3. Edit config_robot.py with your WiFi/IP before running

B. Via Firmware Build (if reflashing)

Use ESP-IDF menuconfig:

idf.py menuconfig
# Set: micro-ROS Settings → WiFi Config → SSID/Password
# Set: micro-ROS Settings → Agent IP/Port

---

4. Hardware Connections

Device	Connection	Notes
Motors (M1-M4)	White shell → Board, Black shell → Motor	310 encoder motors
MS200 Lidar	Anti-reverse connector	Serial UART1 (GPIO17/18)
ESP32 Camera	Custom GPIO ports	See “Drive ESP32 WiFi Camera” doc
RPI 5 Power	Type-C PD from board	Board powers RPI 5 via PD

---

5. Test the Connection

Start agent (RPI 5):

docker run -it --rm --net=host microros/micro-ros-agent:humble udp4 --port 8090 -v4

Power on board → Should see:

• WiFi connection
• Agent connection
• /YB_Car_Node node created

Check from RPI 5:

ros2 node list  # Should show /YB_Car_Node
ros2 node info /YB_Car_Node

# Published topics:
ros2 topic echo /scan      # Lidar
ros2 topic echo /imu       # IMU data
ros2 topic echo /odom_raw  # Odometry

# Control topics:
ros2 topic pub --once /cmd_vel geometry_msgs/msg/Twist "{linear: {x: 0.5}, angular: {z: 0.0}}"  # Move forward
ros2 topic pub /beep std_msgs/msg/UInt16 "data: 1"  # Buzzer on
ros2 topic pub /servo_s1 std_msgs/msg/Int32 "data: 30"  # Servo 1 to 30°

---

6. Robot Bringup (State Estimation)

For full functionality (sensor fusion, TF transforms):

# Install required packages
sudo apt install ros-humble-robot-localization ros-humble-imu-filter-madgwick

# Run bringup (after agent running)
ros2 launch yahboomcar_bringup yahboomcar_bringup_launch.py

What this does:
- Fuses IMU + odometry → /odom topic
- Publishes TF: odom → base_footprint → base_link → sensors
- Loads robot URDF model

---

7. Key Topics Reference

Topic	Type	Purpose
/cmd_vel	Twist	Control robot speed
/scan	LaserScan	Lidar data (11Hz)
/imu	Imu	Raw IMU (20Hz)
/odom_raw	Odometry	Encoder odometry (20Hz)
/odom	Odometry	Fused odom+IMU (after bringup)
/beep	UInt16	Buzzer (0=off, 1=on, >10=ms duration)
/servo_s1, /servo_s2	Int32	Servo angles (-90 to 90°)

---

8. Network Setup

Same LAN + Matching ROS_DOMAIN_ID:

# On RPI 5, add to ~/.bashrc:
export ROS_DOMAIN_ID=20  # Match board config

Bridge mode for VM or use same WiFi for all devices.

---

9. Camera Setup (ESP32 WiFi Camera)

1. Connect camera to board’s custom GPIO
2. Power on → Creates WiFi AP: Yahboom-ESP32_WIFI
3. Connect to AP (no password)
4. Stream: http://192.168.4.1:81/stream

---

Common Issues

Problem	Fix
Agent won’t connect	Check IP, port, WiFi, ROS_DOMAIN_ID match
No /YB_Car_Node	Press reset on board, restart agent
Motors don’t move	Check battery voltage, /cmd_vel topic
Serial port busy	Stop agent if using ttyUSB0 for serial config

---

Quick Start Checklist

• [ ] ROS2 Humble installed
• [ ] micro-ROS agent running (Docker or source)
• [ ] Board configured (WiFi, agent IP)
• [ ] Board powered, connected to agent
• [ ] ros2 node list shows /YB_Car_Node
• [ ] Test /cmd_vel, /scan, /imu topics
• [ ] (Optional) Run yahboomcar_bringup_launch.py for full stack

---

You’re good to go. The board handles low-level motor/sensor control. RPI 5 runs navigation, mapping, computer vision. Agent bridges them.