tinygo.org/x/drivers@v0.27.1-0.20240509133757-7dbca2a54349/README-net.md (about) 1 ### Table of Contents 2 3 - ["net" Package](#net-package) 4 - [Using "net" Package](#using-net-package) 5 - [Using "net/http" Package](#using-nethttp-package) 6 - [Using "crypto/tls" Package](#using-cryptotls-package) 7 - [Using Sockets](#using-sockets) 8 9 ## "net" Package 10 11 TinyGo's "net" package is ported from Go. The port offers a subset of Go's 12 "net" package. The subset maintains Go 1 compatiblity guarantee. A Go 13 application that uses "net" will most-likey just work on TinyGo if the usage is 14 within the subset offered. (There may be external constraints such as limited 15 SRAM on some targets that may limit full "net" functionality). 16 17 Continue below for details on using "net" and "net/http" packages. 18 19 See src/net/READMD.md in the TinyGo repo for more details on maintaining 20 TinyGo's "net" package. 21 22 ## Using "net" Package 23 24 Ideally, TinyGo's "net" package would be Go's "net" package and applications 25 using "net" would just work, as-is. TinyGo's net package is a partial port of 26 Go's net package, so some things may not work because they have not been 27 ported. 28 29 There are a few features excluded during the porting process, in particular: 30 31 - No IPv6 support 32 - No DualStack support 33 34 Run ```go doc -all ./src/net``` in TinyGo repo to see full listing of what has 35 been ported. Here is a list of things known to work. You can find examples 36 of these at [examples/net](examples/net/). 37 38 ### What is Known to Work 39 40 (These are all IPv4 only). 41 42 - TCP client and server 43 - UDP client 44 - TLS client 45 - HTTP client and server 46 - HTTPS client 47 - NTP client (UDP) 48 - MQTT client (paho & natiu) 49 - WebSocket client and server 50 51 Multiple sockets can be opened in a single app. For example, the app could run 52 as an http server listen on port :80 and also use NTP to get the current time 53 or send something over MQTT. There is a practical limit to the number of 54 active sockets per app, around 8 or 10, so don't go crazy. 55 56 Applications using Go's net package will need a few setup steps to work with 57 TinyGo's net package. The steps are required before using "net". 58 59 ### Step 1: Probe to Load Network Driver 60 61 Call Probe() to load the correct network driver for your target. Probe() 62 allows the app to work on multiple targets. 63 64 ```go 65 package main 66 67 import ( 68 "tinygo.org/x/drivers/netlink/probe" 69 ) 70 71 func main() { 72 73 // load network driver for target 74 link, dev := probe.Probe() 75 76 ... 77 } 78 ``` 79 80 Probe() will load the driver with default configuration for the target. For 81 custom configuration, the app can open code Probe() for the target 82 requirements. 83 84 Probe() returns a [Netlinker](netlink/README.md) and a 85 [Netdever](netdev/README.md), interfaces implemented by the network driver. 86 Next, we'll use the Netlinker interface to connect the target to an IP network. 87 88 ### Step 2: Connect to an IP Network 89 90 Before the net package is fully functional, we need to connect the target to an 91 IP network. 92 93 ```go 94 package main 95 96 import ( 97 "tinygo.org/x/drivers/netlink" 98 "tinygo.org/x/drivers/netlink/probe" 99 ) 100 101 func main() { 102 103 // load network driver for target 104 link, _ := probe.Probe() 105 106 // Connect target to IP network 107 link.NetConnect(&netlink.ConnectParams{ 108 Ssid: "my SSID", 109 Passphrase: "my passphrase", 110 }) 111 112 // OK to use "net" from here on 113 ... 114 } 115 ``` 116 117 Optionally, get notified of IP network connects and disconnects: 118 119 ```go 120 link.Notify(func(e netlink.Event) { 121 switch e { 122 case netlink.EventNetUp: println("Network UP") 123 case netlink.EventNetDown: println("Network DOWN") 124 }) 125 ``` 126 127 Here is an example of an http server listening on port :8080: 128 129 ```go 130 package main 131 132 import ( 133 "fmt" 134 "net/http" 135 136 "tinygo.org/x/drivers/netlink" 137 "tinygo.org/x/drivers/netlink/probe" 138 ) 139 140 func HelloServer(w http.ResponseWriter, r *http.Request) { 141 fmt.Fprintf(w, "Hello, %s!", r.URL.Path[1:]) 142 } 143 144 func main() { 145 146 // load network driver for target 147 link, _ := probe.Probe() 148 149 // Connect target to IP network 150 link.NetConnect(&netlink.ConnectParams{ 151 Ssid: "my SSID", 152 Passphrase: "my passphrase", 153 }) 154 155 // Serve it up 156 http.HandleFunc("/", HelloServer) 157 http.ListenAndServe(":8080", nil) 158 } 159 ``` 160 161 ## Using "net/http" Package 162 163 TinyGo's net/http package is a partial port of Go's net/http package, providing 164 a subset of the full net/http package. There are a few features excluded 165 during the porting process, in particular: 166 167 - No HTTP/2 support 168 - No TLS support for HTTP servers (no https servers) 169 - HTTP client request can't be reused 170 171 HTTP client methods (http.Get, http.Head, http.Post, and http.PostForm) are 172 functional. Dial clients support both HTTP and HTTPS URLs. 173 174 HTTP server methods and objects are mostly ported, but for HTTP only; HTTPS 175 servers are not supported. 176 177 HTTP request and response handling code is mostly ported, so most the intricacy 178 of parsing and writing headers is handled as in the full net/http package. 179 180 Run ```go doc -all ./src/net/http``` in TinyGo repo to see full listing. 181 182 ## Using "crypto/tls" Package 183 184 TinyGo's TLS support (crypto/tls) relies on hardware offload of the TLS 185 protocol. This is different from Go's crypto/tls package which handles the TLS 186 protocol in software. 187 188 TinyGo's TLS support is only available for client applications. You can 189 http.Get() to an https:// address, but you cannot http.ListenAndServeTLS() an 190 https server. 191 192 The offloading hardware has pre-defined TLS certificates built-in. 193 194 ## Using Sockets 195 196 The Netdever interface is a BSD socket-like interface so an application can make direct 197 socket calls, bypassing the "net" package for the lowest overhead. 198 199 Here is a simple TCP client application using direct sockets: 200 201 ```go 202 package main 203 204 import ( 205 "net" // only need to parse IP address 206 207 "tinygo.org/x/drivers/netdev" 208 "tinygo.org/x/drivers/netlink" 209 "tinygo.org/x/drivers/netlink/probe" 210 ) 211 212 func main() { 213 214 // load network driver for target 215 link, dev := probe.Probe() 216 217 // Connect target to IP network 218 link.NetConnect(&netlink.ConnectParams{ 219 Ssid: "my SSID", 220 Passphrase: "my passphrase", 221 }) 222 223 // omit error handling 224 225 sock, _ := dev.Socket(netdev.AF_INET, netdev.SOCK_STREAM, netdev.IPPROTO_TCP) 226 227 dev.Connect(sock, "", net.ParseIP("10.0.0.100"), 8080) 228 dev.Send(sock, []bytes("hello"), 0, 0) 229 230 dev.Close(sock) 231 link.NetDisconnect() 232 } 233 ```