uploaded 14 hours ago
Micro-ROS ESP-IDF component and sample code
Readme
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/micro-ROS/micro_ros_espidf_component/kilted/.images/banner-dark-theme.png">
<img alt="banner" src="https://raw.githubusercontent.com/micro-ROS/micro_ros_espidf_component/kilted/.images/banner-light-theme.png">
</picture>
| humble | jazzy | kilted | rolling |
|:------:|:-----:|:------:|:-------:|
| [](https://github.com/micro-ROS/micro_ros_espidf_component/actions/workflows/nightly-humble.yml) | [](https://github.com/micro-ROS/micro_ros_espidf_component/actions/workflows/nightly-jazzy.yml) | [](https://github.com/micro-ROS/micro_ros_espidf_component/actions/workflows/nightly-kilted.yml) | [](https://github.com/micro-ROS/micro_ros_espidf_component/actions/workflows/nightly-rolling.yml) |
# micro-ROS component for ESP-IDF
This component has been tested in ESP-IDF v5.2, v5.3, v5.4, v5.5, and v6.0 with ESP32, ESP32-S2, ESP32-S3, ESP32-C3 and ESP32-C6.
## Dependencies
This component needs `colcon` and other Python 3 packages inside the IDF virtual environment in order to build micro-ROS packages:
```bash
. $IDF_PATH/export.sh
pip3 install catkin_pkg colcon-common-extensions lark
```
## Middlewares available
This package support the usage of micro-ROS on top of two different middlewares:
- [eProsima Micro XRCE-DDS](https://micro-xrce-dds.docs.eprosima.com/en/latest/): the default micro-ROS middleware.
- [embeddedRTPS](https://github.com/embedded-software-laboratory/embeddedRTPS): an experimental implementation of a RTPS middleware compatible with ROS 2. (CURRENTLY NOT WORKING)
In order to select it, use `idf.py menuconfig` and go to `micro-ROS Settings > micro-ROS middleware`
## Usage
### From the ESP Component Registry
To align with the semantic versioning scheme of the ESP Component Registry, the ROS 2 distribution release year is used as the major version of the component:
| ROS 2 distro | Version |
|:------------:|:-------:|
| humble | 22.x.y |
| iron | 23.x.y |
| jazzy | 24.x.y |
| kilted | 25.x.y |
| lyrical | 26.x.y |
Rolling is published as a prerelease of the next version, for example `27.0.0-rolling.20260806`.
This branch corresponds to kilted and publishes `25.x.y` versions.
Add the component to your project with the IDF Component Manager:
```bash
idf.py add-dependency "micro-ros/micro_ros_espidf_component^25"
```
Or declare it in your main component's `idf_component.yml`:
```yaml
dependencies:
micro-ros/micro_ros_espidf_component: "^25"
```
Then build your project as usual. The Component Manager downloads the matching `25.x.y` release for Kilted.
### From this repository
You can also clone this repo into the `components` folder of your project:
```bash
cd your_project/components
git clone -b kilted https://github.com/micro-ROS/micro_ros_espidf_component.git
```
If you encounter issues during the build process, ensure that you are running in a clean shell environment _without_ the ROS 2 setup script sourced.
## Example
In order to test a int32_publisher example:
```bash
. $IDF_PATH/export.sh
cd examples/int32_publisher
# Set target board [esp32|esp32s2|esp32s3|esp32c3|esp32c6]
idf.py set-target esp32
idf.py menuconfig
# Set your micro-ROS configuration and WiFi credentials under micro-ROS Settings
idf.py build
idf.py flash
idf.py monitor
```
To clean and rebuild all the micro-ROS library:
```bash
idf.py clean-microros
```
Is possible to use a micro-ROS Agent just with this docker command:
```bash
# UDPv4 micro-ROS Agent
docker run -it --rm --net=host microros/micro-ros-agent:kilted udp4 --port 8888 -v6
```
## Build with docker container
It's possible to build this example application using the official Espressif [docker images](https://hub.docker.com/r/espressif/idf), following the same steps:
```bash
docker run --name micro-ros-espidf-component -it espressif/idf:release-v6.0 bash
git clone -b kilted https://github.com/micro-ROS/micro_ros_espidf_component.git
cd micro_ros_espidf_component/
# Install dependencies
pip install catkin_pkg colcon-common-extensions lark
cd examples/int32_publisher
# Set target board [esp32|esp32s2|esp32s3|esp32c3|esp32c6]
idf.py set-target esp32
idf.py menuconfig
# Set your micro-ROS configuration and WiFi credentials under micro-ROS Settings
idf.py build
idf.py flash
idf.py monitor
```
## Using serial transport
By default, micro-ROS component uses UDP transport, but is possible to enable UART transport or any other custom transport setting the `colcon.meta` like:
```json
...
"rmw_microxrcedds": {
"cmake-args": [
...
"-DRMW_UXRCE_TRANSPORT=custom",
...
]
},
...
```
An example on how to implement this external transports is available in `examples/int32_publisher_custom_transport`.
Available ports are `0`, `1` and `2` corresponding `UART_NUM_0`, `UART_NUM_1` and `UART_NUM_2`.
Is possible to use a micro-ROS Agent just with this docker command:
```bash
# Serial micro-ROS Agent
docker run -it --rm -v /dev:/dev --privileged --net=host microros/micro-ros-agent:kilted serial --dev [YOUR BOARD PORT] -v6
```
## Purpose of the Project
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.
## License
This repository is open-sourced under the Apache-2.0 license. See the [LICENSE](LICENSE) file for details.
For a list of other open-source components included in ROS 2 system_modes,
see the file [3rd-party-licenses.txt](3rd-party-licenses.txt).
## Known Issues/Limitations
There are no known limitations.
Links
To add this component to your project, run:
download archive
idf.py add-dependency "narukara/micro_ros_espidf_component^25.0.0"
Stats
-
Archive size ~ 1.25 MB
-
Downloaded in total 0 times
-
This version: 0 times
Badge
