Skip to content

Commit d3faace

Browse files
FranFinFranFin
committed
Reworking tutorials common sections.
1 parent f125f50 commit d3faace

6 files changed

Lines changed: 323 additions & 39 deletions

File tree

‎_docs/tutorials/advanced/zephyr_emulator/index.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Zephyr Emulator
33
permalink: /docs/tutorials/advanced/zephyr_emulator/
44
---
55

6-
This tutorial aims at creating a new micro-ROS application on with **[Zephyr RTOS](https://www.zephyrproject.org/)** emulator (also known as [Native POSIX](https://docs.zephyrproject.org/latest/boards/posix/native_posix/doc/index.html)).
6+
This tutorial aims at creating a new micro-ROS application on with **[Zephyr RTOS](https://www.zephyrproject.org/)** emulator (also known as [Native POSIX](https://docs.zephyrproject.org/latest/boards/posix/native_posix/doc/index.html)).
77

88
To follow this tutorial, it is assumed that the user is already familiar with the **[First micro-ROS Application on an RTOS](https://micro-ros.github.io/docs/tutorials/core/first_application_rtos/)** tutorial. The target app in this tutorial is the same ping pong app.
99
Another requirement is that the user has a basic knowledge of micro-ROS and ROS 2.
@@ -34,7 +34,7 @@ mkdir host_ping_pong
3434
cd host_ping_pong
3535
mkdir src
3636

37-
touch src/app.c
37+
touch src/app.c
3838
touch app-colcon.meta
3939
touch CMakeLists.txt
4040
touch prj.conf
@@ -82,7 +82,7 @@ Then run the agent:
8282
ros2 run micro_ros_agent micro_ros_agent udp4 --port 8888
8383
```
8484

85-
And run the Zephyr app in another command line (remember sourcing ROS 2 and micro-ROS installation):
85+
And run the Zephyr app in another command line (remember sourcing ROS 2 and micro-ROS installation):
8686

8787
```bash
8888
source /opt/ros/$ROS_DISTRO/setup.bash
@@ -185,9 +185,9 @@ pgarrido@pgarrido$ ./firmware/build/zephyr/zephyr.exe
185185
*** Booting Zephyr OS build zephyr-v2.2.0-492-gc73cb85b4ae9 ***
186186
UDP mode => ip: 127.0.0.1 - port: 8888
187187
Ping send seq 1711620172_1742614911 <---- This micro-ROS node sends a ping with ping ID "1711620172" and node ID "1742614911"
188-
Pong for seq 1711620172_1742614911 (1) <---- The first mate pongs my ping
189-
Pong for seq 1711620172_1742614911 (2) <---- The second mate pongs my ping
190-
Pong for seq 1711620172_1742614911 (3) <---- The third mate pongs my ping
188+
Pong for seq 1711620172_1742614911 (1) <---- The first mate pongs my ping
189+
Pong for seq 1711620172_1742614911 (2) <---- The second mate pongs my ping
190+
Pong for seq 1711620172_1742614911 (3) <---- The third mate pongs my ping
191191
Ping received with seq 1845948271_546591567. Answering. <---- A ping is received from a mate identified as "546591567", let's pong it.
192192
Ping received with seq 232977719_1681483056. Answering. <---- A ping is received from a mate identified as "1681483056", let's pong it.
193193
Ping received with seq 1134264528_1107823050. Answering. <---- A ping is received from a mate identified as "1107823050", let's pong it.

‎_docs/tutorials/core/first_application_linux/index.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,11 @@ title: First micro-ROS Application on Linux
33
permalink: /docs/tutorials/core/first_application_linux/
44
---
55

6-
This tutorial teaches you how to create a first micro-ROS application on Linux for testing purposes. In the follow-up tutorial [*First micro-ROS application on an RTOS*](/docs/tutorials/core/first_application_rtos/), you'll learn how to build and bring this application on a microcontroller running the RTOS NuttX, FreeRTOS, or Zephyr.
6+
This tutorial teaches you how to try a first micro-ROS application on Linux for testing purposes.
7+
In the follow-up tutorial [*First micro-ROS application on an RTOS*](/docs/tutorials/core/first_application_rtos/),
8+
you'll learn how to build and bring this application on a microcontroller running the RTOS NuttX, FreeRTOS, or Zephyr.
9+
Finally in the tutorial [*Zephyr Emulator*](/docs/tutorials/advanced/zephyr_emulator/) you'll learn how to test
10+
a micro-ROS application on a Zephyr emulator.
711

812
## Installing ROS 2 and the micro-ROS build system
913

@@ -52,7 +56,7 @@ Further information about micro-ROS build system can be found [here](https://git
5256
Once the build system is installed, let's create a firmware workspace that targets all the required code and tools:
5357

5458
```bash
55-
# Create step
59+
# Create firmware step
5660
ros2 run micro_ros_setup create_firmware_ws.sh host
5761
```
5862

‎_docs/tutorials/core/first_application_rtos/zephyr.md‎

Lines changed: 206 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,73 @@ redirect_from:
55
- /docs/tutorials/advanced/zephyr/zephyr_getting_started/
66
---
77

8-
{% include first_application_rtos_common/section_01_intro.md %}
8+
## Target platform
99

10-
In this tutorial, you'll learn the use of micro-ROS with Zephyr.
10+
In this tutorial, you'll learn the use of micro-ROS with Zephyr, by testing a Ping Pong application.
1111

12-
{% include first_application_rtos_common/section_02_target_hardware_and_workspace.md %}
12+
The target hardware for this tutorial is the
13+
**[Olimex STM32-E407](https://www.olimex.com/Products/ARM/ST/STM32-E407/open-source-hardware)** evaluation board.
14+
15+
The following hardware will be used:
16+
17+
* [Olimex STM32-E407](https://www.olimex.com/Products/ARM/ST/STM32-E407/open-source-hardware)
18+
* [Olimex ARM-USB-TINY-H](https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/)
19+
* [USB-Serial Cable Female](https://www.olimex.com/Products/Components/Cables/USB-Serial-Cable/USB-Serial-Cable-F/)
20+
21+
## Installing ROS 2 and the micro-ROS build system
22+
23+
First of all, install **ROS 2 Dashing Diademata** on your Ubuntu 18.04 LTS computer.
24+
To do so from binaries, via Debian packages, follow the instructions detailed
25+
[here](https://index.ros.org/doc/ros2/Installation/Dashing/Linux-Install-Debians/) instead.
26+
Alternatively, you can use a docker container with a fresh ROS 2 Dashing installation. The minimum docker that serves
27+
the purpose is the image run by the command:
28+
29+
```bash
30+
docker pull ros:dashing-ros-base
31+
```
32+
33+
```bash
34+
# Source the ROS 2 installation
35+
source /opt/ros/dashing/setup.bash
36+
37+
# Create a workspace and download the micro-ROS tools
38+
mkdir microros_ws
39+
cd microros_ws
40+
git clone -b $ROS_DISTRO https://github.com/micro-ROS/micro-ros-build.git src/micro-ros-build
41+
42+
# Update dependencies using rosdep
43+
sudo apt update && rosdep update
44+
rosdep install --from-path src --ignore-src -y
45+
46+
# Build micro-ROS tools and source them
47+
colcon build
48+
source install/local_setup.bash
49+
```
50+
51+
***TIP:** if you are familiar with Docker containers, this image may be useful:
52+
[micro-ros:base](https://github.com/micro-ROS/docker/blob/dashing/base/Dockerfile)*
53+
54+
These instructions will setup a workspace with a ready-to-use micro-ROS build system.
55+
This build system is in charge of downloading the required cross-compilation tools and building the apps for the
56+
required platforms.
57+
58+
The build system's workflow is a four-step procedure:
59+
60+
* **Create step:** This step is in charge of downloading all the required code repositories and cross-compilation
61+
toolchains for the specific hardware platform. Among these repositories, it will also download a collection of ready
62+
to use micro-ROS apps.
63+
* **Configure step:** In this step, the user can select which app is going to be cross-compiled by the toolchain.
64+
Some other options, such as transport, agent address or port will be also selected in this step.
65+
* **Build step:** Here is where the cross-compilation takes place and the platform-specific binaries are generated.
66+
* **Flash step:** The binaries generated in the previous step are flashed onto the hardware platform memory, in order
67+
to allow the execution of the micro-ROS app.
68+
69+
Further information about micro-ROS build system can be found
70+
[here](https://github.com/micro-ROS/micro-ros-build/tree/dashing/micro_ros_setup).
71+
72+
## Step 1: Creating a new firmware workspace
73+
74+
Once the build system is installed, let's create a firmware workspace that targets all the required code and tools:
1375

1476
```bash
1577
# Create step
@@ -27,13 +89,141 @@ sudo apt update
2789
sudo apt install cmake
2890
```
2991

30-
{% include first_application_rtos_common/section_03_configuring_firmware.md %}
92+
Once the command is executed, a folder named `firmware` must be present in your workspace.
93+
94+
This step is in charge, among other things, of creating a set of micro-ROS apps for the specific platform you are
95+
addressing. In the case of Zephyr, these are located at `firmware/zephyr_apps/apps`.
96+
Each app is represented by a folder containing the following files:
97+
98+
* `src/main.c`: This file contains the logic of the application.
99+
* `app-colcon.meta`: This file contains the micro-ROS app specific colcon configuration. Detailed info on how to
100+
configure the RMW via this file can be found
101+
[here](https://micro-ros.github.io/docs/tutorials/core/microxrcedds_rmw_configuration/).
102+
* `CMakeLists.txt`: This is the CMake file containing the script to compile the application.
103+
* `prj.conf`: This is a Zephyr specific app configuration file.
104+
105+
For the user to create its custom application, a folder `<my_app>` will need to be registered in this location,
106+
containing the four files just described.
107+
108+
In this tutorial, we will focus on the out-of-the-box `ping_pong` application located at
109+
`firmware/zephyr_apps/apps/ping_pong`.
110+
You can check the complete content of this app
111+
[here](https://github.com/micro-ROS/zephyr_apps/tree/dashing/apps/ping_pong).
112+
113+
This example showcases a micro-ROS node with two publisher-subscriber pairs associated with a `ping` and a `pong`
114+
topics, respectively.
115+
The node sends a `ping` package with a unique identifier, using a `ping` publisher.
116+
If the `ping` subscriber receives a `ping` from an external node, the `pong` publisher responds to the incoming `ping`
117+
with a `pong`. To test that this logic is correctly functioning, we implement communication with a ROS 2 node that:
118+
119+
* Listens to the topics published by the `ping` subscriber.
120+
* Publishes a `fake_ping` package, that is received by the micro-ROS `ping` subscriber.
121+
As a consequence, the `pong` publisher on the micro-ROS application will publish a `pong`, to signal that it received
122+
the `fake_ping` correctly.
123+
124+
The diagram below clarifies the communication flow between these entities:
125+
126+
![pingpong](http://www.plantuml.com/plantuml/png/ZOwnIWGn48RxFCNFzSkoUG2vqce5jHEHi1dtWZkPa6GByNntavZY10yknMJu-ORlFwPiOjvvK-d3-M2YOR1uMKvHc93ZJafvoMML07d7h1NAE-DPWblg_na8vnwEx9OeZmzFOt1-BK7AzetJciPxCfRYVw1S0SbRLBEg1IpXPIvpUWLCmZpXIm6BS3addt7uQpu0ZQlxT1MK2r0g-7sfqbsbRrVfMrMwgbev3CDTlsqJGtJhATUmSMrMg5TKwaZUxfcttuMt7m00)
127+
128+
The contents of the Zephyr app specific files can be found here:
129+
[main.c](https://github.com/micro-ROS/zephyr_apps/blob/dashing/apps/ping_pong/src/main.c),
130+
[app-colcon.meta](https://github.com/micro-ROS/zephyr_apps/blob/dashing/apps/ping_pong/app-colcon.meta),
131+
[CMakeLists.txt](https://github.com/micro-ROS/zephyr_apps/blob/dashing/apps/ping_pong/CMakeLists.txt)
132+
and [prj.conf](https://github.com/micro-ROS/zephyr_apps/blob/dashing/apps/ping_pong/prj.conf).
133+
A thorough review of these files is illustrative of how to create a micro-ROS app in this RTOS.
134+
135+
Once the app has been created, the configuration step is in order.
136+
137+
## Step 2: Configuring the firmware
138+
139+
The configuration step will set up the main micro-ROS options and will select the required application.
140+
It can be executed with the following command:
141+
142+
```bash
143+
# Configure step
144+
ros2 run micro_ros_setup configure_firmware.sh [APP] [OPTIONS]
145+
```
146+
147+
The options available for this configuration step are:
148+
- `--transport` or `-t`: `udp`, `tcp`, `serial` or any hardware-specific transport label
149+
- `--dev` or `-d`: agent string descriptor in a serial-like transport
150+
- `--ip` or `-i`: agent IP in a network-like transport
151+
- `--port` or `-p`: agent port in a network-like transport
152+
153+
At this point, in order to build and try your first micro-ROS application, you can use the out-of-the-box `ping_pong`
154+
application located at `firmware/zephyr_apps/apps/ping_pong`. You can check the complete content of this app
155+
[here](https://github.com/micro-ROS/zephyr_apps/tree/dashing/apps/ping_pong). To execute it, run the command above
156+
by specifying the `[APP]` and `[OPTIONS]` parameters as below:
157+
158+
```bash
159+
# Configure step with ping_pong app and serial-usb transport
160+
ros2 run micro_ros_setup configure_firmware.sh ping_pong --transport serial-usb
161+
```
162+
163+
## Step 3: Building the firmware
164+
165+
When the configuring step ends, just build the firmware and source the local installation:
166+
167+
```bash
168+
# Build step
169+
ros2 run micro_ros_setup build_firmware.sh
170+
source install/local_setup.bash
171+
```
172+
173+
## Step 4: Flashing the firmware
174+
175+
Flashing the firmware into the platform varies across hardware platforms.
176+
Regarding this tutorial's target platform
177+
(**[Olimex STM32-E407](https://www.olimex.com/Products/ARM/ST/STM32-E407/open-source-hardware)**),
178+
the JTAG interface is going to be used to flash the firmware.
179+
180+
Connect [Olimex ARM-USB-TINY-H](https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/) to the board:
181+
182+
<img width="400" style="padding-right: 25px;" src="../imgs/2.jpg">
183+
184+
Make sure that the board power supply jumper (PWR_SEL) is in the 3-4 position in order to power the board from the
185+
JTAG connector:
186+
187+
<img width="400" style="padding-right: 25px;" src="../imgs/1.jpg">
188+
189+
Once you have your computer connected to the Olimex board through the JTAG adapter, run the flash step:
190+
191+
```bash
192+
# Flash step
193+
ros2 run micro_ros_setup flash_firmware.sh
194+
```
195+
196+
## Running the micro-ROS app
197+
198+
The micro-ROS app is ready to connect to a micro-ROS-Agent and start talking with the rest of the ROS 2 world.
199+
200+
First of all, create and build a micro-ROS agent:
201+
202+
```bash
203+
# Download micro-ROS-Agent packages
204+
ros2 run micro_ros_setup create_agent_ws.sh
205+
206+
# Build micro-ROS-Agent packages, this may take a while.
207+
colcon build
208+
source install/local_setup.bash
209+
```
210+
211+
Then, depending on the selected transport and RTOS, the board connection to the agent may differ:
212+
213+
```
214+
215+
216+
217+
==========================
218+
219+
220+
31221
32-
| RTOS | `[APP]` | `[OPTIONS]` | Configured app |
33-
| :--------: | --------------- | ---------------------------- | :--------------------------------------------------------------------------------: |
34-
| NuttX | `uros_pingpong` | | [Source](https://github.com/micro-ROS/apps/tree/dashing/examples/uros_pingpong) |
35-
| FreeRTOS | `ping_pong` | `--transport serial --dev 3` | [Source](https://github.com/micro-ROS/freertos_apps/tree/dashing/apps/ping_pong) |
36-
| **Zephyr** | **`ping_pong`** | **`--transport serial-usb`** | [**Source**](https://github.com/micro-ROS/zephyr_apps/tree/dashing/apps/ping_pong) |
222+
223+
224+
225+
226+
{% include first_application_rtos_common/section_03_configuring_firmware.md %}
37227
38228
{% include first_application_rtos_common/section_04_demo_description.md %}
39229
@@ -61,6 +251,11 @@ Once the app folder is created, let's configure our new app with a UDP transport
61251
ros2 run micro_ros_setup configure_firmware.sh ping_pong --transport serial-usb
62252
```
63253

254+
255+
256+
257+
258+
64259
{% include first_application_rtos_common/section_05_building_flashing_and_running.md %}
65260

66261
| RTOS | micro-ROS Client to Agent |
@@ -71,4 +266,5 @@ ros2 run micro_ros_setup configure_firmware.sh ping_pong --transport serial-usb
71266

72267
{% include first_application_rtos_common/section_06_agent.md %}
73268

74-
This completes the First micro-ROS Application on Zephyr tutorial. Do you want to [go back](../) and try a different RTOS, i.e. NuttX or FreeRTOS?
269+
This completes the First micro-ROS Application on Zephyr tutorial.
270+
Do you want to [go back](../) and try a different RTOS, i.e. NuttX or FreeRTOS?

‎_includes/first_application_rtos_common/section_01_intro.md‎

Lines changed: 52 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,54 @@
1-
After you have completed the [First micro-ROS application on Linux tutorial](../../first_application_linux), you are now ready to flash a microcontroller with this application based on a Real-Time Operating System (RTOS). Micro-ROS currently supports three different RTOS, namely NuttX, FreeRTOS, and Zephyr.
1+
## Installing ROS 2 and the micro-ROS build system
22

3-
To follow this tutorial, it is assumed that the user is already familiar with the **[First micro-ROS Application on an RTOS](https://micro-ros.github.io/docs/tutorials/core/first_application_rtos/)** tutorial. The target app in this tutorial is the same ping pong app. Another requirement is that the user has a basic knowledge of micro-ROS and ROS 2.
3+
First of all, install **ROS 2 Dashing Diademata** on your Ubuntu 18.04 LTS computer.
4+
To do so from binaries, via Debian packages, follow the instructions detailed
5+
[here](https://index.ros.org/doc/ros2/Installation/Dashing/Linux-Install-Debians/) instead.
6+
Alternatively, you can use a docker container with a fresh ROS 2 Dashing installation. The minimum docker that serves
7+
the purpose is the image run by the command:
48

5-
The target app in this tutorial is the same ping pong app. Another requirement is that the user has a basic knowledge of micro-ROS and ROS 2.
9+
```bash
10+
docker pull ros:dashing-ros-base
11+
```
12+
13+
```bash
14+
# Source the ROS 2 installation
15+
source /opt/ros/dashing/setup.bash
16+
17+
# Create a workspace and download the micro-ROS tools
18+
mkdir microros_ws
19+
cd microros_ws
20+
git clone -b $ROS_DISTRO https://github.com/micro-ROS/micro-ros-build.git src/micro-ros-build
21+
22+
# Update dependencies using rosdep
23+
sudo apt update && rosdep update
24+
rosdep install --from-path src --ignore-src -y
25+
26+
# Build micro-ROS tools and source them
27+
colcon build
28+
source install/local_setup.bash
29+
```
30+
31+
***TIP:** if you are familiar with Docker containers, this image may be useful:
32+
[micro-ros:base](https://github.com/micro-ROS/docker/blob/dashing/base/Dockerfile)*
33+
34+
These instructions will setup a workspace with a ready-to-use micro-ROS build system.
35+
This build system is in charge of downloading the required cross-compilation tools and building the apps for the
36+
required platforms.
37+
38+
The build system's workflow is a four-step procedure:
39+
40+
* **Create step:** This step is in charge of downloading all the required code repositories and cross-compilation
41+
toolchains for the specific hardware platform. Among these repositories, it will also download a collection of ready
42+
to use micro-ROS apps.
43+
* **Configure step:** In this step, the user can select which app is going to be cross-compiled by the toolchain.
44+
Some other options, such as transport, agent address or port will be also selected in this step.
45+
* **Build step:** Here is where the cross-compilation takes place and the platform-specific binaries are generated.
46+
* **Flash step:** The binaries generated in the previous step are flashed onto the hardware platform memory, in order
47+
to allow the execution of the micro-ROS app.
48+
49+
Further information about micro-ROS build system can be found
50+
[here](https://github.com/micro-ROS/micro-ros-build/tree/dashing/micro_ros_setup).
51+
52+
## Step 1: Creating a new firmware workspace
53+
54+
Once the build system is installed, let's create a firmware workspace that targets all the required code and tools:

0 commit comments

Comments
 (0)