|
1 | | -<br/> |
2 | | - |
3 | | -<a> |
4 | | - <p align="center"> |
5 | | - <img width="20%" src=".images/arduino_logo.png"> |
6 | | - <img width="40%" src=".images/microros_logo.png"> |
7 | | - </p> |
8 | | -</a> |
9 | | -<br/> |
10 | | - |
11 | | -# micro-ROS for Arduino |
12 | | - |
13 | | -This is a micro-ROS library for baremetal projects based on Arduino IDE or Arduino CLI. |
14 | | - |
15 | | -As the build process for ROS 2 and micro-ROS is based on custom meta-build system tools and [CMake](https://cmake.org/), this library is provided as a precompiled library. However, users can rebuild their own precompiled libraries in order to modify the micro-ROS configuration or [RMW parameters](https://micro.ros.org/docs/tutorials/advanced/microxrcedds_rmw_configuration/) by customizing the respective [.meta file](https://github.com/micro-ROS/micro_ros_arduino/tree/main/extras/library_generation). |
16 | | - |
17 | | -- [micro-ROS for Arduino](#micro-ros-for-arduino) |
18 | | - - [Supported boards](#supported-boards) |
19 | | - - [How to use the precompiled library](#how-to-use-the-precompiled-library) |
20 | | - - [Arduino IDE](#arduino-ide) |
21 | | - - [PlatformIO](#platformio) |
22 | | - - [Known issues](#known-issues) |
23 | | - - [How to build the precompiled library](#how-to-build-the-precompiled-library) |
24 | | - - [Patch Arduino board for support precompiled libraries](#patch-arduino-board-for-support-precompiled-libraries) |
25 | | - - [Patch Teensyduino](#patch-teensyduino) |
26 | | - - [Patch SAMD](#patch-samd) |
27 | | - - [Purpose of the Project](#purpose-of-the-project) |
28 | | - - [License](#license) |
29 | | - - [Known Issues/Limitations](#known-issueslimitations) |
30 | | - |
31 | | -## Supported boards |
32 | | - |
33 | | -Supported boards are: |
34 | | - |
35 | | -| Board | Min version | State | Details | .meta file | |
36 | | -| ----------------------------------------------------------------------------------- | ----------- | ---------- | --------------------------------------------------------------------------------------------------- | ------------------------ | |
37 | | -| [Arduino Portenta H7 M7 Core](https://store.arduino.cc/portenta-h7) | v1.8.5 | Supported | Official Arduino support | `colcon.meta` | |
38 | | -| [Arduino Nano RP2040 Connect](https://docs.arduino.cc/hardware/nano-rp2040-connect) | v1.8.5 | Supported | Official Arduino support | `colcon_verylowmem.meta` | |
39 | | -| [OpenCR](https://emanual.robotis.com/docs/en/parts/controller/opencr10/) | v1.4.19 | Supported | [Based on custom board](https://emanual.robotis.com/docs/en/parts/controller/opencr10/#arduino-ide) | `colcon.meta` | |
40 | | -| [Teensy 4.0](https://www.pjrc.com/store/teensy40.html) | v1.8.5 | Not tested | [Based on Teensyduino](https://www.pjrc.com/teensy/td_download.html) | `colcon.meta` | |
41 | | -| [Teensy 4.1](https://www.pjrc.com/store/teensy41.html) | v1.8.5 | Supported | [Based on Teensyduino](https://www.pjrc.com/teensy/td_download.html) | `colcon.meta` | |
42 | | -| [Teensy 3.2/3.1](https://www.pjrc.com/store/teensy32.html) | v1.8.5 | Supported | [Based on Teensyduino](https://www.pjrc.com/teensy/td_download.html) | `colcon_lowmem.meta` | |
43 | | -| [Teensy 3.5](https://www.pjrc.com/store/teensy35.html) | v1.8.5 | Not tested | [Based on Teensyduino](https://www.pjrc.com/teensy/td_download.html) | `colcon_lowmem.meta` | |
44 | | -| [Teensy 3.6](https://www.pjrc.com/store/teensy36.html) | v1.8.5 | Supported | [Based on Teensyduino](https://www.pjrc.com/teensy/td_download.html) | `colcon_lowmem.meta` | |
45 | | -| [ESP32 Dev Module](https://docs.espressif.com/projects/arduino-esp32/en/latest/boards/ESP32-DevKitC-1.html) | v1.8.5 | Supported | [Arduino core for the ESP32 (v2.0.2)](https://github.com/espressif/arduino-esp32/releases/tag/2.0.2) | `colcon.meta` | |
46 | | - |
47 | | -Community contributed boards are: |
48 | | - |
49 | | -| Board | Min version | Contributor | Details | .meta file | |
50 | | -| ---------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------- | ------- | ------------------------ | |
51 | | -| [Arduino Due](https://store.arduino.cc/arduino-due) | - | [@lukicdarkoo](https://github.com/lukicdarkoo) | | `colcon_verylowmem.meta` | |
52 | | -| [Arduino Zero](https://store.arduino.cc/arduino-zero) | - | [@lukicdarkoo](https://github.com/lukicdarkoo) | | `colcon_verylowmem.meta` | |
53 | | -| [Kakute F7](http://www.holybro.com/product/kakute-f7-aio-v1-5/) | - | [@amfern](https://github.com/amfern) | | `colcon.meta` | |
54 | | -| [STM32-E407](https://www.olimex.com/Products/ARM/ST/STM32-E407/resources/STM32-E407.pdf) | - | [@dominikn](https://github.com/dominikn) | | `colcon.meta` | |
55 | | - |
56 | | -You can find the available precompiled ROS 2 types for messages and services in [available_ros2_types](available_ros2_types). |
57 | | - |
58 | | -## How to use the precompiled library |
59 | | - |
60 | | -### Arduino IDE |
61 | | - |
62 | | -Go to [link to release section](https://github.com/micro-ROS/micro_ros_arduino/releases) and download the last release of micro-ROS library for Arduino. |
63 | | - |
64 | | -Include it in your project using `Sketch -> Include library -> Add .ZIP Library...` |
65 | | - |
66 | | -You can test micro-ROS examples located in this repo examples folder. |
67 | | - |
68 | | -Remember that is possible to use a micro-ROS Agent just with this docker command: |
69 | | - |
70 | | -```bash |
71 | | -# Serial micro-ROS Agent |
72 | | -docker run -it --rm -v /dev:/dev --privileged --net=host microros/micro-ros-agent:galactic serial --dev [YOUR BOARD PORT] -v6 |
73 | | -``` |
74 | | -### PlatformIO |
75 | | - |
76 | | -For boards supported by micro-ROS, all you have to do to add the library to your project is including the following lines in the existing `platformio.ini` file: |
77 | | - |
78 | | -```ini |
79 | | -[env:<YOUR_BOARD>] |
80 | | - |
81 | | -... |
82 | | -lib_deps = |
83 | | - https://github.com/micro-ROS/micro_ros_arduino |
84 | | - |
85 | | -build_flags = |
86 | | - -L ./.pio/libdeps/<YOUR_BOARD>/micro_ros_arduino/src/<BOARD_ARCHITECTURE>/ |
87 | | - -l microros |
88 | | - -D <TARGET_DEFINITION> |
89 | | -``` |
90 | | - |
91 | | -| Board | <YOUR_BOARD> | <BOARD_ARCHITECTURE> | <TARGET_DEFINITION> | |
92 | | -| ----------------------------| ------------------- | ---------------------------- | ----------------------------------- | |
93 | | -| Arduino Portenta H7 M7 Core | portenta_h7_m7 | cortex-m7/fpv5-d16-softfp | TARGET_PORTENTA_H7_M7 | |
94 | | -| Arduino Nano RP2040 Connect | nanorp2040connect | cortex-m0plus | ARDUINO_NANO_RP2040_CONNECT | |
95 | | -| Teensy 4.1/4.0 | teensy41 / teensy40 | imxrt1062/fpv5-d16-hard | ARDUINO_TEENSY41 | |
96 | | -| Teensy 3.6 | teensy36 | mk66fx1m0/fpv4-sp-d16-hard | ARDUINO_TEENSY36 | |
97 | | -| Teensy 3.5 | teensy35 | mk64fx512/fpv4-sp-d16-hard | ARDUINO_TEENSY35 | |
98 | | -| Teensy 3.2 / 3.1 | teensy31 | mk20dx256 | ARDUINO_TEENSY32 / ARDUINO_TEENSY31 | |
99 | | -| ESP32 Dev Module | esp32dev | esp32 | ESP32 | |
100 | | -| STM32-E407 | olimex_e407 | cortex-m4 | TARGET_STM32F4 | |
101 | | -| Arduino Due | due | cortex-m3 | - | |
102 | | -| Arduino Zero | zero | cortex-m0plus | - | |
103 | | - |
104 | | -Now to proceed with the PlatformIO workflow: |
105 | | - |
106 | | -```bash |
107 | | -pio lib install # Install dependencies |
108 | | -pio run # Build the firmware |
109 | | -pio run --target upload # Flash the firmware |
110 | | -``` |
111 | | - |
112 | | -An example of a micro-ROS application using PlatformIO is available [here](https://github.com/husarion/micro_ros_stm32_template). |
113 | | - |
114 | | -#### Known issues |
115 | | - |
116 | | -- `multiple definition of` Link errors on galactic: |
117 | | - |
118 | | - Create a python script fix_linker.py on your directory and modify the linker flags manually: |
119 | | - ``` |
120 | | - Import("env") |
121 | | - env["_LIBFLAGS"] = ('-Wl,--start-group -Wl,--whole-archive ' |
122 | | - '${_stripixes(LIBLINKPREFIX, LIBS, LIBLINKSUFFIX, LIBPREFIXES, ' |
123 | | - 'LIBSUFFIXES, __env__)} -Wl,--no-whole-archive -lstdc++ ' |
124 | | - '-lsupc++ -lm -lc -lgcc -lnosys -lmicroros -Wl,--end-group') |
125 | | - ``` |
126 | | - |
127 | | - Now add it to your `platformio.ini` like this: `extra_scripts = fix_linker.py` and delete the `-l libmicroros` line on `build_flags`. |
128 | | - |
129 | | - Related: https://github.com/micro-ROS/micro_ros_arduino/pull/848#issuecomment-1072196933, https://github.com/micro-ROS/micro_ros_arduino/issues/774 |
130 | | - |
131 | | -- Arduino Portenta H7 |
132 | | - - Follow **`multiple definition of` Link errors on galactic** modifications |
133 | | - |
134 | | - Related: https://github.com/micro-ROS/micro_ros_arduino/issues/847 |
135 | | - |
136 | | -- Arduino Nano RP2040 Connect |
137 | | - |
138 | | - - The following versioning shall be used: |
139 | | - ``` |
140 | | - lib_deps = |
141 | | - arduino-libraries/WiFiNINA@^1.8.13 |
142 | | - ... |
143 | | -
|
144 | | - platform_packages = |
145 | | - toolchain-gccarmnoneeabi @ ~1.70201.0 |
146 | | - framework-arduino-mbed @ ~2.4.1 |
147 | | - ``` |
148 | | -
|
149 | | - - Library dependency finder shall be set to `chain+`: `lib_ldf_mode = chain+` |
150 | | - - Follow **`multiple definition of` Link errors on galactic** modifications |
151 | | -
|
152 | | - Related: https://github.com/micro-ROS/micro_ros_arduino/issues/780 |
153 | | -
|
154 | | -- Arduino Due |
155 | | - - The following versioning shall be used: |
156 | | - ``` |
157 | | - platform_packages = |
158 | | - toolchain-gccarmnoneeabi@<1.50000.0 |
159 | | - ``` |
160 | | -
|
161 | | - Related: https://github.com/micro-ROS/micro_ros_arduino/issues/698 |
162 | | -
|
163 | | -- ESP32 Dev Module |
164 | | - - Known issues with espressif32 arduino package, use `2.0.2` version: |
165 | | - ``` |
166 | | - [env:esp32dev] |
167 | | - platform = https://github.com/platformio/platform-espressif32.git#feature/arduino-upstream |
168 | | - board = esp32dev |
169 | | - framework = arduino |
170 | | - lib_deps = |
171 | | - https://github.com/micro-ROS/micro_ros_arduino.git |
172 | | - build_flags = |
173 | | - -L ./.pio/libdeps/esp32dev/micro_ros_arduino/src/esp32/ |
174 | | - -l microros |
175 | | - -D ESP32 |
176 | | -
|
177 | | - platform_packages = |
178 | | - toolchain-xtensa32 @ ~2.80400.0 |
179 | | - framework-arduinoespressif32@https://github.com/espressif/arduino-esp32.git#2.0.2 |
180 | | - ``` |
181 | | -
|
182 | | - Related: https://github.com/micro-ROS/micro_ros_arduino/issues/736, https://github.com/platformio/platform-espressif32/issues/616 |
183 | | -
|
184 | | -## How to build the precompiled library |
185 | | -
|
186 | | -If you need to add custom packages or types, or customize any internal parameter of the micro-ROS stack, you will need to recompile this library from source code: |
187 | | -
|
188 | | -```bash |
189 | | -docker pull microros/micro_ros_static_library_builder:galactic |
190 | | -docker run -it --rm -v $(pwd):/project --env MICROROS_LIBRARY_FOLDER=extras microros/micro_ros_static_library_builder:galactic |
191 | | -``` |
192 | | - |
193 | | -Optionally a specific single target can be built using the `-p <LIBRARY_TARGET>` argument like this: |
194 | | - |
195 | | -```bash |
196 | | -docker run -it --rm -v $(pwd):/project --env MICROROS_LIBRARY_FOLDER=extras microros/micro_ros_static_library_builder:galactic -p <LIBRARY_TARGET> |
197 | | -``` |
198 | | - |
199 | | -Available targets `LIBRARY_TARGETS` are available on the [top of the extras/library_generation/library_generation.sh file](https://github.com/micro-ROS/micro_ros_arduino/blob/main/extras/library_generation/library_generation.sh#L13-L24) |
200 | | - |
201 | | -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. |
202 | | -This should be used for example when adding custom messages types or custom micro-ROS packages. |
203 | | - |
204 | | -You can [configure many parameters](https://micro.ros.org/docs/tutorials/advanced/microxrcedds_rmw_configuration/) of the library by editing the respective `.meta` file in the `extras/library_generation/` directory. |
205 | | - |
206 | | -## Patch Arduino board for support precompiled libraries |
207 | | -### Patch Teensyduino |
208 | | - |
209 | | -Go inside your Arduino + Teensyduino installation and replace `platform.txt`: |
210 | | - |
211 | | -```bash |
212 | | -export ARDUINO_PATH=[Your Arduino + Teensiduino path] |
213 | | -cd $ARDUINO_PATH/hardware/teensy/avr/ |
214 | | -curl https://raw.githubusercontent.com/micro-ROS/micro_ros_arduino/galactic/extras/patching_boards/platform_teensy.txt > platform.txt |
215 | | -``` |
216 | | - |
217 | | -### Patch SAMD |
218 | | - |
219 | | -Go inside your Arduino + Teensyduino installation and replace `platform.txt`: |
220 | | - |
221 | | -```bash |
222 | | -export ARDUINO_PATH=[Your Arduino path] |
223 | | -cd $ARDUINO_PATH/hardware/sam/1.6.12/ |
224 | | -curl https://raw.githubusercontent.com/micro-ROS/micro_ros_arduino/galactic/extras/patching_boards/platform_arduinocore_sam.txt > platform.txt |
225 | | -``` |
226 | | - |
227 | | -## Purpose of the Project |
228 | | - |
229 | | -This software is not ready for production use. It has neither been developed nor |
230 | | -tested for a specific use case. However, the license conditions of the |
231 | | -applicable Open Source licenses allow you to adapt the software to your needs. |
232 | | -Before using it in a safety relevant setting, make sure that the software |
233 | | -fulfills your requirements and adjust it according to any applicable safety |
234 | | -standards, e.g., ISO 26262. |
235 | | - |
236 | | -## License |
237 | | - |
238 | | -This repository is open-sourced under the Apache-2.0 license. See the [LICENSE](LICENSE) file for details. |
239 | | - |
240 | | -For a list of other open-source components included in this repository, |
241 | | -see the file [3rd-party-licenses.txt](3rd-party-licenses.txt). |
242 | | - |
243 | | -## Known Issues/Limitations |
244 | | - |
245 | | -- When using provided precompiled libraries, users should take into account the already configured static memory pools in middleware layers. [More info here](https://micro.ros.org/docs/tutorials/advanced/microxrcedds_rmw_configuration/). |
246 | | -- micro-ROS transports should be refactored in order to provide a pluggable mechanisms. Only USB serial transports are provided. |
247 | | -- Teensyduino support files have to be patched in order to use precompiled libraries. |
248 | | -- To solve Python errors on ESP32 compilation: `apt install python-is-python3 && pip3 install pyserial` |
| 1 | +To be done |
0 commit comments