diff options
Diffstat (limited to 'docs/library')
| -rw-r--r-- | docs/library/network.rst | 38 | ||||
| -rw-r--r-- | docs/library/pyb.Accel.rst | 1 | ||||
| -rw-r--r-- | docs/library/pyb.CAN.rst | 1 | ||||
| -rw-r--r-- | docs/library/pyb.LCD.rst | 1 | ||||
| -rw-r--r-- | docs/library/pyb.Switch.rst | 1 | ||||
| -rw-r--r-- | docs/library/pyb.USB_HID.rst | 1 | ||||
| -rw-r--r-- | docs/library/pyb.USB_VCP.rst | 1 | ||||
| -rw-r--r-- | docs/library/ure.rst | 2 | ||||
| -rw-r--r-- | docs/library/uselect.rst | 10 | ||||
| -rw-r--r-- | docs/library/usocket.rst | 59 | ||||
| -rw-r--r-- | docs/library/ussl.rst | 14 |
11 files changed, 100 insertions, 29 deletions
diff --git a/docs/library/network.rst b/docs/library/network.rst index def6bee74..99a7c242c 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -72,8 +72,7 @@ parameter should be `id`. connection parameters. For various medium types, there are different sets of predefined/recommended parameters, among them: - * WiFi: *bssid* keyword to connect by BSSID (MAC address) instead - of access point name + * WiFi: *bssid* keyword to connect to a specific BSSID (MAC address) .. method:: disconnect() @@ -225,7 +224,9 @@ parameter should be `id`. ============== This class allows you to control WIZnet5x00 Ethernet adaptors based on - the W5200 and W5500 chipsets (only W5200 tested). + the W5200 and W5500 chipsets. The particular chipset that is supported + by the firmware is selected at compile-time via the MICROPY_PY_WIZNET5K + option. Example usage:: @@ -269,6 +270,11 @@ parameter should be `id`. Methods ------- + .. method:: wiznet5k.isconnected() + + Returns ``True`` if the physical Ethernet link is connected and up. + Returns ``False`` otherwise. + .. method:: wiznet5k.ifconfig([(ip, subnet, gateway, dns)]) Get/set IP address, subnet mask, gateway and DNS. @@ -333,9 +339,12 @@ parameter should be `id`. argument is passed. Otherwise, query current state if no argument is provided. Most other methods require active interface. - .. method:: wlan.connect(ssid, password) + .. method:: wlan.connect(ssid=None, password=None, \*, bssid=None) Connect to the specified wireless network, using the specified password. + If *bssid* is given then the connection will be restricted to the + access-point with that MAC address (the *ssid* must also be specified + in this case). .. method:: wlan.disconnect() @@ -413,16 +422,17 @@ parameter should be `id`. Following are commonly supported parameters (availability of a specific parameter depends on network technology type, driver, and `MicroPython port`). - ========= =========== - Parameter Description - ========= =========== - mac MAC address (bytes) - essid WiFi access point name (string) - channel WiFi channel (integer) - hidden Whether ESSID is hidden (boolean) - authmode Authentication mode supported (enumeration, see module constants) - password Access password (string) - ========= =========== + ============= =========== + Parameter Description + ============= =========== + mac MAC address (bytes) + essid WiFi access point name (string) + channel WiFi channel (integer) + hidden Whether ESSID is hidden (boolean) + authmode Authentication mode supported (enumeration, see module constants) + password Access password (string) + dhcp_hostname The DHCP hostname to use + ============= =========== diff --git a/docs/library/pyb.Accel.rst b/docs/library/pyb.Accel.rst index 061996485..9ade5c5c8 100644 --- a/docs/library/pyb.Accel.rst +++ b/docs/library/pyb.Accel.rst @@ -1,4 +1,5 @@ .. currentmodule:: pyb +.. _pyb.Accel: class Accel -- accelerometer control ==================================== diff --git a/docs/library/pyb.CAN.rst b/docs/library/pyb.CAN.rst index 9e71f12b0..232d04d96 100644 --- a/docs/library/pyb.CAN.rst +++ b/docs/library/pyb.CAN.rst @@ -1,4 +1,5 @@ .. currentmodule:: pyb +.. _pyb.CAN: class CAN -- controller area network communication bus ====================================================== diff --git a/docs/library/pyb.LCD.rst b/docs/library/pyb.LCD.rst index 83cf890b6..5ab127edc 100644 --- a/docs/library/pyb.LCD.rst +++ b/docs/library/pyb.LCD.rst @@ -1,4 +1,5 @@ .. currentmodule:: pyb +.. _pyb.LCD: class LCD -- LCD control for the LCD touch-sensor pyskin ======================================================== diff --git a/docs/library/pyb.Switch.rst b/docs/library/pyb.Switch.rst index 0d5dc63b7..e5ab6bd84 100644 --- a/docs/library/pyb.Switch.rst +++ b/docs/library/pyb.Switch.rst @@ -1,4 +1,5 @@ .. currentmodule:: pyb +.. _pyb.Switch: class Switch -- switch object ============================= diff --git a/docs/library/pyb.USB_HID.rst b/docs/library/pyb.USB_HID.rst index 7d17c3099..702704435 100644 --- a/docs/library/pyb.USB_HID.rst +++ b/docs/library/pyb.USB_HID.rst @@ -1,4 +1,5 @@ .. currentmodule:: pyb +.. _pyb.USB_HID: class USB_HID -- USB Human Interface Device (HID) ================================================= diff --git a/docs/library/pyb.USB_VCP.rst b/docs/library/pyb.USB_VCP.rst index 4c4fe4516..80cc40cdd 100644 --- a/docs/library/pyb.USB_VCP.rst +++ b/docs/library/pyb.USB_VCP.rst @@ -1,4 +1,5 @@ .. currentmodule:: pyb +.. _pyb.USB_VCP: class USB_VCP -- USB virtual comm port ====================================== diff --git a/docs/library/ure.rst b/docs/library/ure.rst index 67f4f54a1..ebae1db5f 100644 --- a/docs/library/ure.rst +++ b/docs/library/ure.rst @@ -34,6 +34,8 @@ Supported operators are: ``'+?'`` +``'|'`` + ``'()'`` Grouping. Each group is capturing (a substring it captures can be accessed with `match.group()` method). diff --git a/docs/library/uselect.rst b/docs/library/uselect.rst index e330207db..beffce69a 100644 --- a/docs/library/uselect.rst +++ b/docs/library/uselect.rst @@ -66,12 +66,18 @@ Methods Tuples returned may contain more than 2 elements as described above. -.. method:: poll.ipoll([timeout]) +.. method:: poll.ipoll(timeout=-1, flags=0) Like :meth:`poll.poll`, but instead returns an iterator which yields - callee-owned tuples. This function provides efficient, allocation-free + `callee-owned tuples`. This function provides efficient, allocation-free way to poll on streams. + If *flags* is 1, one-shot behavior for events is employed: streams for + which events happened, event mask will be automatically reset (equivalent + to ``poll.modify(obj, 0)``), so new events for such a stream won't be + processed until new mask is set with `poll.modify()`. This behavior is + useful for asynchronous I/O schedulers. + .. admonition:: Difference to CPython :class: attention diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index dfdcd68bc..fab05b652 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -68,7 +68,16 @@ Functions .. function:: socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP) - Create a new socket using the given address family, socket type and protocol number. + Create a new socket using the given address family, socket type and + protocol number. Note that specifying *proto* in most cases is not + required (and not recommended, as some MicroPython ports may omit + ``IPPROTO_*`` constants). Instead, *type* argument will select needed + protocol automatically:: + + # Create STREAM TCP socket + socket(AF_INET, SOCK_STREAM) + # Create DGRAM UDP socket + socket(AF_INET, SOCK_DGRAM) .. function:: getaddrinfo(host, port) @@ -80,8 +89,8 @@ Functions The following example shows how to connect to a given url:: - s = socket.socket() - s.connect(socket.getaddrinfo('www.micropython.org', 80)[0][-1]) + s = usocket.socket() + s.connect(usocket.getaddrinfo('www.micropython.org', 80)[0][-1]) .. admonition:: Difference to CPython :class: attention @@ -96,13 +105,29 @@ Functions from an exception object). The use of negative values is a provisional detail which may change in the future. +.. function:: inet_ntop(af, bin_addr) + + Convert a binary network address *bin_addr* of the given address family *af* + to a textual representation:: + + >>> usocket.inet_ntop(usocket.AF_INET, b"\x7f\0\0\1") + '127.0.0.1' + +.. function:: inet_pton(af, txt_addr) + + Convert a textual network address *txt_addr* of the given address family *af* + to a binary representation:: + + >>> usocket.inet_pton(usocket.AF_INET, "1.2.3.4") + b'\x01\x02\x03\x04' + Constants --------- .. data:: AF_INET AF_INET6 - Address family types. Availability depends on a particular board. + Address family types. Availability depends on a particular `MicroPython port`. .. data:: SOCK_STREAM SOCK_DGRAM @@ -112,7 +137,11 @@ Constants .. data:: IPPROTO_UDP IPPROTO_TCP - IP protocol numbers. + IP protocol numbers. Availability depends on a particular `MicroPython port`. + Note that you don't need to specify these in a call to `usocket.socket()`, + because `SOCK_STREAM` socket type automatically selects `IPPROTO_TCP`, and + `SOCK_DGRAM` - `IPPROTO_UDP`. Thus, the only real use of these constants + is as an argument to `setsockopt()`. .. data:: usocket.SOL_* @@ -208,12 +237,30 @@ Methods .. method:: socket.settimeout(value) + **Note**: Not every port supports this method, see below. + 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 an `OSError` 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. + Not every `MicroPython port` supports this method. A more portable and + generic solution is to use `uselect.poll` object. This allows to wait on + multiple objects at the same time (and not just on sockets, but on generic + stream objects which support polling). Example:: + + # Instead of: + s.settimeout(1.0) # time in seconds + s.read(10) # may timeout + + # Use: + poller = uselect.poll() + poller.register(s, uselect.POLLIN) + res = poller.poll(1000) # time in milliseconds + if not res: + # s is still not ready for input, i.e. operation timed out + .. admonition:: Difference to CPython :class: attention @@ -281,7 +328,7 @@ Methods Return value: number of bytes written. -.. exception:: socket.error +.. exception:: usocket.error MicroPython does NOT have this exception. diff --git a/docs/library/ussl.rst b/docs/library/ussl.rst index c71b283cc..3ec609f67 100644 --- a/docs/library/ussl.rst +++ b/docs/library/ussl.rst @@ -13,7 +13,7 @@ facilities for network sockets, both client-side and server-side. Functions --------- -.. function:: ssl.wrap_socket(sock, server_side=False, keyfile=None, certfile=None, cert_reqs=CERT_NONE, ca_certs=None) +.. function:: ussl.wrap_socket(sock, server_side=False, keyfile=None, certfile=None, cert_reqs=CERT_NONE, ca_certs=None) Takes a stream *sock* (usually usocket.socket instance of ``SOCK_STREAM`` type), and returns an instance of ssl.SSLSocket, which wraps the underlying stream in @@ -23,12 +23,12 @@ Functions server-side SSL socket should be created from a normal socket returned from `accept()` on a non-SSL listening server socket. - Depending on the underlying module implementation for a particular board, - some or all keyword arguments above may be not supported. + Depending on the underlying module implementation in a particular + `MicroPython port`, some or all keyword arguments above may be not supported. .. warning:: - Some implementations of ``ssl`` module do NOT validate server certificates, + Some implementations of ``ussl`` module do NOT validate server certificates, which makes an SSL connection established prone to man-in-the-middle attacks. Exceptions @@ -41,8 +41,8 @@ Exceptions Constants --------- -.. data:: ssl.CERT_NONE - ssl.CERT_OPTIONAL - ssl.CERT_REQUIRED +.. data:: ussl.CERT_NONE + ussl.CERT_OPTIONAL + ussl.CERT_REQUIRED Supported values for *cert_reqs* parameter. |