Skip to content

Commit 8c97ca5

Browse files
imuguruzaimuguruza
committed
Add simulator tutorial page
1 parent 65f5540 commit 8c97ca5

1 file changed

Lines changed: 246 additions & 0 deletions

File tree

  • _docs/tutorials/getting_started_simulator

‎_docs/tutorials/getting_started_simulator/index.md‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
---
2+
title: Getting Started with simulator (WIP)
3+
permalink: /docs/tutorials/getting_started_simulator/
4+
author: Iñigo Muguruza Goenaga, Juan Muñoz Flores
5+
---
6+
7+
Table of contents
8+
9+
* [Running micro-ROS example in the simulator](#running-micro-ROS-example)
10+
* [Running Micro XRCE-DDS example in the simulator](#running-Micro-XRCE-DDS-example)
11+
12+
## Introduction
13+
14+
The aim of this section is to be able of running micro-ROS architecture examples using Docker files. The main difference at this examples is that you are going to use [QEMU simulator](https://www.qemu.org/).
15+
16+
In this simulator, we are going to emulate the architectures of the MCUs we are using at the project, which are Cortex-M3 and Cortex-M4. At the time of writing this page, as the Cortex-M4 is not supported, we are using a STMF103C8 part number configuration, with a bigger RAM and Flash size, in order to simulate the memory capabilities the used embedded board contains.
17+
18+
19+
20+
## Running micro-ROS example
21+
22+
WIP, is not running properly yet! More info [here](https://github.com/microROS/docker/tree/docker_sim/Simulation/micro-ROS).
23+
24+
25+
## Running Micro XRCE-DDS example
26+
27+
This is a Docker image that sets the proper configuration and dependencies to run a Micro XRCE-DDS NuttX Client application in an emulated Cortex M3 MCU using Quemu.
28+
29+
This example uses NuttX RTOS, micro-XRCE-DDS client example code and micro-XRCE-DDS Agent.
30+
31+
32+
### Build
33+
34+
Build your own the image using the docker file:
35+
36+
```bash
37+
docker build -t microxrcedds_sim .
38+
```
39+
40+
41+
### Run
42+
43+
_Note: the example explained here works with the [commit a495c65](https://github.com/eProsima/Micro-XRCE-DDS-Agent/commit/a495c65faa964ddc068ac6e1249f17f5c9f92787) of Micro XRCE-DDS Agent and NuttX "nuttx-sim-dev" branch [commit 54b0ca9](https://github.com/microROS/NuttX/commit/54b0ca954ae2a734ebef6d1dec589813bfd026a7)._
44+
45+
#### Client 1: Micro XRCE-DDS publisher
46+
47+
Open a new terminal and access the container with privileges so that we can run the binary in simulated board at Quemu:
48+
49+
```bash
50+
docker run -it -v /dev/bus/usb:/dev/bus/usb --privileged microxrcedds_sim /bin/bash
51+
```
52+
53+
Execute the simulator running the NuttX binary that contains the RTOS and the client application:
54+
55+
```bash
56+
##### inside the docker container
57+
cd nuttx
58+
qemu-system-arm -M stm32-f103c8 -serial pty -serial tcp::7777,server -kernel nuttx.bin
59+
```
60+
61+
You should see something like this:
62+
63+
```bash
64+
root@80b9715bedfe:~/nuttx# qemu-system-arm -M stm32-f103c8 -serial pty -serial tcp::7777,server -kernel nuttx.bin
65+
66+
(process:118): GLib-WARNING **: 17:19:54.688: ../../../../glib/gmem.c:489: custom memory allocation vtable not supported
67+
char device redirected to /dev/pts/7 (label serial0)
68+
QEMU waiting for connection on: tcp:0.0.0.0:7777,server
69+
VNC server running on `127.0.0.1:5900'
70+
LED Off
71+
72+
```
73+
74+
75+
Qemu creates one serial port, labeled as "/dev/pts/x".This serial port is the auxiliary port, to be used to attach the Agent. The TCP server which have 0.0.0.0 IP and is attached to the port 7777 handles the console.
76+
(If you want to use another Qemu simulation in the same machine you should give another port number I.E. 8888).
77+
To access to the console, just use an utility like ``Netcat``. For this app, the command to execute should be:
78+
```bash
79+
netcat 0.0.0.0 7777
80+
```
81+
82+
At this point, the simulator is running properly. In a new terminal, obtain the container ID typing `docker ps`. Find *microxrcedds_sim* and copy the *CONTAINER ID*. Type the next command to run an auxiliary console: `docker exec -it <container_id> /bin/bash`.
83+
84+
85+
The micro-ROS Agent is going to connect to the serial the simulator has opened to have communications among them. Now follow the next steps to execute the agent:
86+
87+
+ Access to the folder where the Agent is compiled, using `~/micro-XRCE-DDS-agent/build`.
88+
+ Execute `./MicroXRCEAgent serial /dev/pts/<tty_number>` command, where <tty_number> is the second tty printed when the NuttX binary is executed. For example:
89+
90+
```
91+
(process:118): GLib-WARNING **: 17:19:54.688: ../../../../glib/gmem.c:489: custom memory allocation vtable not supported
92+
char device redirected to /dev/pts/7 (label serial0)
93+
QEMU waiting for connection on: tcp:0.0.0.0:7777,server
94+
VNC server running on `127.0.0.1:5900'
95+
LED Off
96+
97+
```
98+
99+
In this case `/dev/pts/7` is the serial where the client and the agent will talk, so the agent's serial needs to be attached there. You should see the next once you launch the Agent:
100+
101+
```
102+
root@2bdee009f1b1:~/micro-XRCE-DDS-agent/build# ././MicroXRCEAgent serial /dev/pts/7
103+
Serial agent initialization... OK
104+
Enter 'q' for exit
105+
```
106+
107+
Now we need another execution of the docker attached to the NuttX Shell serial session. This session will be used to launch the client inside NuttX.
108+
109+
+ Execute again `docker exec -it <container_id> /bin/bash` in a new terminal.
110+
+ Open a minicom session attached to the first serial session, following the previous example, `docker exec -it <container_id> /bin/bash`.
111+
+ Open a `netcat tcp listener` to opent the terminal attached to the serial created by the emulator, in this case, `netcat 0.0.0.0 7777`
112+
+ Hit enter a couple of times, you should see NuttX NSH shell prompt, type `?` to see if you have the client binary:
113+
114+
```
115+
nsh> ?
116+
help usage: help [-v] [<cmd>]
117+
118+
[ dd help mh sleep xd
119+
? echo hexdump mw test
120+
cat exec kill pwd true
121+
cd exit ls set unset
122+
cp false mb sh usleep
123+
124+
Builtin Apps:
125+
client
126+
```
127+
Chek the available serial ports:
128+
129+
```
130+
nsh> ls /dev
131+
/dev:
132+
console
133+
null
134+
ttyS0
135+
ttyS1
136+
```
137+
And launch the client, attaching it to the second serial where the Agent is listening, using `client --serial /dev/ttyS1` command. The output should be the next:
138+
139+
```
140+
nsh> client --serial /dev/ttyS1
141+
Serial mode => dev: /dev/ttyS1
142+
Running Shapes Demo Client...
143+
```
144+
145+
#### Client 2: Micro XRCE-DDS subscriber
146+
147+
Repeat the steps described at the publisher. You need to change the port of the Qemu TCP server, in the next command you can see an example:
148+
`qemu-system-arm -M stm32-f103c8 -serial pty -serial tcp::8888,server -kernel nuttx.bin`
149+
150+
#### Creating the publisher and subscriber
151+
152+
_Note: the instructions have been taken from eProsima [documentation](https://micro-xrce-dds.readthedocs.io/en/latest/shapes_demo.html)_
153+
154+
Now that we have two Micro XRCE-DDS clients running, with one terminal attached to the NuttX shell and the Agent connected to the second serial, we are able to set the function of each one.
155+
156+
##### Publisher
157+
158+
Take one of the clients NuttX Shell session and type the next command: `create_session`. The output should be the next:
159+
160+
```
161+
=>> 34: (key: AA BB CC DD | n: 0 | 0) [CREATE CLIENT | req: 0x0001 | obj: 0xF
162+
=>> << [34]: 80 00 00 00 00 01 1A 00 00 01 FF FE 58 52 43 45 01 00 01 0F 1D 05 >
163+
=>> 34: (key: AA BB CC DD | n: 0 | 0) [CREATE CLIENT | req: 0x0001 | obj: 0xF
164+
=>> << [34]: 80 00 00 00 00 01 1A 00 00 01 FF FE 58 52 43 45 01 00 01 0F 1D 05 >
165+
<<= 33: (key: AA BB CC DD | n: 0 | 0) [STATUS AGENT | req: 0x0001 | obj: 0xFF
166+
<<= << [33]: 81 00 00 00 04 01 19 00 00 01 FF FE 00 00 58 52 43 45 01 00 01 0F >
167+
Status: OK
168+
```
169+
170+
Now, type the command `create_participant 1`.The output should be the next:
171+
172+
```
173+
<<= 33: (key: AA BB CC DD | n: 0 | 0) [STATUS AGENT | req: 0x0001 | obj: 0xFF
174+
<<= << [33]: 81 00 00 00 04 01 19 00 00 01 FF FE 00 00 58 52 43 45 01 00 01 0F >
175+
=>> 48: (key: AA BB CC DD | r:80 | 0) [CREATE | | req: 0x000A | obj: 0x0011
176+
=>> << [48]: 81 80 00 00 01 01 28 00 00 0A 00 11 01 01 00 00 19 00 00 00 64 65 >
177+
=>> 12: (key: AA BB CC DD | n:80 | 0) [HEARTBEAT | first: 0 | last: 0] t: 988
178+
=>> << [12]: 81 00 80 00 0B 01 04 00 00 00 00 00 >>
179+
<<= 14: (key: AA BB CC DD | r:80 | 0) [STATUS | req: 0x000A | obj: 0x0011 | O
180+
<<= << [14]: 81 80 00 00 05 01 06 00 00 0A 00 11 00 00 >>
181+
Status: OK
182+
=>> 12: (key: AA BB CC DD | n:80 | 0) [ACKNACK | seq_num: 1 | bitmap: 0000000
183+
=>> << [12]: 81 00 80 00 0A 01 04 00 01 00 00 00 >>
184+
=>> 12: (key: AA BB CC DD | n:80 | 0) [HEARTBEAT | first: 0 | last: 0] t: 990
185+
=>> << [12]: 81 00 80 00 0B 01 04 00 00 00 00 00 >>
186+
<<= 12: (key: AA BB CC DD | n:80 | 0) [ACKNACK | seq_num: 1 | bitmap: 0000000
187+
<<= << [12]: 81 00 80 00 0A 01 04 00 01 00 00 00 >>
188+
<<= 12: (key: AA BB CC DD | n:80 | 0) [ACKNACK | seq_num: 1 | bitmap: 0000000
189+
<<= << [12]: 81 00 80 00 0A 01 04 00 01 00 00 00 >>
190+
<<= 12: (key: AA BB CC DD | n:80 | 0) [ACKNACK | seq_num: 1 | bitmap: 0000000
191+
<<= << [12]: 81 00 80 00 0A 01 04 00 01 00 00 00 >>
192+
```
193+
194+
Now, create a topic `create_topic 1 1`.
195+
196+
Now, create publisher `create_publisher 1 1`, and a data writer, `create_datawriter 1 1`.
197+
198+
##### Subscriber
199+
200+
Once we have the publisher working , we need to attach a subscriber to it, using the Micro XRCE-DDS Agent.
201+
202+
First run in this client, the NuttX application of the client:
203+
```
204+
nsh> client --serial /dev/ttyS1
205+
Serial mode => dev: /dev/ttyS1
206+
Running Shapes Demo Client...
207+
```
208+
209+
Now that the client is running, use the next commands to attach to the client that is going to publish data:
210+
211+
+ `create_session`
212+
+ `create_participant 1`
213+
214+
At this point, you should see in the terminal of both Agents that they have matched:
215+
216+
```
217+
RTPS Participant matched 1.f.0.2.cb.0.0.0.0.0.0.0|0.0.1.c1
218+
```
219+
220+
+ `create_subscriber 1 1`
221+
+ `create_datareader 1 1`
222+
223+
And finally, request data to the publisher:
224+
225+
+ `request_data 1 128 5`
226+
227+
##### Publish data
228+
229+
Now the subscriber is listening and the Agents are matched, publish data using the next command: `write_data 1 128 200 200 40 BLUE`
230+
231+
In the subscriber terminal, you should see how it receives the data:
232+
233+
```
234+
Receiving... [SHAPE_TYPE | color: BLUE | x: 200 | y: 200 | size: 40]
235+
=>> 12: (key: AA BB CC DD | n:80 | 0) [ACKNACK | seq_num: 5 | bitmap: 0000000
236+
=>> << [12]: 81 00 80 00 0A 01 04 00 05 00 00 00 >>
237+
<<= 12: (key: AA BB CC DD | n:80 | 0) [HEARTBEAT | first: 4 | last: 4] t: 551
238+
<<= << [12]: 81 00 80 00 0B 01 04 00 04 00 04 00 >>
239+
=>> 12: (key: AA BB CC DD | n:80 | 0) [ACKNACK | seq_num: 5 | bitmap: 0000000
240+
=>> << [12]: 81 00 80 00 0A 01 04 00 05 00 00 00 >>
241+
```
242+
243+
244+
_Needs rework to explain better how to open new terminals_
245+
246+

0 commit comments

Comments
 (0)