{"id":28717049,"url":"https://github.com/micro-ros/micro_ros_platformio","last_synced_at":"2025-06-15T03:13:13.606Z","repository":{"id":37981040,"uuid":"478115214","full_name":"micro-ROS/micro_ros_platformio","owner":"micro-ROS","description":"micro-ROS library for Platform.IO","archived":false,"fork":false,"pushed_at":"2025-04-03T06:13:56.000Z","size":393,"stargazers_count":255,"open_issues_count":30,"forks_count":89,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-04-03T07:24:14.322Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/micro-ROS.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-05T12:18:46.000Z","updated_at":"2025-04-03T06:35:02.000Z","dependencies_parsed_at":"2023-02-10T05:05:12.156Z","dependency_job_id":"11e153b6-047c-4886-a4bf-7cc997421b36","html_url":"https://github.com/micro-ROS/micro_ros_platformio","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/micro-ROS/micro_ros_platformio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-ROS%2Fmicro_ros_platformio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-ROS%2Fmicro_ros_platformio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-ROS%2Fmicro_ros_platformio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-ROS%2Fmicro_ros_platformio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/micro-ROS","download_url":"https://codeload.github.com/micro-ROS/micro_ros_platformio/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/micro-ROS%2Fmicro_ros_platformio/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259914938,"owners_count":22931333,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-15T03:12:57.301Z","updated_at":"2025-06-15T03:13:13.588Z","avatar_url":"https://github.com/micro-ROS.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![banner](.images/banner-dark-theme.png#gh-dark-mode-only)\n![banner](.images/banner-light-theme.png#gh-light-mode-only)\n\n# micro-ROS for PlatformIO\nThis is a micro-ROS library for bare metal projects based on platformIO.\n\nThe build process for ROS 2 and micro-ROS is based on custom meta-build system tools and [CMake](https://cmake.org/).\nPlatformIO will handle the full build process, including dependencies, compilation and linkage.\n\n- [micro-ROS for PlatformIO](#micro-ros-for-platformio)\n  - [Supported boards](#supported-boards)\n  - [Requirements](#requirements)\n  - [How to add to your project](#how-to-add-to-your-project)\n  - [Library configuration](#library-configuration)\n    - [ROS 2 distribution](#ros-2-distribution)\n    - [Transport configuration](#transport-configuration)\n    - [Extra packages](#extra-packages)\n    - [Other configuration](#other-configuration)\n  - [Extend library targets](#extend-library-targets)\n    - [Transport implementation](#transport-implementation)\n    - [Time source](#time-source)\n  - [Using the micro-ROS Agent](#using-the-micro-ros-agent)\n  - [Examples](#examples)\n  - [Purpose of the Project](#purpose-of-the-project)\n  - [License](#license)\n  - [Known Issues/Limitations](#known-issueslimitations)\n\n## Supported boards\nSupported boards are:\n\n| Board                                        | Platform      | Framework   | Transports                               | Default meta file        |\n| -------------------------------------------- | ------------- | ----------- | ---------------------------------------- | ------------------------ |\n| `portenta_h7_m7`                             | `ststm32`     | `arduino`   | `serial` \u003cbr/\u003e `wifi`                    | `colcon.meta`            |\n| `teensy41`                                   | `teensy`      | `arduino`   | `serial` \u003cbr/\u003e `native_ethernet`         | `colcon.meta`            |\n| `teensy40`                                   | `teensy`      | `arduino`   | `serial`                                 | `colcon.meta`            |\n| `teensy36` \u003cbr/\u003e `teensy35` \u003cbr/\u003e `teensy31` | `teensy`      | `arduino`   | `serial`                                 | `colcon_lowmem.meta`     |\n| `due`                                        | `atmelsam`    | `arduino`   | `serial`                                 | `colcon_verylowmem.meta` |\n| `zero`                                       | `atmelsam`    | `arduino`   | `serial`                                 | `colcon_verylowmem.meta` |\n| `olimex_e407`                                | `ststm32`     | `arduino`   | `serial`                                 | `colcon.meta`            |\n| `esp32dev`                                   | `espressif32` | `arduino`   | `serial` \u003cbr/\u003e `wifi` \u003cbr/\u003e `ethernet`*   | `colcon.meta`            |\n| `nanorp2040connect`                          | `raspberrypi` | `arduino`   | `serial` \u003cbr/\u003e `wifi_nina`               | `colcon_verylowmem.meta` |\n| `pico`                                       | `raspberrypi` | `arduino`   | `serial`                                 | `colcon.meta`            |\n\n\\* Community contributed\n\nThe community is encouraged to open pull request with custom use cases.\n\n## Requirements\n\n- PlatformIO [local installation](https://docs.platformio.org/en/stable/core/installation.html) or [PlatformIO IDE for VSCode](https://platformio.org/install/ide?install=vscode)\n- PlatformIO Core version 6.1.0 or greater\n- PlatformIO needs  `git`, `cmake` and `pip3` to handle micro-ROS internal dependencies:\n\n  ```bash\n  apt install -y git cmake python3-pip\n  ```\n  \n### Platform specific requirements\n\n#### MacOS\n\nXCode command line tools are distributed with toolchain that is not fully compatible with micro-ROS build process.\nTo fix this, install GNU [binutils](https://www.gnu.org/software/binutils/) using [Homebrew](https://brew.sh/):\n\n```bash\nbrew install binutils\n```\n\n## How to add to your project\n\nThe library can be included as a regular git library dependence on your `platform.ini` file:\n\n```ini\n...\nlib_deps =\n    https://github.com/micro-ROS/micro_ros_platformio\n```\n\nNow to proceed with the PlatformIO workflow:\n\n```bash\npio lib install # Install dependencies\npio run # Build the firmware\npio run --target upload # Flash the firmware\n```\n\nAfter 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:\n\n```bash\npio run --target clean_microros  # Clean library\n```\n\n## Library configuration\nThis section details the different configuration parameters available on the project `platform.ini` file.\nA explanation for adding custom targets is also present\n\n\n### ROS 2 distribution\nThe target ROS 2 distribution can be configured with the `board_microros_distro = \u003cdistribution\u003e`, supported values are:\n  - `humble`\n  - `iron`\n  - `jazzy` *(default value)*\n  - `kilted`\n  - `rolling`\n\n### Transport configuration\nThe transport can be configured with the `board_microros_transport = \u003ctransport\u003e`, supported values and configurations are:\n  - `serial` *(default value)*\n\n    ```c\n    Serial.begin(115200);\n    set_microros_serial_transports(Serial);\n    ```\n\n  - `wifi`\n  - `wifi_nina`\n\n    ```c\n    IPAddress agent_ip(192, 168, 1, 113);\n    size_t agent_port = 8888;\n\n    char ssid[] = \"WIFI_SSID\";\n    char psk[]= \"WIFI_PSK\";\n\n    set_microros_wifi_transports(ssid, psk, agent_ip, agent_port);\n    ```\n\n  - `native_ethernet`\n\n    ```c\n    byte local_mac[] = { 0xAA, 0xBB, 0xCC, 0xEE, 0xDD, 0xFF };\n    IPAddress local_ip(192, 168, 1, 177);\n    IPAddress agent_ip(192, 168, 1, 113);\n    size_t agent_port = 8888;\n\n    set_microros_native_ethernet_transports(local_mac, local_ip, agent_ip, agent_port);\n    ```\n\n  - `ethernet`\n\n    ```c\n    IPAddress client_ip(192, 168, 1, 177);\n    IPAddress gateway(192, 168, 1, 1);\n    IPAddress netmask(255, 255, 255, 0);\n    IPAddress agent_ip(192, 168, 1, 113);\n    size_t agent_port = 8888;\n\n    // Optional hostname, defaults to nullptr (no hostname set)\n    set_microros_ethernet_transports(client_ip, gateway, netmask, agent_ip, agent_port, \"my-microros-device\");\n    ```\n\n  - `custom`\n\n    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/)\n\n    ```c\n    bool platformio_transport_open(struct uxrCustomTransport * transport) {...};\n    bool platformio_transport_close(struct uxrCustomTransport * transport) {...};\n    size_t platformio_transport_write(struct uxrCustomTransport* transport, const uint8_t * buf, size_t len, uint8_t * err) {...};\n    size_t platformio_transport_read(struct uxrCustomTransport* transport, uint8_t* buf, size_t len, int timeout, uint8_t* err) {...};\n\n    rmw_uros_set_custom_transport(\n      MICROROS_TRANSPORTS_FRAMING_MODE, // Set the MICROROS_TRANSPORTS_FRAMING_MODE or MICROROS_TRANSPORTS_PACKET_MODE mode accordingly\n      NULL,\n      platformio_transport_open,\n      platformio_transport_close,\n      platformio_transport_write,\n      platformio_transport_read\n    );\n    ```\n\n### Extra packages\nColcon packages can be added to the build process using this two methods:\n- Package directories copied on the `\u003cProject_directory\u003e/extra_packages` folder.\n- Git repositories included on the `\u003cProject_directory\u003e/extra_packages/extra_packages.repos` yaml file.\n\nThis should be used for example when adding custom messages types or custom micro-ROS packages.\n\n### Other configuration\nLibrary packages can be configured with a customized meta file on the project main folder: `board_microros_user_meta = \u003cfile_name.meta\u003e`.\n\nThis allows the user to customize the library memory resources or activate optional functionality such as multithreading, including configuration of user [Extra packages](#extra-packages).\n\n- 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)).\n- Default configurations can be found on the [metas](./metas) folder.\n\n  *Note: the [common.meta](./metas/common.meta) file makes general adjustments to the library and shall not be modified by the user.*\n\n## Extend library targets\nThis library can be easily adapted to different boards, transports or RTOS, to achieve this the user shall provide:\n\n### Transport implementation\n\nNew 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/\u003cframework\u003e/\u003cboard_microros_transport\u003e` path. Example:\n\n- `platform.ini`:\n  ```ini\n  framework = arduino\n  board_microros_transport = wifi\n  ```\n- Transport source files: [platform_code/arduino/wifi](https://github.com/micro-ROS/micro_ros_platformio/tree/main/platform_code/arduino/wifi)\n- Also, a `MICRO_ROS_TRANSPORT_\u003cFRAMEWORK\u003e_\u003cTRANSPORT\u003e` definition will be available:\n  https://github.com/micro-ROS/micro_ros_platformio/blob/de7a61c7e86fdd0186ed8b7d8ec320994e8ebcbf/ci/src/main.cpp#L3\n\n  *Note: `board_microros_transport = custom` should not be used, as it is used to add custom transports on user app code*\n\n### Time source\nmicro-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.\n\nThis method shall be included on a `clock_gettime.cpp` source file under the `./platform_code/\u003cframework\u003e/` path, an example implementation can be found on [clock_gettime.cpp](./platform_code/arduino/clock_gettime.cpp)\n\n## Using the micro-ROS Agent\nIt is possible to use a **micro-ROS Agent** just by using this docker command:\n\n```bash\n# UDPv4 micro-ROS Agent\ndocker run -it --rm -v /dev:/dev -v /dev/shm:/dev/shm --privileged --net=host microros/micro-ros-agent:$ROS_DISTRO udp4 --port 8888 -v6\n\n# Serial micro-ROS Agent\ndocker 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\n\n# TCPv4 micro-ROS Agent\ndocker run -it --rm -v /dev:/dev -v /dev/shm:/dev/shm --privileged --net=host microros/micro-ros-agent:$ROS_DISTRO tcp4 --port 8888 -v6\n\n# CAN-FD micro-ROS Agent\ndocker 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\n```\n\nFor the supported transports, only the `serial` and `udp4` versions shall be used, although users can develop\nand use the agent to test their own `tcp4` and `canfd` custom transports.\n\nIt 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).\n\n## Examples\nA simple publisher project using serial transport is available on the [examples](./examples) directory, this examples is meant to be modified with the user board.\n\n- More micro-ROS usage examples are available on [micro-ROS-demos/rclc](https://github.com/micro-ROS/micro-ROS-demos/tree/jazzy/rclc).\n- For a complete micro-ROS tutorial, check [Programming with rcl and rclc](https://micro.ros.org/docs/tutorials/programming_rcl_rclc/overview/) documentation.\n\n## Purpose of the Project\n\nThis software is not ready for production use. It has neither been developed nor\ntested for a specific use case. However, the license conditions of the\napplicable Open Source licenses allow you to adapt the software to your needs.\nBefore using it in a safety relevant setting, make sure that the software\nfulfills your requirements and adjust it according to any applicable safety\nstandards, e.g., ISO 26262.\n\n## License\n\nThis repository is open-sourced under the Apache-2.0 license. See the [LICENSE](LICENSE) file for details.\n\nFor a list of other open-source components included in this repository,\nsee the file [3rd-party-licenses.txt](3rd-party-licenses.txt).\n\n## Known Issues/Limitations\n\n- For `wifi_nina` transport, the following versioning shall be used:\n\n    ```ini\n    lib_deps =\n      arduino-libraries/WiFiNINA@^1.8.13\n    ```\n\n- For `nanorp2040connect` board with `serial` transport, the library dependency finder shall be set to `chain+`:\n\n    ```ini\n    lib_ldf_mode = chain+\n    ```\n- For `pico` board with `serial` transport, the library dependency finder shall be set to `chain+`:\n\n    ```ini\n    lib_ldf_mode = chain+\n    ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicro-ros%2Fmicro_ros_platformio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicro-ros%2Fmicro_ros_platformio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicro-ros%2Fmicro_ros_platformio/lists"}