Skip to content

Commit 5ab3818

Browse files
takasehidekitakasehideki
committed
enrich README (fix #3) and follow the instruction with mros2 v0.5.3
1 parent 323be95 commit 5ab3818

File tree

1 file changed

+265
-61
lines changed

1 file changed

+265
-61
lines changed

‎README.md‎

Lines changed: 265 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,106 +1,310 @@
11
# mros2-esp32
2-
mROS 2 (formally `mros2`) realizes a agent-less and lightweight runtime environment compatible with ROS 2 for embedded devices.
2+
3+
mROS 2 (`mros2` as casually codename) realizes a agent-less and lightweight runtime environment compatible with ROS 2 for embedded devices.
34
mROS 2 mainly offers pub/sub APIs compatible with [rclcpp](https://docs.ros.org/en/rolling/p/rclcpp/index.html) for embedded devices.
45

56
mROS 2 consists of communication library for pub/sub APIs, RTPS protocol, UDP/IP stack, and real-time kernel.
6-
This repository provides the reference implementation of mROS 2 that can be operated on the Mbed enabled board.
7+
This repository provides the reference implementation of mROS 2 that can be operated on the [Espressif Systems ESP32](https://www.espressif.com/en/products/socs/esp32) boards.
78
Please also check [mros2 repository](https://github.com/mROS-base/mros2) for more details and another implementations.
89

910
## Supported environment
10-
- ESP32-S3-DevKitC-1
11-
- M5Stack Basic
12-
- M5Stack Core2
13-
- M5Stack CoreS3
14-
- XIAO ESP32C3 (see [#7](https://github.com/mROS-base/mros2-esp32/issues/7))
1511

16-
# Quickstart by this repository itself
12+
- ESP32 board
13+
- For now, these boards below are confirmed to run the example on them.
14+
- [ESP32-S3-DevKitC-1](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/hw-reference/esp32s3/user-guide-devkitc-1.html)
15+
- These boards below are also confirmed but not always supported in the latest version (due to our development resources,,,).
16+
- [M5Stack Basic](http://docs.m5stack.com/en/core/basic)
17+
- [M5Stack Core2](http://docs.m5stack.com/en/core/core2)
18+
- [M5Stack CoreS3](http://docs.m5stack.com/en/core/CoreS3)
19+
- [XIAO ESP32C3](https://www.seeedstudio.com/Seeed-XIAO-ESP32C3-p-5431.html) (see [#7](https://github.com/mROS-base/mros2-esp32/issues/7))
20+
- Kernel: [ESP-IDF FreeRTOS](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/freertos_idf.html)
21+
- Host environment
22+
- [ROS 2 Humble Hawksbill](https://docs.ros.org/en/humble/index.html) on Ubuntu 22.04 LTS
23+
- Network setting
24+
- Make sure both the device and the host are connected to the same network.
25+
- IP address needs to be assigned to the device by DHCP. We have not confirmed the operation using static IP setting yet. So you may not un-comment the `#define STATIC_IP` line in `platform/wifi/wifi.h`.
26+
- Please prepare the Wi-Fi router that provides 2.4 GHz band.
27+
- Most of ESP32 only support 2.4 GHz.
28+
- Note that you need to set up a dedicated SSID at 2.4 GHz. If the SSID has a band steering setting (that shares 2.4 GHz and 5 GHz), the communication of ESP32 may be disconnected during the operation.
29+
- The firewall on the host (Ubuntu) needs to be disabled for ROS 2 (DDS) communication (e.g. `$ sudo ufw disable`).
30+
- If the host is connected to the Internet with other network adapters, communication with mros2 may not work properly. In that case, please turn off them.
31+
32+
## Setup for development environment
33+
34+
First, please install ESP-IDF as the toolchain for ESP32 family.
35+
We recommend to install it followed "Maunal Installation".
36+
https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#manual-installation
37+
38+
Currently, we checked the operation of basic sapmles with [esp-idf v5.1.1](https://github.com/espressif/esp-idf/releases/tag/v5.1.1).
39+
40+
Building mros2 library requires [Jinja2](https://pypi.org/project/Jinja2/) (to generate `platform/templates.hpp` automatically). So please install this as the below.
1741

18-
## install esp-idf
19-
https://docs.espressif.com/projects/esp-idf/en/latest/esp32/index.html
42+
```
43+
$ pip install -U Jinja2
44+
```
45+
46+
## Quickstart only with this repository
2047

48+
This repository contains mros2 libarary with its related implementations for ESP32, and some examples in [`workspace/`](workspace/).
49+
IOW, this repository is all you need to try it out about the power of mros2-esp32 right away!!
50+
This sections describes the quickstart with `workspace/echoback_string` as the examples.
2151

22-
After install esp-idf, you need to install jinja2 library in esp-idf environment.
52+
You can also use this repositoy as a component in your own ESP-IDF project.
53+
If you want to do so, please refer to [Usage into your own ESP-IDF project](#usage-into-your-own-esp-idf-project) in the next section.
2354

24-
Currently, we checked the operation of basic sapmles with esp-idf v5.1.1.
55+
### git clone
56+
57+
Please `git clone` this repository with `--recursive` (mandatory).
2558

26-
## git clone and settings
2759
```
2860
git clone --recursive https://github.com/mROS-base/mros2-esp32.git
2961
cd mros2-esp32
3062
```
31-
### Change WiFi SSID/Pass
32-
Change ESP_WIFI_SSID and ESP_WIFI_PASS in `platform/wifi/wifi.h`.
3363

34-
### Change IP address
35-
Change IP address in `platform/rtps/config.h`.
64+
Note that you cannot change the directory name from `mros2-esp32` since it is used as the component name in `CMakeLists.txt`.
65+
66+
### Setup your SSID and PASS
67+
68+
Please setup SSID and PASS for your Wi-Fi AP in `platform/wifi/wifi.h` (be careful that we should not commit and push your network environment to the world :D)
69+
70+
```platform/wifi/wifi.h
71+
#define ESP_WIFI_SSID "SSID"
72+
#define ESP_WIFI_PASS "PASS"
73+
```
74+
75+
Again, make sure that its SSID assigns IP by DHCP and is dedicated to 2.4 GHz band.
76+
77+
### Set target
78+
79+
Go to `workspace/echoback_string/` and do the below to setup the target device.
80+
You need to adjust `<target>` arg for your device (e.g., M5Stack Basic and Core2 for `esp32`, ESP32S3Dev and M5Stack CoreS3 for `esp32s3`)
81+
82+
```
83+
cd workspace/echoback_string
84+
idf.py set-target esp32
85+
```
86+
87+
Next, you need to disable IPv6 connection for lwIP, since RTPS communication cannot work well when it is enabled.
88+
Please do `idf.py menuconfig`, move to "Component config" -> "LWIP" -> "Enable IPv6" and --->" and type Space to disable it.
89+
90+
The below image is from [@tasada038](https://github.com/tasada038)'s article: 「[mros2-esp32とM5Stackでサンプルプログラムを試す](https://zenn.dev/tasada038/articles/fdbf3e5ff7cd01)」
91+
92+
[![](https://storage.googleapis.com/zenn-user-upload/667047c679bb-20230606.png)](https://zenn.dev/tasada038/articles/fdbf3e5ff7cd01#mros2-esp32%E3%81%AE%E3%82%B5%E3%83%B3%E3%83%97%E3%83%AB%E5%AE%9F%E8%A1%8C)
93+
94+
If you are afraid to fiddle with this screen, you can skip this step because disabling IPv6 will be disabled automatically during the build process.
95+
However, you need to run the build twice in a row for proper configuration in this case.
3696

37-
When using DHCP, it is also necessary to specify the IP address.
38-
Flash the app and check the IP address from startup log.
39-
After that chenge the IP address in ```config.h``` and rebuild it.
97+
### build, flash, and run!
98+
99+
Please build the project as the below command.
100+
101+
```
102+
idf.py build
103+
```
104+
105+
When the build completed successfully, a binary is generated in `build/echoback_string.bin`.
106+
107+
Connect the device to the host via USB cable, and flash the binary to it.
108+
The default port in Ubuntu may be `/tty/ttyUSB0``, but you may need to change it according to your environment.
109+
110+
```
111+
idf.py -p /tty/ttyUSB0 flash
112+
```
113+
114+
Finally, ron-yori-Run!
115+
You can observe the serial terminal by [IDF Monitor](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-monitor.html)
116+
(quit is `Ctrl + ]`).
117+
118+
```
119+
$ idf.py -p /tty/ttyUSB0 monitor
120+
Executing action: monitor
121+
Running idf_monitor in directory /home/hogehoge/mros2-esp32/workspace/echoback_string
122+
...(SNIPPED)...
123+
I (2208) esp_netif_handlers: sta ip: 192.168.11.102, mask: 255.255.255.0, gw: 192.168.11.1
124+
I (2208) wifi station: got ip:192.168.11.102
125+
I (2208) wifi station: connected to ap SSID:SSID password:PASS
126+
LOG_DEBUG : 00000000.182 : [MROS2LIB] set "192.168.11.102" for RTPS communication
127+
LOG_NOTICE : 00000000.182 : successfully connect and setup network
128+
---
129+
LOG_NOTICE : 00000000.183 : mros2-esp32 start!
130+
LOG_NOTICE : 00000000.183 : app name: echoback_string
131+
LOG_DEBUG : 00000000.184 : [MROS2LIB] mros2_init task start
132+
LOG_DEBUG : 00000000.184 : [MROS2LIB] Initilizing lwIP complete
133+
LOG_DEBUG : 00000000.185 : mROS 2 initialization is completed
134+
LOG_DEBUG : 00000000.186 : [MROS2LIB] create_node
135+
LOG_DEBUG : 00000000.186 : [MROS2LIB] start creating participant
136+
LOG_DEBUG : 00000000.187 : [MROS2LIB] successfully created participant
137+
LOG_DEBUG : 00000000.187 : [MROS2LIB] create_publisher complete.
138+
LOG_DEBUG : 00000000.188 : [MROS2LIB] create_subscription complete.
139+
LOG_DEBUG : 00000000.195 : [MROS2LIB] Initilizing Domain complete
140+
LOG_NOTICE : 00000000.198 : ready to pub/sub message
141+
---
142+
LOG_NOTICE : 00000000.198 : publishing msg: 'Hello from mros2-esp32 onto "ESP32": 0'
143+
LOG_NOTICE : 00000000.298 : publishing msg: 'Hello from mros2-esp32 onto "ESP32": 1'
144+
LOG_NOTICE : 00000000.398 : publishing msg: 'Hello from mros2-esp32 onto "ESP32": 2'
145+
LOG_NOTICE : 00000000.498 : publishing msg: 'Hello from mros2-esp32 onto "ESP32": 3'
146+
...(SNIPPED)...
147+
```
148+
149+
You can confirm proper connection with your AP (SSID and PASS), and gotten IP address that will also be set for RTPS communication.
150+
151+
To confirm the operation of this echoback_string example, please operate [mros2-host-examples/mros2_echoreply_string](https://github.com/mROS-base/mros2-host-examples#mros2_echoreply_string) node on the ROS 2 host as the below.
152+
153+
```
154+
$ ros2 run mros2_echoreply_string echoreply_node
155+
[INFO] [1695193182.117751738] [mros2_echoreply_node]:
156+
Subscribed msg: 'Hello from mros2-esp32 onto "ESP32": 11'
157+
[INFO] [1695193182.117877196] [mros2_echoreply_node]:
158+
Publishing msg: 'Hello from mros2-esp32 onto "ESP32": 11'
159+
[INFO] [1695193183.115781171] [mros2_echoreply_node]:
160+
Subscribed msg: 'Hello from mros2-esp32 onto "ESP32": 12'
161+
[INFO] [1695193183.115852751] [mros2_echoreply_node]:
162+
Publishing msg: 'Hello from mros2-esp32 onto "ESP32": 12'
163+
[INFO] [1695193184.160837237] [mros2_echoreply_node]:
164+
Subscribed msg: 'Hello from mros2-esp32 onto "ESP32": 13'
165+
[INFO] [1695193184.160930132] [mros2_echoreply_node]:
166+
Publishing msg: 'Hello from mros2-esp32 onto "ESP32": 13'
167+
[INFO] [1695193185.185828052] [mros2_echoreply_node]:
168+
Subscribed msg: 'Hello from mros2-esp32 onto "ESP32": 14'
169+
[INFO] [1695193185.185916568] [mros2_echoreply_node]:
170+
Publishing msg: 'Hello from mros2-esp32 onto "ESP32": 14'
171+
...(SNIPPED)...
172+
```
173+
174+
After that, mros2-esp32 and ROS 2 host can be connected directly via RTPS!
175+
176+
```
177+
...(SNIPPED)...
178+
LOG_NOTICE : 00000001.245 : publishing msg: 'Hello from mros2-esp32 onto "ESP32": 9'
179+
LOG_NOTICE : 00000001.345 : publishing msg: 'Hello from mros2-esp32 onto "ESP32": 10'
180+
LOG_DEBUG : 00000001.397 : [MROS2LIB] publisher matched with remote subscriber
181+
LOG_NOTICE : 00000001.445 : publishing msg: 'Hello from mros2-esp32 onto "ESP32": 11'
182+
LOG_NOTICE : 00000001.446 : subscribed msg: 'Hello from mros2-esp32 onto "ESP32": 11'
183+
LOG_NOTICE : 00000001.545 : publishing msg: 'Hello from mros2-esp32 onto "ESP32": 12'
184+
LOG_NOTICE : 00000001.545 : subscribed msg: 'Hello from mros2-esp32 onto "ESP32": 12'
185+
LOG_DEBUG : 00000001.611 : [MROS2LIB] subscriber matched with remote publisher
186+
LOG_NOTICE : 00000001.645 : publishing msg: 'Hello from mros2-esp32 onto "ESP32": 13'
187+
LOG_NOTICE : 00000001.650 : subscribed msg: 'Hello from mros2-esp32 onto "ESP32": 13'
188+
LOG_NOTICE : 00000001.745 : publishing msg: 'Hello from mros2-esp32 onto "ESP32": 14'
189+
LOG_NOTICE : 00000001.755 : subscribed msg: 'Hello from mros2-esp32 onto "ESP32": 14'
190+
...(SNIPPED)...
191+
```
192+
193+
### Examples
40194

41-
## Examples
42195
This repository contains some example applications in [workspace/](workspace/) to communicate with ROS 2 nodes on the host.
43-
Of course you can also create a new program file and specify it as your own application.
44196

197+
The followings are the basic communication examples to the host.
198+
The description and host operation of them are almost the same with [mros2-mbed#Examples](https://github.com/mROS-base/mros2-mbed#examples) (link is to mros2-mbed ripository).
45199
Please also check [mROS-base/mros2-host-examples](https://github.com/mROS-base/mros2-host-examples) repository for more detail about the host examples.
46200

47-
Currently, the following examples are available.
48-
- echoback_string
49-
- echoreply_string
50-
- pub_float32
51-
- pub_twist
52-
- sub_pose
53-
- sub_uint16
201+
- [echoback_string](https://github.com/mROS-base/mros2-mbed#echoback_string-default)
202+
- [echoreply_string](https://github.com/mROS-base/mros2-mbed#echoreply_string)
203+
- [pub_float32](https://github.com/mROS-base/mros2-mbed#pub_float32)
204+
- [pub_twist](https://github.com/mROS-base/mros2-mbed#pub_twist)
205+
- [sub_pose](https://github.com/mROS-base/mros2-mbed#sub_pose)
206+
- [sub_uint16](https://github.com/mROS-base/mros2-mbed#sub_uint16)
207+
208+
The followings are under development and not confirmed the proper operation yet (also see [Issue#14](https://github.com/mROS-base/mros2-esp32/issues/14))
209+
210+
- [pub_image](https://github.com/mROS-base/mros2-mbed#pub_image)
211+
- [pub_long_string_sub_crc](https://github.com/mROS-base/mros2-mbed#pub_long_string_sub_crc)
212+
213+
The followings is for M5Stack device.
214+
You need to do `git clone` [M5Unified](https://github.com/m5stack/M5Unified) and [M5GFX](https://github.com/m5stack/M5GFX) in `components/`, and use ESP-IDF v4.4.4 to try this sample due to the compatibility of these libraries.
215+
54216
- m5stack_sample
55-
- M5Stack_sample project needs [M5Unified](https://github.com/m5stack/M5Unified) and [M5GFX](https://github.com/m5stack/M5GFX) libraries.
56-
Git clone these libraries to ```common/``` directory.
57-
Note that you need to use ESP-IDF v4.4.4 to try this sample due to the compatibility of these libraries.
58217

218+
## Usage into your own ESP-IDF project
219+
220+
We are sure that you definiately want to use mros2-esp32 into your onw ESP-IDF project!
59221

60-
The following examples are under development. untested.
61-
- pub_image
62-
- pub_long_string_sub_crc
222+
This section introduce how to realize it, assuming the project name is "hello_mros2" and the location is `~/esp/`.
63223

224+
### Create your own project
64225

65-
## build Examples
226+
Go to your own location and create the `hello_mros2` project.
227+
228+
```
229+
cd ~/esp
230+
idf.py create-project hello_mros2
231+
cd hello_mros2
66232
```
67-
cd workspace/[Example]/
68233

69-
/* M5Stack Basic / M5Stack Core2 */
70-
idf.py set-target esp32
234+
### Clone mros2-esp32
71235

72-
/* ESP32S3Dev / M5Stack CoreS3 */
73-
idf.py set-target esp32s3
236+
First, create `./components` and do `git clone` into it (`--recursive` is mandatory).
74237

75-
idf.py menuconfig
238+
```
239+
mkdir components
240+
cd components/
241+
git clone --recursive https://github.com/mROS-base/mros2-esp32
242+
```
76243

77-
/* in menuconfig */
78-
Component config -> LWIP -> IPv6 ->
244+
### Change file type of source code
79245

80-
/*Disable IPv6*/
81-
- [ ] IPv6 support (Disable)
82-
/* Save and Quit menuconfig */
246+
You need to change filename to `main/hello_mros2.c` to `main/hello.cpp` because you will use mros2 C++ APIs.
83247

84-
idf.py build
248+
```
249+
mv main/hello_mros2.c main/hello_mros2.cpp
250+
```
251+
252+
### Edit CMakeLists.txt
253+
254+
You need to edit `./CMakeLists.txt` and `./main/CMakeLists.txt` as the below.
255+
256+
- `./CMakeLists.txt`
257+
```
258+
cmake_minimum_required(VERSION 3.16)
259+
260+
add_compile_options(-w) # add
261+
262+
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
263+
project(hello_mros2)
264+
```
265+
- `./main/CMakeLists.txt`
266+
```
267+
idf_component_register(SRCS "hello_mros2.cpp" # edit
268+
INCLUDE_DIRS "."
269+
PRIV_REQUIRES "mros2-esp32") # add
270+
```
271+
272+
### Write your mros2 application
273+
274+
The fastest way is to copy from [./workspace/echoback_string/main/echoback_string.cpp](https://github.com/mROS-base/mros2-esp32/blob/main/workspace/echoback_string/main/echoback_string.cpp) :D
85275

86-
/* If an error occurs, try the following*/
87-
python -m pip install jinja2
88-
/* --- */
276+
```
277+
cd ~/esp/hello_mros2
278+
cp components/mros2-esp32/workspace/echoback_string/main/echoback_string.cpp main/hello_mros2.cpp
279+
```
280+
281+
### Setup your SSID and PASS in mros2 lib
89282

90-
idf.py -p [PORT] flash
283+
You need to SSID and PASS for your Wi-Fi AP in `components/mros2-esp32/platform/wifi/wifi.h` (be careful that we should not commit and push your network environment to the world :D)
91284

92-
idf.py -p [PORT] monitor
93-
/* To exit monitor, press Ctrl + ] */
285+
```platform/wifi/wifi.h
286+
#define ESP_WIFI_SSID "SSID"
287+
#define ESP_WIFI_PASS "PASS"
94288
```
95-
# Usage into your ESP-IDF project
96-
If you needs to use mros2 into your ESP-IDF project,
97-
clone this repository to ```components``` directory in your project.
98289
99-
mros2 needs network connection and setting of IP address.
100-
Please see [Wifi connection example](workspace/common/wifi).
101-
IP address setting find in upper section [Change IP address](#change-ip-address).
290+
### Then, set target, build, flash, and Run!!
291+
292+
The rest of operations follow from [this subsection on Quickstart](#set-target).
293+
294+
If you want to use your own customized message type followed by the ROS 2 manner, please refer to [mros2#generating-header-files-for-custom-msgtypes](https://github.com/mROS-base/mros2#generating-header-files-for-custom-msgtypes) section.
295+
296+
Enjoy your mros2-esp32 development life!! :tada:
297+
298+
## Submodules and Licenses
299+
300+
The source code of this repository itself is published under [Apache License 2.0](https://github.com/mROS-base/mros2/blob/main/LICENSE).
301+
Please note that this repository requires the following stacks as the submodules, and also check their Licenses.
302+
303+
- [mros2](https://github.com/mROS-base/mros2): the pub/sub APIs compatible with ROS 2 Rclcpp
304+
- [embeddedRTPS](https://github.com/mROS-base/embeddedRTPS): RTPS communication layer (including lwIP and Micro-CDR)
305+
- [ESP-IDF and FreeRTOS](https://github.com/espressif/esp-idf): Espressif IoT Development Framework. Official development framework for Espressif SoCs.
102306
103-
# Awesome resources!
307+
## Awesome resources!
104308
105309
The following are trial reports written by third-party users. We deeply appreciate your contributions! Of course, PR for adding your reports/articles, example of works are very welcome!!
106310

0 commit comments

Comments
 (0)