Update usocket.md

content/firmwareapi/micropython/usocket.md

@@ -22,24 +22,40 @@ Create a new socket using the given address family, socket type and protocol num
 Family type:
 * `socket.AF_INET`: For use with Internet protocols (WiFi, LTE, Ethernet)
 * `socket.AF_LORA`: For use with LoRa RAW or LoRaWAN.
-* `socket.AF_SIGFOX`: For use with SigFox.
+* `socket.AF_SIGFOX`: For use with Sigfox.
 Socket type:
-* `socket.SOCK_STREAM`:
-* `socket.SOCK_DGRAM`:
-* `socket.SOCK_RAW`:
-Socket protocols:
-* `socket.IPPROTO_UDP`: 
-* `socket.IPPROTO_TCP`: 
+* `socket.SOCK_STREAM`: Creates a stream socket (INET socket only, UDP protocol only).
+* `socket.SOCK_DGRAM`: Creates a datagram socket (INET socket only, TCP protocol only). 
+* `socket.SOCK_RAW`: A raw socket receives or sends the raw datagram not including link level headers (INET, LoRa and Sigfox)
+Socket protocol options:
+* `socket.IPPROTO_IP`
+* `socket.IPPROTO_ICMP`
+* `socket.IPPROTO_UDP`
+* `socket.IPPROTO_TCP`
+* `socket.IPPROTO_IPV6`
+* `socket.IP_ADD_MEMBERSHIP`
+* `socket.IPPROTO_RAW`: Only option for LoRa and Sigfox.
+
+By default, sockets are set to be blocking.
 
 ### socket.setsockopt(level, optname, value)
 
 Set the value of the given socket option. The needed symbolic constants are defined in the socket module (`SO_*` etc.). The value can be an integer or a bytes-like object representing a buffer. This function takes the following arguments:
-* `level`: The socket type, can take the following values:
+* `level`: The socket type, can take the following values. Select the socket option layer for the socket you're using:
     * `socket.SOL_SOCKET`
-    * `socket.SOL_LORA`:
+    * `socket.SOL_LORA`
     * `socket.SOL_SIGFOX`
 * `optname`: The option name, can take the following values, depending on the chosen socket level.
-    * `
+    * IP socket options: 
+        * `socket.SO_REUSEADDR`: Enable address reusing (Enabled by default)
+    * LoRa socket options: 
+        * `socket.SO_CONFIRMED`: Request a LoRa packet to be acknowledged by the network.
+        * `socket.SO_DR`: Set the datarate, see the [LoRa Socket API](/firmwareapi/pycom/network/lora/#working-with-lora-and-lorawan-sockets) for more information.
+    * Sigfox socket options: 
+        * `socket.SO_RX`: Wait for a downlink after sending the uplink packet
+        * `socket.SO_TX_REPEAT`: Repeat the transmitted packet 
+        * `socket.SO_OOB`: Use the socket to send a Sigfox Out Of Band (OOB) message
+        * `socket.SO_BIT`: Select the bit value when sending bit-only packets
 
 ### socket.getaddrinfo(host, port)
 
@@ -51,56 +67,56 @@ Translate the host/port argument into a sequence of 5-tuples that contain all th
 s = socket.socket()
 s.connect(socket.getaddrinfo('www.micropython.org', 80)[0][-1])
 ```
-
-### socket.close()
+## Socket methods
+### s.close()
 
 Mark the socket closed. Once that happens, all future operations on the socket object will fail. The remote end will receive no more data (after queued data is flushed).
 
 Sockets are automatically closed when they are garbage-collected, but it is recommended to `close()` them explicitly, or to use a with statement around them.
 
-### socket.bind(address)
+### s.bind(address)
 
 Bind the `socket` to `address`. The socket must not already be bound. The `address` parameter must be a tuple containing the IP address and the port.
 
 >In the case of LoRa sockets, the address parameter is simply an integer with the port number, for instance: `s.bind(1)`
 
-### socket.listen([backlog])
+### s.listen([backlog])
 
 Enable a server to accept connections. If backlog is specified, it must be at least 0 (if it's lower, it will be set to 0); and specifies the number of unaccepted connections that the system will allow before refusing new connections. If not specified, a default reasonable value is chosen.
 
-### socket.accept()
+### s.accept()
 
 Accept a connection. The socket must be bound to an address and listening for connections. The return value is a pair `(conn, address)` where `conn` is a new socket object usable to send and receive data on the connection, and `address` is the address bound to the socket on the other end of the connection.
 
-### socket.connect(address)
+### s.connect(address)
 
 Connect to a remote socket at `address`.
 
-### socket.send(bytes)
+### s.send(bytes)
 
 Send data to the socket. The socket must be connected to a remote socket.
 
-### socket.sendall(bytes)
+### s.sendall(bytes)
 
-Alias of `socket.send(bytes)`.
+Alias of `s.send(bytes)`.
 
-### socket.recv(bufsize)
+### s.recv(bufsize)
 
 Receive data from the socket. The return value is a bytes object representing the data received. The maximum amount of data to be received at once is specified by `bufsize`.
 
-### socket.sendto(bytes, address)
+### s.sendto(bytes, address)
 
 Send data to the socket. The socket should not be connected to a remote socket, since the destination socket is specified by address.
 
-### socket.recvfrom(bufsize)
+### s.recvfrom(bufsize)
 
 Receive data from the socket. The return value is a pair `(bytes, address)` where `bytes` is a bytes object representing the data received and `address` is the address of the socket sending the data.
 
-### socket.settimeout(value)
+### s.settimeout(value)
 
 Set a timeout on blocking socket operations. The value argument can be a nonnegative floating point number expressing seconds, or `None`. If a non-zero value is given, subsequent socket operations will raise a timeout exception if the timeout period value has elapsed before the operation has completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket is put in blocking mode.
 
-### socket.setblocking(flag)
+### s.setblocking(flag)
 
 Set blocking or non-blocking mode of the socket: if flag is false, the socket is set to non-blocking, else to blocking mode. This will override the timeout setting
 
@@ -108,11 +124,11 @@ This method is a shorthand for certain `settimeout()` calls:
 
 ```python
 
-sock.setblocking(True) is equivalent to sock.settimeout(None)
-sock.setblocking(False) is equivalent to sock.settimeout(0.0)
+s.setblocking(True) # is equivalent to s.settimeout(None)
+s.setblocking(False) #is equivalent to s.settimeout(0.0)
 ```
 
-### socket.makefile(mode='rb')
+### s.makefile(mode='rb')
 
 Return a file object associated with the socket. The exact returned type depends on the arguments given to makefile(). The support is limited to binary modes only (`rb` and `wb`). CPython's arguments: `encoding`, `errors`, and `newline` are not supported.
 
@@ -122,33 +138,33 @@ The socket must be in blocking mode; it can have a timeout, but the file object'
 >Closing the file object returned by `makefile()` **WILL** close the original socket as well.
 
 
-### socket.read(size)
+### s.read(size)
 
 Read up to size bytes from the socket. Return a bytes object. If `size` is not given, it behaves just like [`socket.readall()`](../usocket#socket-readall), see below.
 
-### socket.readall()
+### s.readall()
 
 Read all data available from the socket until EOF. This function will not return until the socket is closed.
 
-### socket.readinto(buf[, nbytes])
+### s.readinto(buf[, nbytes])
 
 Read bytes into the `buf`. If `nbytes` is specified then read at most that many bytes. Otherwise, read at most `len(buf)` bytes.
 
 Return value: number of bytes read and stored into `buf`.
 
-### socket.readline()
+### s.readline()
 
 Read a line, ending in a newline character.
 
 Return value: the line read.
 
-### socket.write(buf)
+### s.write(buf)
 
 Write the buffer of bytes to the socket.
 
 Return value: number of bytes written.
 
-### socket.do_handshake()
+### s.do_handshake()
 
 Perform the SSL handshake on the previously "wrapped" socket with ssl.wrap_socket().
 could be used when the socket is non-blocking and the SSL handshake is not performed during connect().
@@ -171,7 +187,7 @@ while not wlan.isconnected():
 print ("Wifi Connected")
 
 a = socket.getaddrinfo('www.postman-echo.com', 443)[0][-1]
-s= socket.socket()
+s = socket.socket()
 s.setblocking(False)
 s = ssl.wrap_socket(s)
 try:
@@ -206,13 +222,13 @@ to set primary and Backup DNS servers specify the Index and Ip Address.
 
 Example:
 
-```
+```python
 >>> socket.dnsserver()
 ('10.0.0.1', '8.8.8.8')
 ```
 Setting DNS servers:
 
-```
+```python
 >>> socket.dnsserver(1, '0.0.0.0')
 >>> socket.dnsserver()
 ('10.0.0.1', '0.0.0.0')
@@ -226,8 +242,8 @@ Setting DNS servers:
 
 * Family types: `socket.AF_INET`, `socket.AF_LORA`, `socket.AF_SIGFOX`
 * Socket types: `socket.SOCK_STREAM`, `socket.SOCK_DGRAM`, `socket.SOCK_RAW`
-* Socket protocols: `socket.IPPROTO_UDP`, `socket.IPPROTO_TCP`
+* Socket protocols: `socket.IPPROTO_IP`, `socket.IPPROTO_ICMP`, `socket.IPPROTO_UDP`, `socket.IPPROTO_TCP`, `socket.IPPROTO_IPV6`, `socket.IP_ADD_MEMBERSHIP`, `socket.IPPROTO_RAW`
 * Socket options layers: `socket.SOL_SOCKET`, `socket.SOL_LORA`, `socket.SOL_SIGFOX`
     * IP socket options: `socket.SO_REUSEADDR`
     * LoRa socket options: `socket.SO_CONFIRMED`, `socket.SO_DR`
-    * Sigfox socket options: `socket.SO_RX`, `socket.SO_TX_REPEAT`, `socket.SO_OOB`, `socket.SO_BIT`
+    * Sigfox socket options: `socket.SO_RX`, `socket.SO_TX_REPEAT`, `socket.SO_OOB`, `socket.SO_BIT`