1# OpenThread CLI - UDP Example
2
3The OpenThread UDP APIs may be invoked via the OpenThread CLI.
4
5## Quick Start
6
7### Form Network
8
9Form a network with at least two devices.
10
11### Node 1
12
13On node 1, open and bind the example UDP socket.
14
15```bash
16> udp open
17> udp bind :: 1234
18```
19
20The `::` specifies the IPv6 Unspecified Address.
21
22### Node 2
23
24On node 2, open the example UDP socket and send a simple message.
25
26```bash
27> udp open
28> udp send fdde:ad00:beef:0:bb1:ebd6:ad10:f33 1234 hello
29```
30
31### Result
32
33On node 1, you should see a print out similar to below:
34
35```bash
365 bytes from fdde:ad00:beef:0:dac3:6792:e2e:90d8 49153 hello
37```
38
39## Command List
40
41- [help](#help)
42- [bind](#bind-netif-ip-port)
43- [close](#close)
44- [connect](#connect-ip-port)
45- [linksecurity](#linksecurity)
46- [open](#open)
47- [send](#send-ip-port-message)
48
49## Command Details
50
51### help
52
53List the UDP CLI commands.
54
55```bash
56> udp help
57help
58bind
59close
60connect
61open
62send
63Done
64```
65
66### bind [netif] \<ip\> \<port\>
67
68Assigns a name (i.e. IPv6 address and port) to the example socket.
69
70- netif: the network interface to bind to.
71  - not specified: Thread network interface.
72  - `-u`: unspecified network interface.
73  - `-b`: Backbone network interface.
74- ip: the IPv6 address or the unspecified IPv6 address (`::`).
75- port: the UDP port
76
77```bash
78> udp bind :: 1234
79Done
80> udp bind -u :: 1234
81Done
82> udp bind -b :: 1234
83Done
84```
85
86### close
87
88Closes the example socket.
89
90```bash
91> udp close
92Done
93```
94
95### connect \<ip\> \<port\>
96
97Specifies the peer with which the socket is to be associated.
98
99- ip: the peer's IP address.
100- port: the peer's UDP port.
101
102```bash
103> udp connect fdde:ad00:beef:0:bb1:ebd6:ad10:f33 1234
104Done
105```
106
107The address can be an IPv4 address, which will be synthesized to an IPv6 address using the preferred NAT64 prefix from the network data.
108
109> Note: The command will return `InvalidState` when the preferred NAT64 prefix is unavailable.
110
111```bash
112> udp connect 172.17.0.1 1234
113Connecting to synthesized IPv6 address: fdde:ad00:beef:2:0:0:ac11:1
114Done
115```
116
117### linksecurity
118
119Indicates whether the link security is enabled or disabled.
120
121```bash
122> udp linksecurity
123Enabled
124Done
125```
126
127### linksecurity enable
128
129Enable link security.
130
131```bash
132> udp linksecurity enable
133Done
134```
135
136### linksecurity disable
137
138Disable link security.
139
140```bash
141> udp linksecurity disable
142Done
143```
144
145### open
146
147Opens the example socket.
148
149```bash
150> udp open
151Done
152```
153
154### send \<ip\> \<port\> \<message\>
155
156Send a UDP message.
157
158- ip: the destination address.
159- port: the UDP destination port.
160- message: the message to send.
161
162```bash
163> udp send fdde:ad00:beef:0:bb1:ebd6:ad10:f33 1234 hello
164Done
165```
166
167The address can be an IPv4 address, which will be synthesized to an IPv6 address using the preferred NAT64 prefix from the network data.
168
169> Note: The command will return `InvalidState` when the preferred NAT64 prefix is unavailable.
170
171```bash
172> udp send 172.17.0.1 1234 hello
173Sending to synthesized IPv6 address: fdde:ad00:beef:2:0:0:ac11:1
174Done
175```
176
177### send \<ip\> \<port\> \<type\> \<value\>
178
179Send a few bytes over UDP.
180
181- ip: the IPv6 destination address.
182- port: the UDP destination port.
183- type: the type of the message:
184  - `-t`: text payload in the `value`, same as without specifying the type.
185  - `-s`: autogenerated payload with specified length indicated in the `value`.
186  - `-x`: binary data in hexadecimal representation in the `value`.
187
188```bash
189> udp send fdde:ad00:beef:0:bb1:ebd6:ad10:f33 1234 -t hello
190Done
191
192> udp send fdde:ad00:beef:0:bb1:ebd6:ad10:f33 1234 -x 68656c6c6f
193Done
194
195> udp send fdde:ad00:beef:0:bb1:ebd6:ad10:f33 1234 -s 800
196Done
197
198```
199
200### send \<message\>
201
202Send a UDP message on a connected socket.
203
204- message: the message to send.
205
206```bash
207> udp send hello
208Done
209```
210
211### send \<type\> \<value\>
212
213Send a few bytes over UDP.
214
215- type: the type of the message:
216  - `-t`: text payload in the `value`, same as without specifying the type.
217  - `-s`: autogenerated payload with specified length indicated in the `value`.
218  - `-x`: binary data in hexadecimal representation in the `value`.
219
220```bash
221> udp send -t hello
222Done
223
224> udp send -x 68656c6c6f
225Done
226
227> udp send -s 800
228Done
229```
230