This repository contains Docker-related material aimed at setting up, configuring and developing a micro-ROS-based application.
This set of Dockerfiles provides ready-to-use environments to easily execute micro-ROS examples in your host machine, as well as to use the standalone micro-ROS build system. In addition, two images are provided that allow using micro-ROS as an external library, both in ESP-IDF.
The Docker images can be found at dockerhub.
The available images are listed below:
| Image | Description | Status |
|---|---|---|
| base | Base image with a ROS 2 Iron installation + micro-ROS specific build system tools. Used as base of any other micro-ROS image |    |
| micro-ros-agent | Image containing a pre-compiled micro-ROS-Agent, ready to use as a standalone application |    |
| micro-ros-demos | Contains pre-compiled micro-ROS demo applications, ready to use to get a taste of micro-ROS capabilities |    |
| micro_ros_static_library_builder | Allows to use a pre-compiled micro-ROS library to develop applications in external environments |    |
| esp-idf-microros | Allows to use micro-ROS as a component of the ESP-IDF build system |    |
You need to have Docker in your system. For installing Docker, refer to the official documentation at https://www.docker.com/.
To get an image, use the docker pull command:
- e.g.
docker pull microros/base
You can select the preferred tag by appending :tag to the image name
- e.g.
docker pull microros/base:iron
Once you have the image locally, type docker run to start it. It is not mandatory, although usually useful, to launch your containers using the --rm and --net=host flags:
- e.g.
docker run -it --rm --net=host microros/micro-ros-agent:iron
--rm makes sure that the docker image will be removed after exiting.
--net=host provides the container with the same network access as the host.
-it allocates a pseudo-TTY for you and keeps stdin listening.
Another used command is -v to map local files with docker container ones.
-v is useful in case you may want to flash boards from within a Docker container.
It is the base for the rest of the containers. It contains the necessary micro-ROS setup tools and dependencies. From this image, you can start any development targeting micro-ROS.
This image is meant to be used as a stand-alone application.
It includes the installation of the ROS 2 version selected by the tag selected, together with a micro-ROS Agent.
The entry point of this image is directly the micro-ROS Agent, so upon execution of docker run you will be facing the micro-ROS Agent command line input. Running:
- e.g.
docker run -it --net=host microros/micro-ros-agent:iron udp4 -p 9999
will start a micro-ROS Agent listening to UDP messages on port 9999.
micro-ros-demos is one of the example images.
With this image, you can launch example applications using micro-ROS (compiled for Linux machines).
This image entry point has a ROS 2 environment set up with micro-ROS examples.
You can run regular ROS 2 tools to launch the examples.
- eg:
docker run -it --net=host microros/micro-ros-demos bash
The currently available examples are listed here.
The micro_ros_static_library_builder docker image provides you with a set of include files and pre-compiled micro-ROS libraries to develop your micro-ROS application within the Arduino IDE environment.
To be able to use it, use the following command to instantiate a container of this image:
- e.g.
docker run -it -v $(pwd):/arduino_project --net=host microros/micro_ros_static_library_builder:iron.
Note that folders added to extras/library_generation/extra_packages and entries added to extras/library_generation/extra_packages/extra_packages.repos will be taken into account by this build system.
This Docker image allows you to use micro-ROS as a component of the ESP-IDF build system.
To use it:
- e.g.
docker run -it --user espidf --volume="/etc/timezone:/etc/timezone:ro" -v $(pwd):/micro_ros_espidf_component -v /dev:/dev --privileged --workdir /micro_ros_espidf_component microros/esp-idf-microros:latest /bin/bash"
Then, you can navigate to your example aplications and build it using the ESP IDF buildtool system script, idf.py menuconfig/build/flash/monitor.
These Dockerfiles are used for automatically creating images on Docker Hub. These builds are tagged with the ROS 2 version they will be compatible with: e.g. humble, iron, rolling... The latest tag will always correspond to the latest release of ROS 2.
These automatic builds have a direct relationship with the content of the micro-ROS repositories:
| Image | Triggers |
|---|---|
| base | https://github.com/micro-ROS/micro-ROS-build |
| micro-ros-agent | https://github.com/micro-ROS/micro-ROS-Agent https://github.com/eProsima/Micro-XRCE-DDS-Agent |
| micro-ros-demos | https://github.com/micro-ROS/micro-ROS-demos |
| micro_ros_static_library_builder | https://github.com/micro-ROS/micro_ros_arduino |
| esp-idf-microros | https://github.com/micro-ROS/micro_ros_espidf_component |
Apart from GitHub repositories changes, a build can be triggered whenever the base image is updated on Docker Hub.
Base images are specified with the FROM: directive in the Dockerfile.
This software is not ready for production use. It has neither been developed nor tested for a specific use case. However, the license conditions of the applicable Open Source licenses allow you to adapt the software to your needs. Before using it in a safety relevant setting, make sure that the software fulfills your requirements and adjust it according to any applicable safety standards, e.g., ISO 26262.
This repository is open-sourced under the Apache-2.0 license. See the LICENSE file for details.
For a list of other open-source components included in this repository, see the file 3rd-party-licenses.txt.
There are no known limitations.
If you find issues, please report them.