diff options
Diffstat (limited to 'docs/library')
| -rw-r--r-- | docs/library/cmath.rst | 5 | ||||
| -rw-r--r-- | docs/library/index.rst | 31 | ||||
| -rw-r--r-- | docs/library/machine.UART.rst | 36 | ||||
| -rw-r--r-- | docs/library/machine.rst | 41 | ||||
| -rw-r--r-- | docs/library/math.rst | 5 | ||||
| -rw-r--r-- | docs/library/pyb.DAC.rst | 4 | ||||
| -rw-r--r-- | docs/library/ussl.rst | 99 | ||||
| -rw-r--r-- | docs/library/ustruct.rst | 6 |
8 files changed, 154 insertions, 73 deletions
diff --git a/docs/library/cmath.rst b/docs/library/cmath.rst index e45efee303..465cf54ad3 100644 --- a/docs/library/cmath.rst +++ b/docs/library/cmath.rst @@ -4,9 +4,12 @@ .. module:: cmath :synopsis: mathematical functions for complex numbers -The ``cmath`` module provides some basic mathematical funtions for +The ``cmath`` module provides some basic mathematical functions for working with complex numbers. +Availability: not available on WiPy and ESP8266. Floating point support +required for this module. + Functions --------- diff --git a/docs/library/index.rst b/docs/library/index.rst index 03e6502d95..e3d6e31575 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -1,9 +1,33 @@ MicroPython libraries ===================== -The following standard Python libraries are built in to MicroPython. - -For additional libraries, please download them from the `micropython-lib repository +This chapter describes modules (function and class libraries) which are built +into MicroPython. There are a few categories of modules: + +* Modules which implement a subset of standard Python functionality and are not + intended to be extended by the user. +* Modules which implement a subset of Python functionality, with a provision + for extension by the user (via Python code). +* Modules which implement MicroPython extensions to the Python standard libraries. +* Modules specific to a particular port and thus not portable. + +Note about the availability of modules and their contents: This documentation +in general aspires to describe all modules and functions/classes which are +implemented in MicroPython. However, MicroPython is highly configurable, and +each port to a particular board/embedded system makes available only a subset +of MicroPython libraries. For officially supported ports, there is an effort +to either filter out non-applicable items, or mark individual descriptions +with "Availability:" clauses describing which ports provide a given feature. +With that in mind, please still be warned that some functions/classes +in a module (or even the entire module) described in this documentation may be +unavailable in a particular build of MicroPython on a particular board. The +best place to find general information of the availability/non-availability +of a particular feature is the "General Information" section which contains +information pertaining to a specific port. + +Beyond the built-in libraries described in this documentation, many more +modules from the Python standard library, as well as further MicroPython +extensions to it, can be found in the `micropython-lib repository <https://github.com/micropython/micropython-lib>`_. Python standard libraries and micro-libraries @@ -101,6 +125,7 @@ library. uos.rst ure.rst usocket.rst + ussl.rst ustruct.rst utime.rst uzlib.rst diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index 98e24f37dd..7399b9b6e9 100644 --- a/docs/library/machine.UART.rst +++ b/docs/library/machine.UART.rst @@ -86,13 +86,15 @@ Methods When no pins are given, then the default set of TX and RX pins is taken, and hardware flow control will be disabled. If pins=None, no pin assignment will be made. -.. method:: uart.deinit() +.. only:: not port_esp8266 - Turn off the UART bus. + .. method:: uart.deinit() -.. method:: uart.any() + Turn off the UART bus. - Return the number of characters available for reading. + .. method:: uart.any() + + Return the number of characters available for reading. .. method:: uart.read([nbytes]) @@ -127,11 +129,13 @@ Methods Return value: number of bytes written or ``None`` on timeout. -.. method:: uart.sendbreak() +.. only:: not port_esp8266 + + .. method:: uart.sendbreak() - Send a break condition on the bus. This drives the bus low for a duration - of 13 bits. - Return value: ``None``. + Send a break condition on the bus. This drives the bus low for a duration + of 13 bits. + Return value: ``None``. .. only:: port_wipy @@ -158,14 +162,16 @@ Methods Returns an irq object. -Constants ---------- +.. only:: not port_esp8266 + + Constants + --------- -.. data:: UART.EVEN -.. data:: UART.ODD + .. data:: UART.EVEN + .. data:: UART.ODD - parity types (anlong with ``None``) + parity types (anlong with ``None``) -.. data:: UART.RX_ANY + .. data:: UART.RX_ANY - IRQ trigger sources + IRQ trigger sources diff --git a/docs/library/machine.rst b/docs/library/machine.rst index 14d75cb466..b103ec393d 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -18,25 +18,23 @@ Reset related functions Get the reset cause. See :ref:`constants <machine_constants>` for the possible return values. -.. only:: port_wipy - - Interrupt related functions - --------------------------- +Interrupt related functions +--------------------------- - .. function:: disable_irq() +.. function:: disable_irq() - Disable interrupt requests. - Returns the previous IRQ state: ``False``/``True`` for disabled/enabled IRQs - respectively. This return value can be passed to enable_irq to restore - the IRQ to its original state. + Disable interrupt requests. + Returns the previous IRQ state: ``False``/``True`` for disabled/enabled IRQs + respectively. This return value can be passed to enable_irq to restore + the IRQ to its original state. - .. function:: enable_irq(state=True) +.. function:: enable_irq(state=True) - Enable interrupt requests. - If ``state`` is ``True`` (the default value) then IRQs are enabled. - If ``state`` is ``False`` then IRQs are disabled. The most common use of - this function is to pass it the value returned by ``disable_irq`` to - exit a critical section. + Enable interrupt requests. + If ``state`` is ``True`` (the default value) then IRQs are enabled. + If ``state`` is ``False`` then IRQs are disabled. The most common use of + this function is to pass it the value returned by ``disable_irq`` to + exit a critical section. Power related functions ----------------------- @@ -103,6 +101,19 @@ Miscellaneous functions varies by hardware (so use substring of a full value if you expect a short ID). In some MicroPython ports, ID corresponds to the network MAC address. +.. function:: time_pulse_us(pin, pulse_level, timeout_us=1000000) + + Time a pulse on the given `pin`, and return the duration of the pulse in + microseconds. The `pulse_level` argument should be 0 to time a low pulse + or 1 to time a high pulse. + + The function first waits while the pin input is different to the `pulse_level` + parameter, then times the duration that the pin is equal to `pulse_level`. + If the pin is already equal to `pulse_level` then timing starts straight away. + + The function will raise an OSError with ETIMEDOUT if either of the waits is + longer than the given timeout value (which is in microseconds). + .. _machine_constants: Constants diff --git a/docs/library/math.rst b/docs/library/math.rst index 6ed42333c7..9d5cf7b4ba 100644 --- a/docs/library/math.rst +++ b/docs/library/math.rst @@ -4,11 +4,14 @@ .. module:: math :synopsis: mathematical functions -The ``math`` module provides some basic mathematical funtions for +The ``math`` module provides some basic mathematical functions for working with floating-point numbers. *Note:* On the pyboard, floating-point numbers have 32-bit precision. +Availability: not available on WiPy. Floating point support required +for this module. + Functions --------- diff --git a/docs/library/pyb.DAC.rst b/docs/library/pyb.DAC.rst index 6041151b0f..7b5b1a6821 100644 --- a/docs/library/pyb.DAC.rst +++ b/docs/library/pyb.DAC.rst @@ -66,6 +66,10 @@ Methods Reinitialise the DAC. ``bits`` can be 8 or 12. +.. method:: dac.deinit() + + De-initialise the DAC making its pin available for other uses. + .. method:: dac.noise(freq) Generate a pseudo-random noise signal. A new random sample is written diff --git a/docs/library/ussl.rst b/docs/library/ussl.rst index b66e23b2c8..5371ed1290 100644 --- a/docs/library/ussl.rst +++ b/docs/library/ussl.rst @@ -8,56 +8,79 @@ This module provides access to Transport Layer Security (often known as “Secure Sockets Layer”) encryption and peer authentication facilities for network sockets, both client-side and server-side. -Functions ---------- +.. only:: not port_wipy -.. function:: ssl.wrap_socket(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ca_certs=None) + Functions + --------- - Takes an instance sock of socket.socket, and returns an instance of ssl.SSLSocket, a subtype of - ``socket.socket``, which wraps the underlying socket in an SSL context. sock must be a ``SOCK_STREAM`` - socket and protocol number ``socket.IPPROTO_SEC``; other socket types are unsupported. Example:: + .. function:: ssl.wrap_socket(sock, server_side=False) - import socket - import ssl - s = socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC) - ss = ssl.wrap_socket(s) - ss.connect(socket.getaddrinfo('www.google.com', 443)[0][-1]) + 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 + an SSL context. Returned object has the usual stream interface methods like + `read()`, `write()`, etc. In MicroPython, the returned object does not expose + socket interface and methods like `recv()`, `send()`. In particular, a + server-side SSL socket should be created from a normal socket returned from + `accept()` on a non-SSL listening server socket. - Certificates must be used in order to validate the other side of the connection, and also to - authenticate ourselves with the other end. Such certificates must be stored as files using the - FTP server, and they must be placed in specific paths with specific names. + .. warning:: - - The certificate to validate the other side goes in: **'/flash/cert/ca.pem'** - - The certificate to authenticate ourselves goes in: **'/flash/cert/cert.pem'** - - The key for our own certificate goes in: **'/flash/cert/private.key'** + Currently, this function does NOT validate server certificates, which makes + an SSL connection established prone to man-in-the-middle attacks. - .. note:: - When these files are stored, they are placed inside the internal **hidden** file system - (just like firmware updates), and therefore they are never visible. +.. only:: port_wipy - For instance to connect to the Blynk servers using certificates, take the file ``ca.pem`` located - in the `blynk examples folder <https://github.com/wipy/wipy/tree/master/examples/blynk>`_ - and put it in '/flash/cert/'. Then do:: + Functions + --------- - import socket - import ssl - s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC) - ss = ssl.wrap_socket(s, cert_reqs=ssl.CERT_REQUIRED, ca_certs='/flash/cert/ca.pem') - ss.connect(socket.getaddrinfo('cloud.blynk.cc', 8441)[0][-1]) + .. function:: ssl.wrap_socket(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ca_certs=None) - SSL sockets inherit all methods and from the standard sockets, see the :mod:`usocket` module. + Takes an instance sock of socket.socket, and returns an instance of ssl.SSLSocket, a subtype of + ``socket.socket``, which wraps the underlying socket in an SSL context. sock must be a ``SOCK_STREAM`` + socket and protocol number ``socket.IPPROTO_SEC``; other socket types are unsupported. Example:: -Exceptions ----------- + import socket + import ssl + s = socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC) + ss = ssl.wrap_socket(s) + ss.connect(socket.getaddrinfo('www.google.com', 443)[0][-1]) -.. data:: ssl.SSLError + Certificates must be used in order to validate the other side of the connection, and also to + authenticate ourselves with the other end. Such certificates must be stored as files using the + FTP server, and they must be placed in specific paths with specific names. -Constants ---------- + - The certificate to validate the other side goes in: **'/flash/cert/ca.pem'** + - The certificate to authenticate ourselves goes in: **'/flash/cert/cert.pem'** + - The key for our own certificate goes in: **'/flash/cert/private.key'** -.. data:: ssl.CERT_NONE -.. data:: ssl.CERT_OPTIONAL -.. data:: ssl.CERT_REQUIRED + .. note:: - supported values in ``cert_reqs`` + When these files are stored, they are placed inside the internal **hidden** file system + (just like firmware updates), and therefore they are never visible. + + For instance to connect to the Blynk servers using certificates, take the file ``ca.pem`` located + in the `blynk examples folder <https://github.com/wipy/wipy/tree/master/examples/blynk>`_ + and put it in '/flash/cert/'. Then do:: + + import socket + import ssl + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC) + ss = ssl.wrap_socket(s, cert_reqs=ssl.CERT_REQUIRED, ca_certs='/flash/cert/ca.pem') + ss.connect(socket.getaddrinfo('cloud.blynk.cc', 8441)[0][-1]) + + SSL sockets inherit all methods and from the standard sockets, see the :mod:`usocket` module. + + Exceptions + ---------- + + .. data:: ssl.SSLError + + Constants + --------- + + .. data:: ssl.CERT_NONE + .. data:: ssl.CERT_OPTIONAL + .. data:: ssl.CERT_REQUIRED + + supported values in ``cert_reqs`` diff --git a/docs/library/ustruct.rst b/docs/library/ustruct.rst index ae5b1be003..74e42af07a 100644 --- a/docs/library/ustruct.rst +++ b/docs/library/ustruct.rst @@ -7,6 +7,12 @@ See `Python struct <https://docs.python.org/3/library/struct.html>`_ for more information. +Supported size/byte order prefixes: ``@``, ``<``, ``>``, ``!``. + +Supported format codes: ``b``, ``B``, ``h``, ``H``, ``i``, ``I``, ``l``, +``L``, ``q``, ``Q``, ``s``, ``P``, ``f``, ``d`` (the latter 2 depending +on the floating-point support). + Functions --------- |