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 unicast 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> Note: to receive datagrams sent to a multicast IPv6 address, the unspecified IPv6 address must be used. Using a multicast address for the \<ip\> argument is not supported. Also, the node must subscribe to the multicast group using `ipmaddr add` before it can receive UDP multicast. 87 88### close 89 90Closes the example socket. 91 92```bash 93> udp close 94Done 95``` 96 97### connect \<ip\> \<port\> 98 99Specifies the peer with which the socket is to be associated. 100 101- ip: the peer's IP address. 102- port: the peer's UDP port. 103 104```bash 105> udp connect fdde:ad00:beef:0:bb1:ebd6:ad10:f33 1234 106Done 107``` 108 109The address can be an IPv4 address, which will be synthesized to an IPv6 address using the preferred NAT64 prefix from the network data. 110 111> Note: The command will return `InvalidState` when the preferred NAT64 prefix is unavailable. 112 113```bash 114> udp connect 172.17.0.1 1234 115Connecting to synthesized IPv6 address: fdde:ad00:beef:2:0:0:ac11:1 116Done 117``` 118 119### linksecurity 120 121Indicates whether the link security is enabled or disabled. 122 123```bash 124> udp linksecurity 125Enabled 126Done 127``` 128 129### linksecurity enable 130 131Enable link security. 132 133```bash 134> udp linksecurity enable 135Done 136``` 137 138### linksecurity disable 139 140Disable link security. 141 142```bash 143> udp linksecurity disable 144Done 145``` 146 147### open 148 149Opens the example socket. 150 151```bash 152> udp open 153Done 154``` 155 156### send \<ip\> \<port\> \<message\> 157 158Send a UDP message. 159 160- ip: the destination address. 161- port: the UDP destination port. 162- message: the message to send. 163 164```bash 165> udp send fdde:ad00:beef:0:bb1:ebd6:ad10:f33 1234 hello 166Done 167``` 168 169The address can be an IPv4 address, which will be synthesized to an IPv6 address using the preferred NAT64 prefix from the network data. 170 171> Note: The command will return `InvalidState` when the preferred NAT64 prefix is unavailable. 172 173```bash 174> udp send 172.17.0.1 1234 hello 175Sending to synthesized IPv6 address: fdde:ad00:beef:2:0:0:ac11:1 176Done 177``` 178 179### send \<ip\> \<port\> \<type\> \<value\> 180 181Send a few bytes over UDP. 182 183- ip: the IPv6 destination address. 184- port: the UDP destination port. 185- type: the type of the message: 186 - `-t`: text payload in the `value`, same as without specifying the type. 187 - `-s`: autogenerated payload with specified length indicated in the `value`. 188 - `-x`: binary data in hexadecimal representation in the `value`. 189 190```bash 191> udp send fdde:ad00:beef:0:bb1:ebd6:ad10:f33 1234 -t hello 192Done 193 194> udp send fdde:ad00:beef:0:bb1:ebd6:ad10:f33 1234 -x 68656c6c6f 195Done 196 197> udp send fdde:ad00:beef:0:bb1:ebd6:ad10:f33 1234 -s 800 198Done 199 200``` 201 202### send \<message\> 203 204Send a UDP message on a connected socket. 205 206- message: the message to send. 207 208```bash 209> udp send hello 210Done 211``` 212 213### send \<type\> \<value\> 214 215Send a few bytes over UDP. 216 217- type: the type of the message: 218 - `-t`: text payload in the `value`, same as without specifying the type. 219 - `-s`: autogenerated payload with specified length indicated in the `value`. 220 - `-x`: binary data in hexadecimal representation in the `value`. 221 222```bash 223> udp send -t hello 224Done 225 226> udp send -x 68656c6c6f 227Done 228 229> udp send -s 800 230Done 231``` 232