diff options
Diffstat (limited to 'docs/library')
| -rw-r--r-- | docs/library/btree.rst | 18 | ||||
| -rw-r--r-- | docs/library/framebuf.rst | 11 | ||||
| -rw-r--r-- | docs/library/index.rst | 5 | ||||
| -rw-r--r-- | docs/library/machine.RTC.rst | 2 | ||||
| -rw-r--r-- | docs/library/machine.Signal.rst | 41 | ||||
| -rw-r--r-- | docs/library/micropython.rst | 2 | ||||
| -rw-r--r-- | docs/library/network.rst | 10 | ||||
| -rw-r--r-- | docs/library/sys.rst | 2 | ||||
| -rw-r--r-- | docs/library/ubinascii.rst | 8 | ||||
| -rw-r--r-- | docs/library/uos.rst | 22 | ||||
| -rw-r--r-- | docs/library/usocket.rst | 66 |
11 files changed, 138 insertions, 49 deletions
diff --git a/docs/library/btree.rst b/docs/library/btree.rst index 9322d32e6..8fac67e8d 100644 --- a/docs/library/btree.rst +++ b/docs/library/btree.rst @@ -76,20 +76,24 @@ Example:: Functions --------- -.. function:: open(stream, \*, flags=0, cachesize=0, pagesize=0, minkeypage=0) +.. function:: open(stream, \*, flags=0, pagesize=0, cachesize=0, minkeypage=0) Open a database from a random-access `stream` (like an open file). All other parameters are optional and keyword-only, and allow to tweak advanced parameters of the database operation (most users will not need them): * *flags* - Currently unused. - * *cachesize* - Suggested maximum memory cache size in bytes. For a - board with enough memory using larger values may improve performance. - The value is only a recommendation, the module may use more memory if - values set too low. * *pagesize* - Page size used for the nodes in BTree. Acceptable range - is 512-65536. If 0, underlying I/O block size will be used (the best - compromise between memory usage and performance). + is 512-65536. If 0, a port-specific default will be used, optimized for + port's memory usage and/or performance. + * *cachesize* - Suggested memory cache size in bytes. For a + board with enough memory using larger values may improve performance. + Cache policy is as follows: entire cache is not allocated at once; + instead, accessing a new page in database will allocate a memory buffer + for it, until value specified by *cachesize* is reached. Then, these + buffers will be managed using LRU (least recently used) policy. More + buffers may still be allocated if needed (e.g., if a database contains + big keys and/or values). Allocated cache buffers aren't reclaimed. * *minkeypage* - Minimum number of keys to store per page. Default value of 0 equivalent to 2. diff --git a/docs/library/framebuf.rst b/docs/library/framebuf.rst index b92bd08ef..74c9f8564 100644 --- a/docs/library/framebuf.rst +++ b/docs/library/framebuf.rst @@ -38,9 +38,9 @@ Constructors - *width* is the width of the FrameBuffer in pixels - *height* is the height of the FrameBuffer in pixels - *format* specifies the type of pixel used in the FrameBuffer; - valid values are ``framebuf.MVLSB``, ``framebuf.RGB565`` - and ``framebuf.GS4_HMSB``. MVLSB is monochrome 1-bit color, - RGB565 is RGB 16-bit color, and GS4_HMSB is grayscale 4-bit color. + permissible values are listed under Constants below. These set the + number of bits used to encode a color value and the layout of these + bits in *buffer*. Where a color value c is passed to a method, c is a small integer with an encoding that is dependent on the format of the FrameBuffer. - *stride* is the number of pixels between each horizontal line @@ -110,8 +110,9 @@ Other methods corresponding color will be considered transparent: all pixels with that color value will not be drawn. - This method works between FrameBuffer's utilising different formats, but the - resulting colors may be unexpected due to the mismatch in color formats. + This method works between FrameBuffer instances utilising different formats, + but the resulting colors may be unexpected due to the mismatch in color + formats. Constants --------- diff --git a/docs/library/index.rst b/docs/library/index.rst index e884f266e..0789ea43d 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -40,8 +40,7 @@ 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>`_. +extensions to it, can be found in `micropython-lib`. Python standard libraries and micro-libraries --------------------------------------------- @@ -54,7 +53,7 @@ e.g. ``ujson`` instead of ``json``. This is to signify that such a module is micro-library, i.e. implements only a subset of CPython module functionality. By naming them differently, a user has a choice to write a Python-level module to extend functionality for better compatibility with CPython (indeed, this is -what done by micropython-lib project mentioned above). +what done by the `micropython-lib` project mentioned above). On some embedded platforms, where it may be cumbersome to add Python-level wrapper modules to achieve naming compatibility with CPython, micro-modules diff --git a/docs/library/machine.RTC.rst b/docs/library/machine.RTC.rst index 2a53b9146..95fa2b4ce 100644 --- a/docs/library/machine.RTC.rst +++ b/docs/library/machine.RTC.rst @@ -38,7 +38,7 @@ Methods Resets the RTC to the time of January 1, 2015 and starts running it again. -.. method:: RTC.alarm(id, time, /*, repeat=False) +.. method:: RTC.alarm(id, time, \*, repeat=False) Set the RTC alarm. Time might be either a millisecond value to program the alarm to current time + time_in_ms in the future, or a datetimetuple. If the time passed is in diff --git a/docs/library/machine.Signal.rst b/docs/library/machine.Signal.rst index 486908627..a1a29164b 100644 --- a/docs/library/machine.Signal.rst +++ b/docs/library/machine.Signal.rst @@ -4,17 +4,44 @@ class Signal -- control and sense external I/O devices ====================================================== -The Signal class is a simple extension of Pin class. Unlike Pin, which +The Signal class is a simple extension of the `Pin` class. Unlike Pin, which can be only in "absolute" 0 and 1 states, a Signal can be in "asserted" (on) or "deasserted" (off) states, while being inverted (active-low) or -not. Summing up, it adds logical inversion support to Pin functionality. +not. In other words, it adds logical inversion support to Pin functionality. While this may seem a simple addition, it is exactly what is needed to support wide array of simple digital devices in a way portable across different boards, which is one of the major MicroPython goals. Regardless -whether different users have an active-high or active-low LED, a normally -open or normally closed relay - you can develop single, nicely looking +of whether different users have an active-high or active-low LED, a normally +open or normally closed relay - you can develop a single, nicely looking application which works with each of them, and capture hardware -configuration differences in few lines on the config file of your app. +configuration differences in few lines in the config file of your app. + +Example:: + + from machine import Pin, Signal + + # Suppose you have an active-high LED on pin 0 + led1_pin = Pin(0, Pin.OUT) + # ... and active-low LED on pin 1 + led2_pin = Pin(1, Pin.OUT) + + # Now to light up both of them using Pin class, you'll need to set + # them to different values + led1_pin.value(1) + led2_pin.value(0) + + # Signal class allows to abstract away active-high/active-low + # difference + led1 = Signal(led1_pin, invert=False) + led2 = Signal(led2_pin, invert=True) + + # Now lighting up them looks the same + led1.value(1) + led2.value(1) + + # Even better: + led1.on() + led2.on() Following is the guide when Signal vs Pin should be used: @@ -33,11 +60,11 @@ architecture of MicroPython: Pin offers the lowest overhead, which may be important when bit-banging protocols. But Signal adds additional flexibility on top of Pin, at the cost of minor overhead (much smaller than if you implemented active-high vs active-low device differences in -Python manually!). Also, Pin is low-level object which needs to be +Python manually!). Also, Pin is a low-level object which needs to be implemented for each support board, while Signal is a high-level object which comes for free once Pin is implemented. -If in doubt, give the Signal a try! Once again, it is developed to save +If in doubt, give the Signal a try! Once again, it is offered to save developers from the need to handle unexciting differences like active-low vs active-high signals, and allow other users to share and enjoy your application, instead of being frustrated by the fact that it doesn't diff --git a/docs/library/micropython.rst b/docs/library/micropython.rst index 4ff0b0c15..c13a7391b 100644 --- a/docs/library/micropython.rst +++ b/docs/library/micropython.rst @@ -46,7 +46,7 @@ Functions .. function:: mem_info([verbose]) - Print information about currently used memory. If the *verbose`* argument + Print information about currently used memory. If the *verbose* argument is given then extra information is printed. The information that is printed is implementation dependent, but currently diff --git a/docs/library/network.rst b/docs/library/network.rst index de93c0e01..def6bee74 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -9,7 +9,7 @@ This module provides network drivers and routing configuration. To use this module, a MicroPython variant/build with network capabilities must be installed. Network drivers for specific hardware are available within this module and are used to configure hardware network interface(s). Network services provided -by configured interfaces are then available for use via the :mod:`socket` +by configured interfaces are then available for use via the :mod:`usocket` module. For example:: @@ -39,9 +39,9 @@ Common network adapter interface ================================ This section describes an (implied) abstract base class for all network -interface classes implemented by different ports of MicroPython for -different hardware. This means that MicroPython does not actually -provide `AbstractNIC` class, but any actual NIC class, as described +interface classes implemented by `MicroPython ports <MicroPython port>` +for different hardware. This means that MicroPython does not actually +provide ``AbstractNIC`` class, but any actual NIC class, as described in the following sections, implements methods as described here. .. class:: AbstractNIC(id=None, ...) @@ -411,7 +411,7 @@ parameter should be `id`. print(ap.config('channel')) Following are commonly supported parameters (availability of a specific parameter - depends on network technology type, driver, and MicroPython port). + depends on network technology type, driver, and `MicroPython port`). ========= =========== Parameter Description diff --git a/docs/library/sys.rst b/docs/library/sys.rst index 0bec35cc9..d49577306 100644 --- a/docs/library/sys.rst +++ b/docs/library/sys.rst @@ -28,7 +28,7 @@ Functions this function takes just exception value instead of exception type, exception value, and traceback object; *file* argument should be positional; further arguments are not supported. CPython-compatible - ``traceback`` module can be found in micropython-lib. + ``traceback`` module can be found in `micropython-lib`. Constants --------- diff --git a/docs/library/ubinascii.rst b/docs/library/ubinascii.rst index 0664d5b09..192d34514 100644 --- a/docs/library/ubinascii.rst +++ b/docs/library/ubinascii.rst @@ -29,8 +29,12 @@ Functions .. function:: a2b_base64(data) - Convert Base64-encoded data to binary representation. Returns bytes string. + Decode base64-encoded data, ignoring invalid characters in the input. + Conforms to `RFC 2045 s.6.8 <https://tools.ietf.org/html/rfc2045#section-6.8>`_. + Returns a bytes object. .. function:: b2a_base64(data) - Encode binary data in Base64 format. Returns string. + Encode binary data in base64 format, as in `RFC 3548 + <https://tools.ietf.org/html/rfc3548.html>`_. Returns the encoded data + followed by a newline character, as a bytes object. diff --git a/docs/library/uos.rst b/docs/library/uos.rst index 7c52c1eea..43bf69cc0 100644 --- a/docs/library/uos.rst +++ b/docs/library/uos.rst @@ -89,8 +89,22 @@ Functions Return a bytes object with n random bytes. Whenever possible, it is generated by the hardware random number generator. -.. function:: dupterm(stream_object) +.. function:: dupterm(stream_object, index=0) - Duplicate or switch MicroPython terminal (the REPL) on the passed stream-like - object. The given object must implement the ``readinto()`` and ``write()`` - methods. If ``None`` is passed, previously set redirection is cancelled. + Duplicate or switch the MicroPython terminal (the REPL) on the given stream-like + object. The *stream_object* argument must implement the ``readinto()`` and + ``write()`` methods. The stream should be in non-blocking mode and + ``readinto()`` should return ``None`` if there is no data available for reading. + + After calling this function all terminal output is repeated on this stream, + and any input that is available on the stream is passed on to the terminal input. + + The *index* parameter should be a non-negative integer and specifies which + duplication slot is set. A given port may implement more than one slot (slot 0 + will always be available) and in that case terminal input and output is + duplicated on all the slots that are set. + + If ``None`` is passed as the *stream_object* then duplication is cancelled on + the slot given by *index*. + + The function returns the previous stream-like object in the given slot. diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index 70d4f49fc..dfdcd68bc 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -12,12 +12,6 @@ This module provides access to the BSD socket interface. .. admonition:: Difference to CPython :class: attention - CPython used to have a ``socket.error`` exception which is now deprecated, - and is an alias of `OSError`. In MicroPython, use `OSError` directly. - -.. admonition:: Difference to CPython - :class: attention - For efficiency and consistency, socket objects in MicroPython implement a stream (file-like) interface directly. In CPython, you need to convert a socket to a file-like object using `makefile()` method. This method is still supported @@ -27,11 +21,47 @@ This module provides access to the BSD socket interface. Socket address format(s) ------------------------ -The functions below which expect a network address, accept it in the format of -*(ipv4_address, port)*, where *ipv4_address* is a string with dot-notation numeric -IPv4 address, e.g. ``"8.8.8.8"``, and port is integer port number in the range -1-65535. Note the domain names are not accepted as *ipv4_address*, they should be -resolved first using `usocket.getaddrinfo()`. +The native socket address format of the ``usocket`` module is an opaque data type +returned by `getaddrinfo` function, which must be used to resolve textual address +(including numeric addresses):: + + sockaddr = usocket.getaddrinfo('www.micropython.org', 80)[0][-1] + # You must use getaddrinfo() even for numeric addresses + sockaddr = usocket.getaddrinfo('127.0.0.1', 80)[0][-1] + # Now you can use that address + sock.connect(addr) + +Using `getaddrinfo` is the most efficient (both in terms of memory and processing +power) and portable way to work with addresses. + +However, ``socket`` module (note the difference with native MicroPython +``usocket`` module described here) provides CPython-compatible way to specify +addresses using tuples, as described below. Note that depending on a +`MicroPython port`, ``socket`` module can be builtin or need to be +installed from `micropython-lib` (as in the case of `MicroPython Unix port`), +and some ports still accept only numeric addresses in the tuple format, +and require to use `getaddrinfo` function to resolve domain names. + +Summing up: + +* Always use `getaddrinfo` when writing portable applications. +* Tuple addresses described below can be used as a shortcut for + quick hacks and interactive use, if your port supports them. + +Tuple address format for ``socket`` module: + +* IPv4: *(ipv4_address, port)*, where *ipv4_address* is a string with + dot-notation numeric IPv4 address, e.g. ``"8.8.8.8"``, and *port* is and + integer port number in the range 1-65535. Note the domain names are not + accepted as *ipv4_address*, they should be resolved first using + `usocket.getaddrinfo()`. +* IPv6: *(ipv6_address, port, flowinfo, scopeid)*, where *ipv6_address* + is a string with colon-notation numeric IPv6 address, e.g. ``"2001:db8::1"``, + and *port* is an integer port number in the range 1-65535. *flowinfo* + must be 0. *scopeid* is the interface scope identifier for link-local + addresses. Note the domain names are not accepted as *ipv6_address*, + they should be resolved first using `usocket.getaddrinfo()`. Availability + of IPv6 support depends on a `MicroPython port`. Functions --------- @@ -87,12 +117,12 @@ Constants .. data:: usocket.SOL_* Socket option levels (an argument to `setsockopt()`). The exact - inventory depends on a MicroPython port. + inventory depends on a `MicroPython port`. .. data:: usocket.SO_* Socket options (an argument to `setsockopt()`). The exact - inventory depends on a MicroPython port. + inventory depends on a `MicroPython port`. Constants specific to WiPy: @@ -250,3 +280,13 @@ Methods the length of *buf*. Return value: number of bytes written. + +.. exception:: socket.error + + MicroPython does NOT have this exception. + + .. admonition:: Difference to CPython + :class: attention + + CPython used to have a ``socket.error`` exception which is now deprecated, + and is an alias of `OSError`. In MicroPython, use `OSError` directly. |