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 1, you should see a printout on node 1 similar to below: 35 36```bash 37TCP: Connection established 38``` 39 40In addition, you should also see a printout on node 2 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 1, you should see a printout on node 2 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) 62- [send](#send-message) 63- [benchmark](#benchmark-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 [\<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 89Done 90TCP Benchmark Complete: Transferred 73728 bytes in 7233 milliseconds 91TCP Goodput: 81.546 kb/s 92``` 93 94### bind \<ip\> \<port\> 95 96Associates a name (i.e. IPv6 address and port) to the example TCP endpoint. 97 98- ip: the IPv6 address or the unspecified IPv6 address (`::`). 99- port: the TCP port. 100 101```bash 102> tcp bind :: 30000 103Done 104``` 105 106### connect \<ip\> \<port\> 107 108Establishes a connection with the specified peer. 109 110If the connection establishment is successful, the resulting TCP connection is associated with the example TCP endpoint. 111 112- ip: the peer's IPv6 address. 113- port: the peer's TCP port. 114 115```bash 116> tcp connect fe80:0:0:0:a8df:580a:860:ffa4 30000 117Done 118TCP: Connection established 119``` 120 121### deinit 122 123Deinitializes the example TCP listener and the example TCP endpoint. 124 125```bash 126> tcp deinit 127Done 128``` 129 130### help 131 132List the TCP CLI commands. 133 134```bash 135> tcp help 136abort 137benchmark 138bind 139connect 140deinit 141help 142init 143listen 144send-message 145sendend 146stoplistening 147Done 148``` 149 150### init [\<size\>] 151 152Initializes the example TCP listener and the example TCP endpoint. 153 154- size: the size of the receive buffer to associate with the example TCP endpoint. If left unspecified, the maximum size is used. 155 156```bash 157> tcp init 158Done 159``` 160 161### listen \<ip\> \<port\> 162 163Uses the example TCP listener to listen for incoming connections on the specified name (i.e. IPv6 address and port). 164 165If 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. 166 167- ip: the IPv6 address or the unspecified IPv6 address (`::`). 168- port: the TCP port. 169 170```bash 171> tcp listen :: 30000 172Done 173``` 174 175### send \<message\> 176 177Send data over the TCP connection associated with the example TCP endpoint. 178 179- message: the message to send. 180 181```bash 182> tcp send hello 183Done 184``` 185 186### sendend 187 188Sends 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. 189 190```bash 191> tcp sendend 192Done 193``` 194 195### stoplistening 196 197Stops listening for incoming TCP connections using the example TCP listener. 198 199```bash 200> tcp stoplistening 201Done 202``` 203