https://github.com/micro-ros/micro_ros_platformio
micro-ROS library for Platform.IO
https://github.com/micro-ros/micro_ros_platformio
Last synced: 8 months ago
JSON representation
micro-ROS library for Platform.IO
- Host: GitHub
- URL: https://github.com/micro-ros/micro_ros_platformio
- Owner: micro-ROS
- License: apache-2.0
- Created: 2022-04-05T12:18:46.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-04-03T06:13:56.000Z (11 months ago)
- Last Synced: 2025-04-03T07:24:14.322Z (11 months ago)
- Language: Python
- Size: 384 KB
- Stars: 255
- Watchers: 7
- Forks: 89
- Open Issues: 30
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.rst
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# micro-ROS for PlatformIO
This is a micro-ROS library for bare metal projects based on platformIO.
The build process for ROS 2 and micro-ROS is based on custom meta-build system tools and [CMake](https://cmake.org/).
PlatformIO will handle the full build process, including dependencies, compilation and linkage.
- [micro-ROS for PlatformIO](#micro-ros-for-platformio)
- [Supported boards](#supported-boards)
- [Requirements](#requirements)
- [How to add to your project](#how-to-add-to-your-project)
- [Library configuration](#library-configuration)
- [ROS 2 distribution](#ros-2-distribution)
- [Transport configuration](#transport-configuration)
- [Extra packages](#extra-packages)
- [Other configuration](#other-configuration)
- [Extend library targets](#extend-library-targets)
- [Transport implementation](#transport-implementation)
- [Time source](#time-source)
- [Using the micro-ROS Agent](#using-the-micro-ros-agent)
- [Examples](#examples)
- [Purpose of the Project](#purpose-of-the-project)
- [License](#license)
- [Known Issues/Limitations](#known-issueslimitations)
## Supported boards
Supported boards are:
| Board | Platform | Framework | Transports | Default meta file |
| -------------------------------------------- | ------------- | ----------- | ---------------------------------------- | ------------------------ |
| `portenta_h7_m7` | `ststm32` | `arduino` | `serial`
`wifi` | `colcon.meta` |
| `teensy41` | `teensy` | `arduino` | `serial`
`native_ethernet` | `colcon.meta` |
| `teensy40` | `teensy` | `arduino` | `serial` | `colcon.meta` |
| `teensy36`
`teensy35`
`teensy31` | `teensy` | `arduino` | `serial` | `colcon_lowmem.meta` |
| `due` | `atmelsam` | `arduino` | `serial` | `colcon_verylowmem.meta` |
| `zero` | `atmelsam` | `arduino` | `serial` | `colcon_verylowmem.meta` |
| `olimex_e407` | `ststm32` | `arduino` | `serial` | `colcon.meta` |
| `esp32dev` | `espressif32` | `arduino` | `serial`
`wifi`
`ethernet`* | `colcon.meta` |
| `nanorp2040connect` | `raspberrypi` | `arduino` | `serial`
`wifi_nina` | `colcon_verylowmem.meta` |
| `pico` | `raspberrypi` | `arduino` | `serial` | `colcon.meta` |
\* Community contributed
The community is encouraged to open pull request with custom use cases.
## Requirements
- PlatformIO [local installation](https://docs.platformio.org/en/stable/core/installation.html) or [PlatformIO IDE for VSCode](https://platformio.org/install/ide?install=vscode)
- PlatformIO Core version 6.1.0 or greater
- PlatformIO needs `git`, `cmake` and `pip3` to handle micro-ROS internal dependencies:
```bash
apt install -y git cmake python3-pip
```
### Platform specific requirements
#### MacOS
XCode command line tools are distributed with toolchain that is not fully compatible with micro-ROS build process.
To fix this, install GNU [binutils](https://www.gnu.org/software/binutils/) using [Homebrew](https://brew.sh/):
```bash
brew install binutils
```
## How to add to your project
The library can be included as a regular git library dependence on your `platform.ini` file:
```ini
...
lib_deps =
https://github.com/micro-ROS/micro_ros_platformio
```
Now to proceed with the PlatformIO workflow:
```bash
pio lib install # Install dependencies
pio run # Build the firmware
pio run --target upload # Flash the firmware
```
After the library is compiled for first time the build process will be skipped, to trigger a library build and apply [library modifications](#library-configuration) on your next platformIO build:
```bash
pio run --target clean_microros # Clean library
```
## Library configuration
This section details the different configuration parameters available on the project `platform.ini` file.
A explanation for adding custom targets is also present
### ROS 2 distribution
The target ROS 2 distribution can be configured with the `board_microros_distro = `, supported values are:
- `humble`
- `iron`
- `jazzy` *(default value)*
- `kilted`
- `rolling`
### Transport configuration
The transport can be configured with the `board_microros_transport = `, supported values and configurations are:
- `serial` *(default value)*
```c
Serial.begin(115200);
set_microros_serial_transports(Serial);
```
- `wifi`
- `wifi_nina`
```c
IPAddress agent_ip(192, 168, 1, 113);
size_t agent_port = 8888;
char ssid[] = "WIFI_SSID";
char psk[]= "WIFI_PSK";
set_microros_wifi_transports(ssid, psk, agent_ip, agent_port);
```
- `native_ethernet`
```c
byte local_mac[] = { 0xAA, 0xBB, 0xCC, 0xEE, 0xDD, 0xFF };
IPAddress local_ip(192, 168, 1, 177);
IPAddress agent_ip(192, 168, 1, 113);
size_t agent_port = 8888;
set_microros_native_ethernet_transports(local_mac, local_ip, agent_ip, agent_port);
```
- `ethernet`
```c
IPAddress client_ip(192, 168, 1, 177);
IPAddress gateway(192, 168, 1, 1);
IPAddress netmask(255, 255, 255, 0);
IPAddress agent_ip(192, 168, 1, 113);
size_t agent_port = 8888;
// Optional hostname, defaults to nullptr (no hostname set)
set_microros_ethernet_transports(client_ip, gateway, netmask, agent_ip, agent_port, "my-microros-device");
```
- `custom`
The user will need to write transport functions in app code and provide it to the micro-ROS library using [`rmw_uros_set_custom_transport()` API](https://micro.ros.org/docs/tutorials/advanced/create_custom_transports/)
```c
bool platformio_transport_open(struct uxrCustomTransport * transport) {...};
bool platformio_transport_close(struct uxrCustomTransport * transport) {...};
size_t platformio_transport_write(struct uxrCustomTransport* transport, const uint8_t * buf, size_t len, uint8_t * err) {...};
size_t platformio_transport_read(struct uxrCustomTransport* transport, uint8_t* buf, size_t len, int timeout, uint8_t* err) {...};
rmw_uros_set_custom_transport(
MICROROS_TRANSPORTS_FRAMING_MODE, // Set the MICROROS_TRANSPORTS_FRAMING_MODE or MICROROS_TRANSPORTS_PACKET_MODE mode accordingly
NULL,
platformio_transport_open,
platformio_transport_close,
platformio_transport_write,
platformio_transport_read
);
```
### Extra packages
Colcon packages can be added to the build process using this two methods:
- Package directories copied on the `/extra_packages` folder.
- Git repositories included on the `/extra_packages/extra_packages.repos` yaml file.
This should be used for example when adding custom messages types or custom micro-ROS packages.
### Other configuration
Library packages can be configured with a customized meta file on the project main folder: `board_microros_user_meta = `.
This allows the user to customize the library memory resources or activate optional functionality such as multithreading, including configuration of user [Extra packages](#extra-packages).
- Documentation on available parameters can be found [here](https://micro.ros.org/docs/tutorials/advanced/microxrcedds_rmw_configuration) and [here]([microxrcedds_rmw_configuration](https://micro-xrce-dds.docs.eprosima.com/en/latest/client.html)).
- Default configurations can be found on the [metas](./metas) folder.
*Note: the [common.meta](./metas/common.meta) file makes general adjustments to the library and shall not be modified by the user.*
## Extend library targets
This library can be easily adapted to different boards, transports or RTOS, to achieve this the user shall provide:
### Transport implementation
New transport implementations shall follow the signatures shown on [micro_ros_platformio.h](./platform_code/arduino/micro_ros_platformio.h), the [provided sources](./platform_code) can be used as reference along [this documentation](https://micro-xrce-dds.docs.eprosima.com/en/latest/transport.html#custom-transport). Contributed transport source code shall be added on the `./platform_code//` path. Example:
- `platform.ini`:
```ini
framework = arduino
board_microros_transport = wifi
```
- Transport source files: [platform_code/arduino/wifi](https://github.com/micro-ROS/micro_ros_platformio/tree/main/platform_code/arduino/wifi)
- Also, a `MICRO_ROS_TRANSPORT__` definition will be available:
https://github.com/micro-ROS/micro_ros_platformio/blob/de7a61c7e86fdd0186ed8b7d8ec320994e8ebcbf/ci/src/main.cpp#L3
*Note: `board_microros_transport = custom` should not be used, as it is used to add custom transports on user app code*
### Time source
micro-ROS needs a time source to handle executor spins and synchronize reliable communication. To achieve this, a `clock_gettime` [POSIX compliant](https://linux.die.net/man/3/clock_gettime) implementation is required, with a minimum resolution of 1 millisecond.
This method shall be included on a `clock_gettime.cpp` source file under the `./platform_code//` path, an example implementation can be found on [clock_gettime.cpp](./platform_code/arduino/clock_gettime.cpp)
## Using the micro-ROS Agent
It is possible to use a **micro-ROS Agent** just by using this docker command:
```bash
# UDPv4 micro-ROS Agent
docker run -it --rm -v /dev:/dev -v /dev/shm:/dev/shm --privileged --net=host microros/micro-ros-agent:$ROS_DISTRO udp4 --port 8888 -v6
# Serial micro-ROS Agent
docker run -it --rm -v /dev:/dev -v /dev/shm:/dev/shm --privileged --net=host microros/micro-ros-agent:$ROS_DISTRO serial --dev [YOUR BOARD PORT] -v6
# TCPv4 micro-ROS Agent
docker run -it --rm -v /dev:/dev -v /dev/shm:/dev/shm --privileged --net=host microros/micro-ros-agent:$ROS_DISTRO tcp4 --port 8888 -v6
# CAN-FD micro-ROS Agent
docker run -it --rm -v /dev:/dev -v /dev/shm:/dev/shm --privileged --net=host microros/micro-ros-agent:$ROS_DISTRO canfd --dev [YOUR CAN INTERFACE] -v6
```
For the supported transports, only the `serial` and `udp4` versions shall be used, although users can develop
and use the agent to test their own `tcp4` and `canfd` custom transports.
It is also possible to use custom transports on a `micro-XRCE Agent` instance. More info available [here](https://micro-xrce-dds.docs.eprosima.com/en/latest/agent.html#custom-transport-agent).
## Examples
A simple publisher project using serial transport is available on the [examples](./examples) directory, this examples is meant to be modified with the user board.
- More micro-ROS usage examples are available on [micro-ROS-demos/rclc](https://github.com/micro-ROS/micro-ROS-demos/tree/jazzy/rclc).
- For a complete micro-ROS tutorial, check [Programming with rcl and rclc](https://micro.ros.org/docs/tutorials/programming_rcl_rclc/overview/) documentation.
## 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 this repository,
see the file [3rd-party-licenses.txt](3rd-party-licenses.txt).
## Known Issues/Limitations
- For `wifi_nina` transport, the following versioning shall be used:
```ini
lib_deps =
arduino-libraries/WiFiNINA@^1.8.13
```
- For `nanorp2040connect` board with `serial` transport, the library dependency finder shall be set to `chain+`:
```ini
lib_ldf_mode = chain+
```
- For `pico` board with `serial` transport, the library dependency finder shall be set to `chain+`:
```ini
lib_ldf_mode = chain+
```