1# OpenThread CLI - TCP Example 2 3The OpenThread TCP 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, initialize the TCP CLI module and listen for incoming connections using the example TCP listener. 14 15```bash 16> tcp init 17> tcp listen :: 30000 18``` 19 20The `::` specifies the IPv6 Unspecified Address. 21 22### Node 2 23 24On node 2, initialize the TCP CLI module, connect to node 1, and send a simple message. 25 26```bash 27> tcp init 28> tcp connect fe80:0:0:0:a8df:580a:860:ffa4 30000 29> tcp send hello 30``` 31 32### Result 33 34After running the `tcp connect` command on node 2, you should see a printout on node 2 similar to below: 35 36```bash 37TCP: Connection established 38``` 39 40In addition, you should also see a printout on node 1 similar to below: 41 42```bash 43Accepted connection from [fe80:0:0:0:8f3:f602:bf9b:52f2]:49152 44TCP: Connection established 45``` 46 47After running the `tcp send` command on node 2, you should see a printout on node 1 similar to below: 48 49```bash 50TCP: Received 5 bytes: hello 51``` 52 53For a more in-depth example, see [this video](https://youtu.be/ppZ784YUKlI). 54 55## Command List 56 57- [help](#help) 58- [init](#init-size) 59- [deinit](#deinit) 60- [bind](#bind-ip-port) 61- [connect](#connect-ip-port-fastopen) 62- [send](#send-message) 63- [benchmark](#benchmark-run-size) 64- [sendend](#sendend) 65- [abort](#abort) 66- [listen](#listen-ip-port) 67- [stoplistening](#stoplistening) 68 69## Command Details 70 71### abort 72 73Unceremoniously ends the TCP connection, if one exists, associated with the example TCP endpoint, transitioning the TCP endpoint to the closed state. 74 75```bash 76> tcp abort 77TCP: Connection reset 78Done 79``` 80 81### benchmark run [\<size\>] 82 83Transfers the specified number of bytes using the TCP connection currently associated with the example TCP endpoint (this TCP connection must be established before using this command). 84 85- size: the number of bytes to send for the benchmark. If it is left unspecified, the default size is used. 86 87```bash 88> tcp benchmark run 89Done 90TCP Benchmark Complete: Transferred 73728 bytes in 7233 milliseconds 91TCP Goodput: 81.546 kb/s 92``` 93 94### benchmark result 95 96Get the last result of TCP benchmark. If the benchmark is ongoing, it will show that benchmark is ongoing. This command is used for test scripts which automate the tcp benchmark test. 97 98``` 99> tcp benchmark result 100TCP Benchmark Status: Ongoing 101Done 102 103> tcp benchmark result 104TCP Benchmark Status: Completed 105TCP Benchmark Complete: Transferred 73728 bytes in 7056 milliseconds 106TCP Goodput: 83.592 kb/s 107``` 108 109### bind \<ip\> \<port\> 110 111Associates a name (i.e. IPv6 address and port) to the example TCP endpoint. 112 113- ip: the IPv6 address or the unspecified IPv6 address (`::`). 114- port: the TCP port. 115 116```bash 117> tcp bind :: 30000 118Done 119``` 120 121### connect \<ip\> \<port\> [\<fastopen\>] 122 123Establishes a connection with the specified peer. 124 125If the connection establishment is successful, the resulting TCP connection is associated with the example TCP endpoint. 126 127- ip: the peer's IP address. 128- port: the peer's TCP port. 129- fastopen: if "fast", TCP Fast Open is enabled for this connection; if "slow", it is not. Defaults to "slow". 130 131```bash 132> tcp connect fe80:0:0:0:a8df:580a:860:ffa4 30000 133Done 134TCP: Connection established 135``` 136 137The address can be an IPv4 address, which will be synthesized to an IPv6 address using the preferred NAT64 prefix from the network data. 138 139> Note: The command will return `InvalidState` when the preferred NAT64 prefix is unavailable. 140 141```bash 142> tcp connect 172.17.0.1 1234 143Connecting to synthesized IPv6 address: fdde:ad00:beef:2:0:0:ac11:1 144Done 145``` 146 147### deinit 148 149Deinitializes the example TCP listener and the example TCP endpoint. 150 151```bash 152> tcp deinit 153Done 154``` 155 156### help 157 158List the TCP CLI commands. 159 160```bash 161> tcp help 162abort 163benchmark 164bind 165connect 166deinit 167help 168init 169listen 170send-message 171sendend 172stoplistening 173Done 174``` 175 176### init [\<mode\>] [\<size\>] 177 178Initializes the example TCP listener and the example TCP endpoint. 179 180- mode: this specifies the buffering strategy and whether to use TLS. The possible values are "linked", "circular" (default), and "tls". 181- size: the size of the receive buffer to associate with the example TCP endpoint. If left unspecified, the maximum size is used. 182 183If "tls" is used, then the TLS protocol will be used for the connection (on top of TCP). When communicating over TCP between two nodes, either both should use TLS or neither should (a non-TLS endpoint cannot communicate with a TLS endpoint). The first two options, "linked" and "circular", specify that TLS should not be used and specify a buffering strategy to use with TCP; two endpoints of a TCP connection may use different buffering strategies. 184 185The behaviors of "linked" and "circular" buffering are identical, but the option is provided so that users of TCP can inspect the code to see an example of using the two buffering strategies. 186 187```bash 188> tcp init tls 189Done 190``` 191 192### listen \<ip\> \<port\> 193 194Uses the example TCP listener to listen for incoming connections on the specified name (i.e. IPv6 address and port). 195 196If no TCP connection is associated with the example TCP endpoint, then any incoming connections matching the specified name are accepted and associated with the example TCP endpoint. 197 198- ip: the IPv6 address or the unspecified IPv6 address (`::`). 199- port: the TCP port. 200 201```bash 202> tcp listen :: 30000 203Done 204``` 205 206### send \<message\> 207 208Send data over the TCP connection associated with the example TCP endpoint. 209 210- message: the message to send. 211 212```bash 213> tcp send hello 214Done 215``` 216 217### sendend 218 219Sends the "end of stream" signal (i.e., FIN segment) over the TCP connection associated with the example TCP endpoint. This promises the peer that no more data will be sent to it over this TCP connection. 220 221```bash 222> tcp sendend 223Done 224``` 225 226### stoplistening 227 228Stops listening for incoming TCP connections using the example TCP listener. 229 230```bash 231> tcp stoplistening 232Done 233``` 234