Skip to content

Commit 305a2b5

Browse files
pablogs9jamoralpFranFinralph-lange
authored
Adding build systems section (#244)
* Initial * Update _docs/concepts/build_system/index.md Co-authored-by: Jose Antonio Moral <joseantoniomoralparras@gmail.com> * Update _docs/concepts/build_system/index.md Co-authored-by: Jose Antonio Moral <joseantoniomoralparras@gmail.com> * Update _docs/concepts/build_system/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> * Update _docs/concepts/build_system/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> * Update _docs/concepts/build_system/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> * Update _docs/concepts/build_system/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> * Update _docs/concepts/build_system/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> * Update _docs/concepts/build_system/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> * Update _docs/concepts/build_system/external_build_systems/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> * Update _docs/concepts/build_system/external_build_systems/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> * Update _docs/concepts/build_system/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> * Update _docs/concepts/build_system/external_build_systems/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> * Update _docs/concepts/build_system/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> * Update _docs/concepts/build_system/index.md Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> * Update * Updates * Update _docs/concepts/build_system/external_build_systems/index.md Co-authored-by: Ralph Lange <ralph-lange@users.noreply.github.com> * Update _docs/concepts/build_system/external_build_systems/index.md Co-authored-by: Ralph Lange <ralph-lange@users.noreply.github.com> * Update _docs/concepts/build_system/external_build_systems/index.md Co-authored-by: Ralph Lange <ralph-lange@users.noreply.github.com> * Update _docs/concepts/build_system/external_build_systems/index.md Co-authored-by: Ralph Lange <ralph-lange@users.noreply.github.com> * Update _docs/concepts/build_system/index.md Co-authored-by: Ralph Lange <ralph-lange@users.noreply.github.com> * Update _docs/concepts/build_system/index.md Co-authored-by: Ralph Lange <ralph-lange@users.noreply.github.com> * Update _docs/concepts/build_system/index.md Co-authored-by: Ralph Lange <ralph-lange@users.noreply.github.com> * Update _docs/concepts/build_system/index.md Co-authored-by: Ralph Lange <ralph-lange@users.noreply.github.com> * Refer to tutorial section * Update _docs/concepts/build_system/index.md Co-authored-by: Ralph Lange <ralph-lange@users.noreply.github.com> * Update _docs/concepts/build_system/index.md Co-authored-by: Ralph Lange <ralph-lange@users.noreply.github.com> * Update _docs/concepts/build_system/index.md Co-authored-by: Ralph Lange <ralph-lange@users.noreply.github.com> Co-authored-by: Jose Antonio Moral <joseantoniomoralparras@gmail.com> Co-authored-by: FranFin <58737168+FranFin@users.noreply.github.com> Co-authored-by: Ralph Lange <ralph-lange@users.noreply.github.com>
1 parent c0babd8 commit 305a2b5

6 files changed

Lines changed: 102 additions & 10 deletions

File tree

‎_data/docs.yml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,11 @@
3131
- concepts/rtos/NuttX
3232
- concepts/rtos/Zephyr
3333
- concepts/rtos/comparison
34-
- concepts/rtos/integration_with_colcon
34+
35+
- title: Build System
36+
docs:
37+
- concepts/build_system
38+
- concepts/build_system/external_build_systems
3539

3640
- title: Benchmarking
3741
docs:

‎_docs/concepts/build_system/external_build_systems/index.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: External Build Systems
3+
permalink: /docs/concepts/build_system/external_build_systems/
4+
---
5+
6+
Once you have read about the official [**micro_ros_setup** tool](/docs/concepts/build_system/), this page will present some other approaches for building micro-ROS as a module or component integrated into other build systems.
7+
8+
## micro-ROS component for ESP-IDF
9+
10+
The [micro-ROS component for ESP-IDF](https://github.com/micro-ROS/micro_ros_espidf_component) allows to integrate micro-ROS as a component in an Espressif ESP-IDF Build System. This component allows the user to integrate the micro-ROS API and utilities in an already created ESP-IDF project just by cloning or copying a folder.
11+
12+
Configuration of the micro-ROS library is based on the `colcon.meta` file. For more details visit the [Git repository](https://github.com/micro-ROS/micro_ros_espidf_component).
13+
14+
## micro-ROS module for Zephyr
15+
16+
The [micro-ROS module for Zephyr](https://github.com/micro-ROS/micro_ros_zephyr_module) allows to integrate micro-ROS as a module in a Zephyr-based project. In detail, it enables to integrate the micro-ROS API and utilities in an existing Zephyr project just by cloning or copying a folder.
17+
18+
The procedure for configuring the built micro-ROS library is based in `colcon.meta`. For more details visit the [Git repository](https://github.com/micro-ROS/micro_ros_espidf_component).
19+
20+
## micro-ROS for Arduino
21+
22+
The [micro-ROS for Arduino](https://github.com/micro-ROS/micro_ros_arduino) support package is a special port of micro-ROS provided as a set of precompiled libraries for specific platforms. The main reason for this approach is that Arduino does not allow the build of a complex library such as micro-ROS, so by using this approach a ready-to-use solution is provided to the Arduino users.
23+
24+
Along with this support package, there are [detailed instructions](https://github.com/micro-ROS/micro_ros_arduino#how-to-build-the-precompiled-library) for rebuilding the micro-ROS for Arduino libraries for users that need to tune the default configuration.

‎_docs/concepts/build_system/index.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
title: micro-ROS Build System
3+
permalink: /docs/concepts/build_system/
4+
---
5+
6+
micro-ROS provides two ways of building a micro-ROS application for embedded platforms:
7+
- _micro_ros_setup:_ integrates and hides the RTOS-specific build tools in few scripts provided as a ROS 2 package.
8+
_RTOS-specific integrations:_ We have integrated micro-ROS with several RTOS build tools. Click [here](/docs/concepts/build_system/external_build_systems/) to learn more.
9+
10+
**micro_ros_setup** provides a standalone build system in the form of a ROS 2 package for use in any normal ROS 2 workspace. This tool is available in the [micro-ROS/micro_ros_setup](https://github.com/micro-ROS/micro_ros_setup) repository.
11+
12+
The **micro_ros_setup** tool allows compiling and generating images that contain micro-ROS apps for the [supported hardware](/docs/overview/hardware/) boards and [RTOSes](/docs/concepts/rtos/).
13+
14+
As the **micro_ros_setup** package can be installed like any other ROS 2 package, its usage will be through the ROS 2 CLI tool. Compiling, generating an image and flashing it on a board can be done just with four ROS 2 commands. A detailed description about the usage of this package can be found in the [tutorial section](/docs/tutorials/core/first_application_rtos/).
15+
16+
### micro-ROS client
17+
18+
Once installed, the build system tool provides some utilities that can be used in order to prepare, build, flash and use a micro-ROS application. The micro-ROS build system is a four-step procedure. In the first step, the user can create a new micro-ROS application by configuring the target hardware and RTOS:
19+
20+
```bash
21+
# Create step
22+
ros2 run micro_ros_setup create_firmware_ws.sh [RTOS] [HARDWARE BOARD]
23+
```
24+
25+
It is possible to obtain a list of the supported hardware by running the command without any argument. By doing so, it is possible to see that along with the RTOSes and hardware supported by micro-ROS this build system also provides with three extra options:
26+
- By using `zephyr` as RTOS and `host` as hardware name, it is possible to obtain a Zephyr RTOS image with your micro-ROS app that runs in your host computer.
27+
- By using just `host` as RTOS, micro-ROS will build a set of [micro-ROS demo applications](https://github.com/micro-ROS/micro-ROS-demos) natively in your host machine. These applications behave just like micro-ROS apps (using the same abstraction layers and middleware implementation) and allow the user to debug and test the applications on a PC.
28+
- By using `generate_lib` as RTOS it is possible to configure the build system for generating static libraries (`.a`) and a set of headers (`include`) that can be linked in any other external tool. This option requires a valid CMake toolchain.
29+
30+
Once the build system has created the new firmware project, it is possible to configure it using:
31+
32+
```bash
33+
# Configure step
34+
ros2 run micro_ros_setup configure_firmware.sh [APP] [OPTIONS]
35+
```
36+
37+
By running this command without any argument, it will output a list of example applications valid for the selected RTOS.
38+
Common options available at this configuration step are:
39+
- `--transport` or `-t`: `udp`, `serial` or any hardware specific transport label
40+
- `--dev` or `-d`: agent string descriptor in a serial-like transport
41+
- `--ip` or `-i`: agent IP in a network-like transport
42+
- `--port` or `-p`: agent port in a network-like transport
43+
44+
45+
Finally, it is possible to build and flash a micro-ROS app using:
46+
47+
```bash
48+
# Build step
49+
ros2 run micro_ros_setup build_firmware.sh
50+
51+
# Flash step
52+
ros2 run micro_ros_setup flash_firmware.sh
53+
```
54+
55+
### micro-ROS agent
56+
57+
The micro-ROS build system is also able to ease the compilation of the micro-ROS Agent in a ROS 2 workspace by using these commands:
58+
59+
```bash
60+
# Download micro-ROS-Agent packages
61+
ros2 run micro_ros_setup create_agent_ws.sh
62+
ros2 run micro_ros_setup build_agent.sh
63+
source install/local_setup.bash
64+
ros2 run micro_ros_agent micro_ros_agent [OPTIONS]
65+
```
66+
67+
**Tip 1:** To learn use of the micro_ros_setup build system hands-on, please see the [core tutorials](https://micro-ros.github.io/docs/tutorials/core/first_application_rtos/).
68+
69+
**Tip 2 :** Remember that the micro-ROS Agent can be also be used with this simple Docker command: `docker run -it --rm -v /dev:/dev --privileged --net=host microros/micro-ros-agent:foxy [OPTIONS]`

‎_docs/concepts/rtos/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,4 +21,4 @@ By now, micro-ROS supports three RTOSes, which all come with (basic) POSIX imple
2121
* [NuttX](NuttX/)
2222
* [Zephyr](Zephyr/)
2323

24-
Most important, we [integrated these RTOSes with the ROS meta build system colcon](integration_with_colcon/).
24+
Most important, we [integrated these RTOSes with the micro-ROS build system](/docs/concepts/build_system/).

‎_docs/concepts/rtos/integration_with_colcon/index.md‎

Lines changed: 0 additions & 8 deletions
This file was deleted.

‎_includes/docs_nav.html‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@
1313
{% if page.path contains "_docs/concepts" and section.title == "RTOS" %}
1414
{% assign should_show_this_menu = true %}
1515
{% endif %}
16+
{% if page.path contains "_docs/concepts" and section.title == "Build System" %}
17+
{% assign should_show_this_menu = true %}
18+
{% endif %}
1619
{% if page.path contains "_docs/concepts" and section.title == "Benchmarking" %}
1720
{% assign should_show_this_menu = true %}
1821
{% endif %}

0 commit comments

Comments
 (0)