Skip to content

Commit 9a166fb

Browse files
FranFinFranFin
committed
Significant changes in core tutori+zephyr_emulator tutorials.
1 parent d3faace commit 9a166fb

18 files changed

Lines changed: 368 additions & 627 deletions

File tree

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

Lines changed: 105 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -3,54 +3,66 @@ 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+
## Target platform
77

8-
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.
9-
Another requirement is that the user has a basic knowledge of micro-ROS and ROS 2.
8+
In this tutorial, you'll learn the use of micro-ROS with a **[Zephyr RTOS](https://www.zephyrproject.org/)**
9+
emulator (also known as [Native POSIX](https://docs.zephyrproject.org/latest/boards/posix/native_posix/doc/index.html))
10+
by testing a Ping Pong application.
1011

1112
<div>
1213
<img width="300" style="padding-right: 25px;" src="imgs/4.jpg">
1314
</div>
1415

15-
## Required hardware
16-
17-
This tutorial requires no hardware beyond a Linux host computer.
18-
19-
## Building a Zephyr emulator application
20-
21-
Once the micro-ROS build system is ready, let's create a new Zephyr firmware for the host platform:
16+
{% include first_application_common/build_system.md %}
2217

2318
```bash
24-
# Create firmware step
19+
# Create step
2520
ros2 run micro_ros_setup create_firmware_ws.sh zephyr host
2621
```
2722

28-
micro-ROS apps for Zephyr emulator are located at `firmware/zephyr_apps/apps`. In order to create a new application, create a new folder containing two files: the app code (inside a `src` folder) and the RMW configuration. You will also need some other Zephyr related files: a `CMakeLists.txt` to define the building process and a `prj.conf` where Zephyr is configured. There is a sample proyect [here](https://github.com/micro-ROS/zephyr_apps/tree/dashing/apps/host_ping_pong), for now, it is ok to copy them.
23+
Once the command is executed, a folder named `firmware` must be present in your workspace.
2924

30-
```bash
31-
# Creating a new app
32-
pushd firmware/zephyr_apps/apps
33-
mkdir host_ping_pong
34-
cd host_ping_pong
35-
mkdir src
25+
This step is in charge, among other things, of creating a set of micro-ROS apps for the specific platform you are
26+
addressing.
27+
In the case of Zephyr, these are located at `firmware/zephyr_apps/apps`.
28+
Each app is represented by a folder containing the following files:
3629

37-
touch src/app.c
38-
touch app-colcon.meta
39-
touch CMakeLists.txt
40-
touch prj.conf
30+
* `src/main.c`: This file contains the logic of the application.
31+
* `app-colcon.meta`: This file contains the micro-ROS app specific colcon configuration. Detailed info on how to
32+
configure the RMW via this file can be found
33+
[here](https://micro-ros.github.io/docs/tutorials/core/microxrcedds_rmw_configuration/).
34+
* `CMakeLists.txt`: This is the CMake file containing the script to compile the application.
35+
* `prj.conf`: This is a Zephyr specific app configuration file.
4136

42-
popd
43-
```
37+
For the user to create its custom application, a folder `<my_app>` will need to be registered in this location,
38+
containing the four files just described.
4439

45-
The contents of the files can be found here: [app.c](https://github.com/micro-ROS/zephyr_apps/blob/dashing/apps/host_ping_pong/src/main.c), [app-colcon.meta](https://github.com/micro-ROS/zephyr_apps/blob/dashing/apps/host_ping_pong/app-colcon.meta), [CMakeLists.txt](https://github.com/micro-ROS/zephyr_apps/blob/dashing/apps/host_ping_pong/CMakeLists.txt) and [prj.conf](https://github.com/micro-ROS/zephyr_apps/blob/dashing/apps/host_ping_pong/prj.conf).
40+
{% include first_application_common/config.md %}
4641

47-
Once the app folder is created, let's configure our new app with a UDP transport that looks for the agent on the port UDP/8888 at localhost:
42+
In this tutorial, we will use a UDP transport that looks for the agent on the port UDP/8888 at localhost, and focus on
43+
the out-of-the-box `host_ping_pong` application located at `firmware/zephyr_apps/apps/host_ping_pong`.
44+
To execute this application with the chosen transport, run the configuration command above by specifying the `[APP]`
45+
and `[OPTIONS]` parameters as below::
4846

4947
```bash
5048
# Configure step
5149
ros2 run micro_ros_setup configure_firmware.sh host_ping_pong --transport udp --ip 127.0.0.1 --port 8888
5250
```
5351

52+
You can check the complete content of the `host_ping_pong` app
53+
[here](https://github.com/micro-ROS/zephyr_apps/tree/dashing/apps/host_ping_pong).
54+
55+
{% include first_application_common/pingpong_logic.md %}
56+
57+
The contents of the Zephyr app specific files can be found here:
58+
[main.c](https://github.com/micro-ROS/zephyr_apps/blob/dashing/apps/host_ping_pong/src/main.c),
59+
[app-colcon.meta](https://github.com/micro-ROS/zephyr_apps/blob/dashing/apps/host_ping_pong/app-colcon.meta),
60+
[CMakeLists.txt](https://github.com/micro-ROS/zephyr_apps/blob/dashing/apps/host_ping_pong/CMakeLists.txt)
61+
and [prj.conf](https://github.com/micro-ROS/zephyr_apps/blob/dashing/apps/host_ping_pong/prj.conf).
62+
A thorough review of these files is illustrative of how to create a micro-ROS app in this RTOS.
63+
64+
## Building the firmware
65+
5466
When the configuring step ends, just build the firmware:
5567

5668
```bash
@@ -59,43 +71,64 @@ ros2 run micro_ros_setup build_firmware.sh
5971
```
6072

6173
Now you have a Zephyr + micro-ROS app ready to run on your own computer.
74+
Notice that in this case, the steps of flashing the firmware and running the micro-ROS app go together
6275

63-
## Running the micro-ROS app
76+
## Flashing the firmware
6477

65-
The micro-ROS app is ready to connect to a micro-ROS-Agent and start talking with the rest of the ROS 2 world.
78+
Now you can run the flash step by means of the flashing command:
6679

67-
First of all, create and build a micro-ROS agent:
80+
```bash
81+
# Flash/run step
82+
ros2 run micro_ros_setup flash_firmware.sh
83+
```
84+
85+
Notice that this command also has the effect of running the micro-ROS node.
86+
87+
## Creating the micro-ROS agent
88+
89+
The micro-ROS app is now ready to be connected to a micro-ROS agent to start talking with the rest of the ROS 2
90+
world.
91+
92+
To do that, let's open a new command line and create a micro-ROS agent
93+
(remember sourcing the ROS 2 and micro-ROS installations):
6894

6995
```bash
7096
# Download micro-ROS-Agent packages
97+
source /opt/ros/dashing/setup.bash
98+
source install/local_setup.bash
99+
71100
ros2 run micro_ros_setup create_agent_ws.sh
101+
```
102+
103+
Now, let's build the agent packages and, when this is done, source the installation:
72104

73-
# Build micro-ROS-Agent packages, this may take a while.
105+
```bash
106+
# Build step
74107
colcon build
75108
source install/local_setup.bash
76109
```
77110

78-
Then run the agent:
111+
## Running the micro-ROS app
112+
113+
At this point, you have both the client and the agent correctly installed in your host machine.
114+
115+
To start micro-ROS, you just need to run the agent:
79116

80117
```bash
81118
# Run a micro-ROS agent
82119
ros2 run micro_ros_agent micro_ros_agent udp4 --port 8888
83120
```
84121

85-
And run the Zephyr app in another command line (remember sourcing ROS 2 and micro-ROS installation):
86-
87-
```bash
88-
source /opt/ros/$ROS_DISTRO/setup.bash
89-
source microros_ws/install/local_setup.bash
122+
## Testing the micro-ROS app
90123

91-
# Flash/run step
92-
ros2 run micro_ros_setup flash_firmware.sh
93-
```
124+
At this point, the micro-ROS app is built and flashed and the board is connected to a micro-ROS agent.
125+
We now want to check that everything is working.
94126

95-
And finally, let's check that everything is working in another command line. We are going to listen to ping topic to check whether the Ping Pong node is publishing its own pings:
127+
Open a new command line. We are going to listen to the `ping` topic
128+
with ROS 2 to check whether the micro-ROS Ping Pong node is correctly publishing the expected pings:
96129

97130
```bash
98-
source /opt/ros/$ROS_DISTRO/setup.bash
131+
source /opt/ros/dashing/setup.bash
99132

100133
# Subscribe to micro-ROS ping topic
101134
ros2 topic echo /microROS/ping
@@ -117,25 +150,30 @@ frame_id: '730417256_1085377743'
117150
---
118151
```
119152

120-
On another command line, let's subscribe to the pong topic
153+
At this point, we know that our app is publishing pings.
154+
Let's check if it also answers to someone else's pings. If this works, it'll publish a pong.
155+
156+
So, first of all, let's subscribe with ROS 2 to the `pong` topic
157+
(notice that initially we don't expect to receive any pong, since none has been sent yet):
121158

122159
```bash
123-
source /opt/ros/$ROS_DISTRO/setup.bash
160+
source /opt/ros/dashing/setup.bash
124161

125162
# Subscribe to micro-ROS pong topic
126163
ros2 topic echo /microROS/pong
127164
```
128165

129-
At this point, we know that our app is publishing pings. Let's check if it also answers to someone else pings in a new command line:
166+
And now, let's publish a `fake_ping` with ROS 2 from yet another command line:
130167

131168
```bash
132-
source /opt/ros/$ROS_DISTRO/setup.bash
169+
source /opt/ros/dashing/setup.bash
133170

134171
# Send a fake ping
135172
ros2 topic pub --once /microROS/ping std_msgs/msg/Header '{frame_id: "fake_ping"}'
136173
```
137174

138-
Now, we should see on the ping subscriber our fake ping along with the board pings:
175+
Now, we should see this `fake_ping` in the `ping` subscriber console (the second that we opened),
176+
along with the micro-ROS pings:
139177

140178
```
141179
user@user:~$ ros2 topic echo /microROS/ping
@@ -156,10 +194,26 @@ frame_id: '2084670932_1085377743'
156194
---
157195
```
158196

159-
And in the pong subscriber, we should see the board's answer to our fake ping:
197+
Also, we expect that, because of having received the `fake_ping`, the micro-ROS node will answer with a `pong`:
198+
199+
```
200+
user@user:~$ ros2 run micro_ros_setup flash_firmware.sh
201+
Ping send seq 1706097268_1085377743
202+
Ping send seq 181171802_1085377743
203+
Ping send seq 1385567526_1085377743
204+
Ping send seq 926583793_1085377743
205+
Ping send seq 1831510138_1085377743
206+
Ping received with seq fake_ping. Answering.
207+
Ping send seq 1508705084_1085377743
208+
Ping send seq 1702133625_1085377743
209+
Ping send seq 176104820_1085377743
210+
```
211+
212+
As a consequence, in the `pong` subscriber console (the third that we opened),
213+
we should see the micro-ROS app answer to our `fake_ping`:
160214

161215
```
162-
pgarrido@pgarrido:~$ ros2 topic echo /microROS/pong
216+
user@user:~$ ros2 topic echo /microROS/pong
163217
stamp:
164218
sec: 0
165219
nanosec: 0
@@ -169,7 +223,9 @@ frame_id: fake_ping
169223

170224
## Multiple Ping Pong nodes
171225

172-
One of the advantages of having an emulator is that you don't need to buy a bunch of hardware in order to test some multi-node micro-ROS apps. So, with the same micro-ROS agent of the last section, let's open four different command lines and run the following on each:
226+
One of the advantages of having an emulator is that you don't need to buy a bunch of hardware in order to test some
227+
multi-node micro-ROS apps. So, with the same micro-ROS agent of the last section, let's open four different command
228+
lines and run the following on each:
173229

174230
```bash
175231
cd microros_ws

0 commit comments

Comments
 (0)