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