Installing and Starting the microROS Agent

Description: The same system can have both the Docker startup method and the source startup method installed at the same time, but when starting, you can only choose one of them. In general, the Docker startup method is simple and convenient, so the Docker startup method is recommended.

Note: The out-of-the-box virtual machine already comes with all the environments, so there is no need to reinstall them. Just refer to the Quick Start guide and use it directly. This tutorial is provided for setting up a personal environment.

1. Starting the microROS Agent with Docker

The microROS agent is started via the Docker method this time, so you need to have Docker set up on the system first. The out-of-the-box system already has the relevant Docker environment set up, so it can be run directly.

Starting the WIFI Agent with Docker

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

Here, --port 8090 is the network port number, and -v4 is the LOG print level. The higher the value, the more output is printed. You can modify these according to your actual situation.

If you need to stop the agent, press Ctrl+C in the terminal to exit the agent.

Note: Do not directly close the terminal, otherwise the docker container will keep running in the background.

If the microcontroller restarts and reconnects to the agent multiple times, causing ROS2 to discover multiple identical nodes, this does not actually affect usage. Just press Ctrl+C to stop the agent, then reset the microcontroller and reconnect to the agent.

Starting the Serial Agent with Docker

xxxxxxxxxx
docker run -it --rm -v /dev:/dev -v /dev/shm:/dev/shm --privileged --net=host microros/micro-ros-agent:humble serial --dev /dev/ttyUSB0 -b 921600 -v4

Here, --dev /dev/ttyUSB0 is the serial device number, and -b 921600 is the baud rate. You can modify these according to your actual situation.

If you need to stop the agent, press Ctrl+C in the terminal to exit the agent.

Note: Do not directly close the terminal, otherwise the docker container will keep running in the background.

If the microcontroller restarts and reconnects to the agent multiple times, causing ROS2 to discover multiple identical nodes, this does not actually affect usage. Just press Ctrl+C to stop the agent, then reset the microcontroller and reconnect to the agent.

When the Agent Fails to Start

The microROS agent can only be started in one terminal. If a terminal is already running the microROS agent in the background, starting the agent again will cause an error. Please first press Ctrl+C in the original agent terminal to exit the agent, and then run the agent again.

If starting the agent fails the next time because the terminal was closed directly, you can solve the problem by restarting the virtual machine/computer, or by manually stopping the docker container.

How to manually stop the docker container:

First, query the current docker container ID, and then stop the current agent docker container.

xxxxxxxxxx
docker ps -a | grep microros/micro-ros-agent
docker stop xxxxxxxxxx
docker run -it --rm -v /dev:/dev -v /dev/shm:/dev/shm --privileged --net=host microros/micro-ros-agent:humble udp4 --port 8090 -v4

2. Starting the microROS Agent from Source

Installing the tinyxml2 Dependency

Run the following command in the terminal to install tinyxml2.

xxxxxxxxxx
cd ~/
git clone https://github.com/leethomason/tinyxml2.git
cd tinyxml2
mkdir build
cd build
sudo cmake ..
sudo make
sudo make install

Installing the python3-rosdep Tool

Run the following command in the terminal to install the rosdep tool. You can skip this step if it is already installed.

xxxxxxxxxx
sudo apt install python3-rosdep

Compiling the micro_ros_setup Environment

Activate the ROS2 environment variables. Here, we take the humble version as an example. If it is already activated, you can skip the activation step.

xxxxxxxxxx
source /opt/ros/humble/setup.bash

Create and enter the uros_ws workspace in the user directory.

xxxxxxxxxx
mkdir ~/uros_ws && cd ~/uros_ws
mkdir src

Download the micro_ros_setup files to the src folder.

xxxxxxxxxx
git clone -b $ROS_DISTRO https://github.com/micro-ROS/micro_ros_setup.git src/micro_ros_setup

Initialize rosdep.

xxxxxxxxxx
sudo rosdep init

If a network problem occurs, add the -E parameter.

xxxxxxxxxx
sudo -E rosdep init

If all the above steps report errors and rosdep still cannot be initialized, you can create a new 20-default.list file in the /etc/ros/rosdep/sources.list.d/ directory, add the following content, and then proceed to the next step.

​x
# os-specific listings first
yaml https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/osx-homebrew.yaml osx
​
# generic
yaml https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/base.yaml
yaml https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/python.yaml
yaml https://raw.githubusercontent.com/ros/rosdistro/master/rosdep/ruby.yaml
gbpdistro https://raw.githubusercontent.com/ros/rosdistro/master/releases/fuerte.yaml fuerte
​
# newer distributions (Groovy, Hydro, ...) must not be listed anymore, they are being fetched from the rosdistro index.yaml instead

Update rosdep and install the related driver packages.

xxxxxxxxxx
rosdep update && rosdep install --from-paths src --ignore-src -y

Build the workspace.

xxxxxxxxxx
colcon build

Activate the micro_ros_setup environment.

xxxxxxxxxx
source install/local_setup.bash

Compiling the micro_ros_agent Environment

xxxxxxxxxx
ros2 run micro_ros_setup create_agent_ws.sh
ros2 run micro_ros_setup build_agent.sh

If an error occurs while running the build_agent.sh build, run the build again.

Starting the microROS Agent from Source

Activate the micro_ros_agent agent environment.

xxxxxxxxxx
source ~/uros_ws/install/local_setup.sh

Starting the WIFI Agent from ROS2 Source

xxxxxxxxxx
ros2 run micro_ros_agent micro_ros_agent udp4 --port 8090 -v4

Here, --port 8090 is the network port number, and -v4 is the LOG print level. The higher the value, the more output is printed. You can modify these according to your actual situation.

If you need to stop the agent, press Ctrl+C in the terminal to exit the agent.

Starting the Serial Agent from ROS2 Source

xxxxxxxxxx
ros2 run micro_ros_agent micro_ros_agent serial --dev /dev/ttyUSB0 -b 921600 -v4

Here, --dev /dev/ttyUSB0 is the serial device number, and -b 921600 is the baud rate. You can modify these according to your actual situation.

If you need to stop the agent, press Ctrl+C in the terminal to exit the agent.