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:
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:jazzy
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:jazzy
--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:jazzy 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.
This image provides you with a ready-to-flash firmware for Olimex-STM32-E407 boards with demos included. To be able to flash, you need to map your devices to the Docker container as follows:
- e.g.
docker run -it --privileged -v /dev/bus/usb:/dev/bus/usb microros/micro-ros-olimex-nuttx:jazzy
Once inside the container, you can flash the board by running scripts/flash.sh
from the firmware/NuttX
directory.
There you can find a publisher and a subscriber examples.
Both examples use serial transport to communicate with a micro-ROS Agent, so you should start an Agent with the same transport (You can use the micro-ros-agent
image to do so).
Once a Client-Agent communication is established you can use ROS 2 tools to view the publications from the Olimex or to publish messages to it.
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:jazzy
.
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. foxy, 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.