diff --git a/_data/docs.yml b/_data/docs.yml index 3a01bfc6..fac683d5 100644 --- a/_data/docs.yml +++ b/_data/docs.yml @@ -31,7 +31,11 @@ - concepts/rtos/NuttX - concepts/rtos/Zephyr - concepts/rtos/comparison - - concepts/rtos/integration_with_colcon + +- title: Build System + docs: + - concepts/build_system + - concepts/build_system/external_build_systems - title: Benchmarking docs: diff --git a/_docs/concepts/build_system/external_build_systems/index.md b/_docs/concepts/build_system/external_build_systems/index.md new file mode 100644 index 00000000..3e576676 --- /dev/null +++ b/_docs/concepts/build_system/external_build_systems/index.md @@ -0,0 +1,24 @@ +--- +title: External Build Systems +permalink: /docs/concepts/build_system/external_build_systems/ +--- + +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. + +## micro-ROS component for ESP-IDF + +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. + +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). + +## micro-ROS module for Zephyr + +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. + +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). + +## micro-ROS for Arduino + +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. + +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. diff --git a/_docs/concepts/build_system/index.md b/_docs/concepts/build_system/index.md new file mode 100644 index 00000000..5ef6fdba --- /dev/null +++ b/_docs/concepts/build_system/index.md @@ -0,0 +1,69 @@ +--- +title: micro-ROS Build System +permalink: /docs/concepts/build_system/ +--- + +micro-ROS provides two ways of building a micro-ROS application for embedded platforms: +- _micro_ros_setup:_ integrates and hides the RTOS-specific build tools in few scripts provided as a ROS 2 package. +_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. + +**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. + +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/). + +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/). + +### micro-ROS client + +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: + +```bash +# Create step +ros2 run micro_ros_setup create_firmware_ws.sh [RTOS] [HARDWARE BOARD] +``` + +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: +- 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. +- 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. +- 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. + +Once the build system has created the new firmware project, it is possible to configure it using: + +```bash +# Configure step +ros2 run micro_ros_setup configure_firmware.sh [APP] [OPTIONS] +``` + +By running this command without any argument, it will output a list of example applications valid for the selected RTOS. +Common options available at this configuration step are: + - `--transport` or `-t`: `udp`, `serial` or any hardware specific transport label + - `--dev` or `-d`: agent string descriptor in a serial-like transport + - `--ip` or `-i`: agent IP in a network-like transport + - `--port` or `-p`: agent port in a network-like transport + + +Finally, it is possible to build and flash a micro-ROS app using: + +```bash +# Build step +ros2 run micro_ros_setup build_firmware.sh + +# Flash step +ros2 run micro_ros_setup flash_firmware.sh +``` + +### micro-ROS agent + +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: + +```bash +# Download micro-ROS-Agent packages +ros2 run micro_ros_setup create_agent_ws.sh +ros2 run micro_ros_setup build_agent.sh +source install/local_setup.bash +ros2 run micro_ros_agent micro_ros_agent [OPTIONS] +``` + +**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/). + +**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]` diff --git a/_docs/concepts/rtos/index.md b/_docs/concepts/rtos/index.md index e69ee629..459d8818 100644 --- a/_docs/concepts/rtos/index.md +++ b/_docs/concepts/rtos/index.md @@ -21,4 +21,4 @@ By now, micro-ROS supports three RTOSes, which all come with (basic) POSIX imple * [NuttX](NuttX/) * [Zephyr](Zephyr/) -Most important, we [integrated these RTOSes with the ROS meta build system colcon](integration_with_colcon/). \ No newline at end of file +Most important, we [integrated these RTOSes with the micro-ROS build system](/docs/concepts/build_system/). \ No newline at end of file diff --git a/_docs/concepts/rtos/integration_with_colcon/index.md b/_docs/concepts/rtos/integration_with_colcon/index.md deleted file mode 100644 index e1cf7d76..00000000 --- a/_docs/concepts/rtos/integration_with_colcon/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Integration with colcon -permalink: /docs/concepts/rtos/integration_with_colcon/ ---- - -In order to streamline the use of different RTOSes with micro-ROS, we integrated the build systems of [FreeRTOS](../FreeRTOS/), [NuttX](../NuttX/), and [Zephyr](../Zephyr/) with the ROS 2 meta-build tool [colcon](https://colcon.readthedocs.io/) using [cmake](https://cmake.org/). - -To learn more, please see [https://github.com/micro-ROS/micro_ros_setup](https://github.com/micro-ROS/micro_ros_setup). \ No newline at end of file diff --git a/_includes/docs_nav.html b/_includes/docs_nav.html index f4821b47..24b8d5e1 100644 --- a/_includes/docs_nav.html +++ b/_includes/docs_nav.html @@ -13,6 +13,9 @@ {% if page.path contains "_docs/concepts" and section.title == "RTOS" %} {% assign should_show_this_menu = true %} {% endif %} + {% if page.path contains "_docs/concepts" and section.title == "Build System" %} + {% assign should_show_this_menu = true %} + {% endif %} {% if page.path contains "_docs/concepts" and section.title == "Benchmarking" %} {% assign should_show_this_menu = true %} {% endif %}