Skip to content

Commit c921080

Browse files
chshuchshu
committed
Merge branch 'docs/add_trel' into 'main'
docs(thread-br): add documentation for TREL codelab See merge request espressif/esp-thread-br!147
2 parents ce091f0 + 264f08b commit c921080

File tree

2 files changed

+201
-0
lines changed

2 files changed

+201
-0
lines changed

‎docs/en/codelab/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,5 +10,6 @@
1010
service_discovery
1111
nat64
1212
web-gui
13+
trel
1314

1415

‎docs/en/codelab/trel.rst‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
*******************************************
2+
3.6. Thread Radio Encapsulation Link (TREL)
3+
*******************************************
4+
5+
TREL provides the mechanism for encapsulating IEEE 802.15.4 MAC frames
6+
within UDP/IPv6 packets. This encapsulation allows Thread messages to
7+
traverse IP-based networks while remaining compatible with existing Thread
8+
devices, once the Thread messages are again de-encapsulated from the
9+
UDP/IPv6 packet.
10+
11+
Prerequisites
12+
-------------
13+
14+
Hardware Prerequisites
15+
^^^^^^^^^^^^^^^^^^^^^^
16+
17+
To perform Thread Radio Encapsulation Link (TREL), the following devices are required:
18+
19+
- An ESP Thread Border Router (BR) flashed with the `Thread BR Example <https://github.com/espressif/esp-thread-br/blob/main/examples/basic_thread_border_router/README.md>`_
20+
- A Thread CLI device (e.g. ESP32-H2) flashed with the `Thread CLI Example <https://github.com/espressif/esp-idf/blob/master/examples/openthread/ot_cli/README.md>`_
21+
- A TREL enabled Wi-Fi device (e.g. ESP32-S3) flashed with the `TREL Example <https://github.com/espressif/esp-idf/blob/master/examples/openthread/ot_trel/README.md>`_
22+
23+
- Note that this TREL Wi-Fi device does not need to have built-in 802.15.4 capabilities
24+
25+
The Border Router and the Wi-Fi device shall be connected to the same Wi-Fi network and
26+
the Thread CLI device shall join the Thread network formed by the Border Router (refer to set up below for detailed instructions):
27+
28+
1. Thread BR connects to Wi-Fi network (refer to configuration below), forms a Thread network, and assumes the role of LEADER
29+
2. Thread CLI device joins Thread network formed by Thread BR
30+
3. TREL Wi-Fi device connects to the same Wi-Fi network, and joins the Thread network created by the BR using Thread CLI
31+
32+
Configuration
33+
^^^^^^^^^^^^^
34+
35+
The Thread BR should be configured to enable TREL feature, which can be found in:
36+
37+
.. code-block::
38+
39+
idf.py menuconfig
40+
→ Component config
41+
→ OpenThread
42+
→ OpenThread
43+
→ Thread Core Features
44+
→ Thread Trel Radio Link
45+
→ Enable Thread Radio Encapsulation Link (TREL)
46+
47+
Both the Thread BR and Wi-Fi device should be configured to join the same Wi-Fi network using:
48+
49+
.. code-block::
50+
51+
idf.py menuconfig
52+
→ Example Connection Configuration
53+
→ WiFi SSID
54+
idf.py menuconfig
55+
→ Example Connection Configuration
56+
→ WiFi Password
57+
58+
If users do not wish to provide Wi-Fi credentials via menuconfig, the credentials may also be
59+
provided at runtime via:
60+
61+
.. code-block::
62+
63+
> wifi connect -s <ssid> -p <psk>
64+
65+
Set up
66+
------
67+
68+
ESP Thread BR device
69+
^^^^^^^^^^^^^^^^^^^^
70+
71+
1. Build and flash the Thread BR Example on the ESP Thread BR device, and wait a few moments for it to connect to the Wi-Fi network automatically (if configured in ``menuconfig``).
72+
2. Check that the ESP Thread BR device is connected to the Wi-Fi network:
73+
74+
.. code-block::
75+
76+
> wifi state
77+
connected
78+
Done
79+
80+
3. Use the ESP Thread BR device to form a Thread network:
81+
82+
.. code-block::
83+
84+
> ifconfig up
85+
Done
86+
> thread start
87+
Done
88+
89+
4. Check that the ESP Thread BR device has assumed the role of LEADER in the Thread network:
90+
91+
.. code-block::
92+
93+
> state
94+
leader
95+
Done
96+
97+
5. Obtain the Thread network details for use later:
98+
99+
.. code-block::
100+
101+
> dataset active -x
102+
0e080000000000010000000300001835060004001fffe00208fe7bb701f5f1125d0708fd75cbde7c6647bd0510b3914792d44f45b6c7d76eb9306eec94030f4f70656e5468726561642d35383332010258320410e35c581af5029b054fc904a24c2b27700c0402a0fff8
103+
104+
Thread CLI device
105+
^^^^^^^^^^^^^^^^^
106+
107+
6. Build and flash the Thread CLI Example on the Thread CLI device.
108+
7. Set the Thread network details on the Thread CLI device, and wait a few moments for it to join the Thread network:
109+
110+
.. code-block::
111+
112+
> dataset set active 0e080000000000010000000300001835060004001fffe00208fe7bb701f5f1125d0708fd75cbde7c6647bd0510b3914792d44f45b6c7d76eb9306eec94030f4f70656e5468726561642d35383332010258320410e35c581af5029b054fc904a24c2b27700c0402a0fff8
113+
> ifconfig up
114+
Done
115+
> thread start
116+
Done
117+
118+
8. Check that the Thread CLI device has joined the Thread network and assumed the role of ROUTER or CHILD:
119+
120+
.. code-block::
121+
122+
> state
123+
router # child is also a valid state
124+
Done
125+
126+
TREL enabled Wi-Fi device
127+
^^^^^^^^^^^^^^^^^^^^^^^^^
128+
129+
9. Build and flash the TREL Example on the TREL enabled Wi-Fi device, and wait a few moments for it to connect to the Wi-Fi network automatically (if configured in ``menuconfig``).
130+
10. Check that the TREL enabled Wi-Fi device is connected to the Wi-Fi network:
131+
132+
.. code-block::
133+
134+
> wifi state
135+
connected
136+
Done
137+
138+
11. Set the Thread network details on the TREL enabled Wi-Fi device, and wait a few moments for it to join the Thread network:
139+
140+
.. code-block::
141+
142+
> dataset set active 0e080000000000010000000300001835060004001fffe00208fe7bb701f5f1125d0708fd75cbde7c6647bd0510b3914792d44f45b6c7d76eb9306eec94030f4f70656e5468726561642d35383332010258320410e35c581af5029b054fc904a24c2b27700c0402a0fff8
143+
> ifconfig up
144+
Done
145+
> thread start
146+
Done
147+
148+
12. Check that the Thread CLI device has joined the Thread network and assumed the role of ROUTER or CHILD:
149+
150+
.. code-block::
151+
152+
> state
153+
router # child is also a valid state
154+
Done
155+
156+
Validate the Connection between Wi-Fi device and Thread CLI device
157+
------------------------------------------------------------------
158+
159+
If the Wi-Fi device has been set up correctly to join the same Thread network as the Thread BR
160+
and CLI device, it should be possible to ping the Thread CLI device from the Wi-Fi device (and
161+
vice versa).
162+
163+
Obtain IPv6 address of Thread CLI device:
164+
165+
.. code-block::
166+
167+
> ipaddr mleid
168+
169+
fd14:c8eb:d14c:5fbe:b57e:1e02:a532:26d1
170+
Done
171+
172+
Obtain IPv6 address of Wi-Fi device:
173+
174+
.. code-block::
175+
176+
> ipaddr mleid
177+
178+
fd14:c8eb:d14c:5fbe:bd5e:16de:3183:694a
179+
Done
180+
181+
Ping Wi-Fi device from Thread CLI device:
182+
183+
.. code-block::
184+
185+
> ping fd14:c8eb:d14c:5fbe:bd5e:16de:3183:694a
186+
187+
16 bytes from fd14:c8eb:d14c:5fbe:bd5e:16de:3183:694a: icmp_seq=1 hlim=255 time=122ms
188+
1 packets transmitted, 1 packets received. Packet loss = 0.0%. Round-trip min/avg/max = 122/122.0/122 ms.
189+
Done
190+
191+
Ping Thread CLI device from Wi-Fi device:
192+
193+
.. code-block::
194+
195+
> ping fd14:c8eb:d14c:5fbe:b57e:1e02:a532:26d1
196+
197+
16 bytes from fd14:c8eb:d14c:5fbe:b57e:1e02:a532:26d1: icmp_seq=1 hlim=255 time=562ms
198+
1 packets transmitted, 1 packets received. Packet loss = 0.0%. Round-trip min/avg/max = 562/562.0/562 ms.
199+
Done
200+

0 commit comments

Comments
 (0)