diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/design_guide.rst | 4 | ||||
| -rw-r--r-- | docs/library/errno.rst (renamed from docs/library/uerrno.rst) | 10 | ||||
| -rw-r--r-- | docs/library/esp.rst | 85 | ||||
| -rw-r--r-- | docs/library/index.rst | 53 | ||||
| -rw-r--r-- | docs/library/io.rst (renamed from docs/library/uio.rst) | 6 | ||||
| -rw-r--r-- | docs/library/json.rst (renamed from docs/library/ujson.rst) | 6 | ||||
| -rw-r--r-- | docs/library/network.rst | 278 | ||||
| -rw-r--r-- | docs/library/re.rst (renamed from docs/library/ure.rst) | 8 | ||||
| -rw-r--r-- | docs/shared_bindings_matrix.py | 4 |
9 files changed, 30 insertions, 424 deletions
diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 75825893a..7a8c76b50 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -520,7 +520,9 @@ properties. +-----------------------+-----------------------+-------------------------------------------------------------------------+ | ``temperature`` | float | degrees centigrade | +-----------------------+-----------------------+-------------------------------------------------------------------------+ -| ``eCO2`` | float | equivalent CO2 in ppm | +| ``CO2`` | float | measured CO2 in ppm | ++-----------------------+-----------------------+-------------------------------------------------------------------------+ +| ``eCO2`` | float | equivalent/estimated CO2 in ppm (estimated from some other measurement) | +-----------------------+-----------------------+-------------------------------------------------------------------------+ | ``TVOC`` | float | Total Volatile Organic Compounds in ppb | +-----------------------+-----------------------+-------------------------------------------------------------------------+ diff --git a/docs/library/uerrno.rst b/docs/library/errno.rst index 72f71f0aa..96777b205 100644 --- a/docs/library/uerrno.rst +++ b/docs/library/errno.rst @@ -1,9 +1,7 @@ -:mod:`uerrno` -- system error codes +:mod:`errno` -- system error codes =================================== -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: uerrno +.. module:: errno :synopsis: system error codes |see_cpython_module| :mod:`cpython:errno`. @@ -22,7 +20,7 @@ Constants try: os.mkdir("my_dir") except OSError as exc: - if exc.args[0] == uerrno.EEXIST: + if exc.args[0] == errno.EEXIST: print("Directory already exists") .. data:: errorcode @@ -30,5 +28,5 @@ Constants Dictionary mapping numeric error codes to strings with symbolic error code (see above):: - >>> print(uerrno.errorcode[uerrno.EEXIST]) + >>> print(errno.errorcode[uerrno.EEXIST]) EEXIST diff --git a/docs/library/esp.rst b/docs/library/esp.rst deleted file mode 100644 index 125aaa890..000000000 --- a/docs/library/esp.rst +++ /dev/null @@ -1,85 +0,0 @@ -:mod:`esp` --- functions related to the ESP8266 -=============================================== - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: esp - :synopsis: functions related to the ESP8266 - -The ``esp`` module contains specific functions related to the ESP8266 module. - - -Functions ---------- - -.. function:: sleep_type([sleep_type]) - - Get or set the sleep type. - - If the *sleep_type* parameter is provided, sets the sleep type to its - value. If the function is called without parameters, returns the current - sleep type. - - The possible sleep types are defined as constants: - - * ``SLEEP_NONE`` -- all functions enabled, - * ``SLEEP_MODEM`` -- modem sleep, shuts down the WiFi Modem circuit. - * ``SLEEP_LIGHT`` -- light sleep, shuts down the WiFi Modem circuit - and suspends the processor periodically. - - The system enters the set sleep mode automatically when possible. - -.. function:: deepsleep(time=0) - - Enter deep sleep. - - The whole module powers down, except for the RTC clock circuit, which can - be used to restart the module after the specified time if the pin 16 is - connected to the reset pin. Otherwise the module will sleep until manually - reset. - -.. function:: flash_id() - - Read the device ID of the flash memory. - -.. function:: flash_read(byte_offset, length_or_buffer) - -.. function:: flash_write(byte_offset, bytes) - -.. function:: flash_erase(sector_no) - -.. function:: set_native_code_location(start, length) - - Set the location that native code will be placed for execution after it is - compiled. Native code is emitted when the ``@micropython.native``, - ``@micropython.viper`` and ``@micropython.asm_xtensa`` decorators are applied - to a function. The ESP8266 must execute code from either iRAM or the lower - 1MByte of flash (which is memory mapped), and this function controls the - location. - - If *start* and *length* are both ``None`` then the native code location is - set to the unused portion of memory at the end of the iRAM1 region. The - size of this unused portion depends on the firmware and is typically quite - small (around 500 bytes), and is enough to store a few very small - functions. The advantage of using this iRAM1 region is that it does not - get worn out by writing to it. - - If neither *start* nor *length* are ``None`` then they should be integers. - *start* should specify the byte offset from the beginning of the flash at - which native code should be stored. *length* specifies how many bytes of - flash from *start* can be used to store native code. *start* and *length* - should be multiples of the sector size (being 4096 bytes). The flash will - be automatically erased before writing to it so be sure to use a region of - flash that is not otherwise used, for example by the firmware or the - filesystem. - - When using the flash to store native code *start+length* must be less - than or equal to 1MByte. Note that the flash can be worn out if repeated - erasures (and writes) are made so use this feature sparingly. - In particular, native code needs to be recompiled and rewritten to flash - on each boot (including wake from deepsleep). - - In both cases above, using iRAM1 or flash, if there is no more room left - in the specified region then the use of a native decorator on a function - will lead to `MemoryError` exception being raised during compilation of - that function. diff --git a/docs/library/index.rst b/docs/library/index.rst index e91387242..181ff0109 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -6,35 +6,21 @@ MicroPython libraries Python standard libraries and micro-libraries --------------------------------------------- -These libraries are inherited from MicroPython. -They are similar to the standard Python libraries with the same name -or with the "u" prefix dropped. +The libraries below are inherited from MicroPython. +They are similar to the standard Python libraries with the same name. They implement a subset of or a variant of the corresponding standard Python library. -.. warning:: - - Though these MicroPython-based libraries are available in CircuitPython, - their functionality may change in the future, perhaps significantly. - As CircuitPython continues to develop, new versions of these libraries will - be created that are more compliant with the standard Python libraries. - You may need to change your code later if you rely - on any non-standard functionality they currently provide. - CircuitPython's long-term goal is that code written in CircuitPython using Python standard libraries will be runnable on CPython without changes. -Some libraries below are not enabled on CircuitPython builds with +These libraries are not enabled on CircuitPython builds with limited flash memory, usually on non-Express builds: -``uerrno``, ``ure``. - -Some libraries are not currently enabled in any CircuitPython build, but may be in the future: -``uio``, ``ujson``, ``uzlib``. +``binascii``, ``errno``, ``json``, ``re``. -Some libraries are only enabled only WiFi-capable ports (ESP8266, nRF) -because they are typically used for network software: -``binascii``, ``hashlib``, ``uheapq``, ``uselect``, ``ussl``. -Not all of these are enabled on all WiFi-capable ports. +These libraries are not currently enabled in any CircuitPython build, but may be in the future, +with the ``u`` prefix dropped: +``uctypes``, ``uhashlib``, ``uzlib``. .. toctree:: :maxdepth: 1 @@ -44,13 +30,14 @@ Not all of these are enabled on all WiFi-capable ports. array.rst binascii.rst collections.rst + errno.rst gc.rst hashlib.rst + io.rst + json.rst + re.rst sys.rst - uerrno.rst - uio.rst - ujson.rst - ure.rst + uctypes.rst uselect.rst usocket.rst ussl.rst @@ -59,8 +46,8 @@ Not all of these are enabled on all WiFi-capable ports. Omitted functions in the ``string`` library ------------------------------------------- -A few string operations are not enabled on CircuitPython -M0 non-Express builds, due to limited flash memory: +A few string operations are not enabled on small builds +(usually non-Express), due to limited flash memory: ``string.center()``, ``string.partition()``, ``string.splitlines()``, ``string.reversed()``. @@ -78,15 +65,3 @@ versions of CircuitPython. btree.rst framebuf.rst micropython.rst - network.rst - uctypes.rst - -Libraries specific to the ESP8266 ---------------------------------- - -The following libraries are specific to the ESP8266. - -.. toctree:: - :maxdepth: 2 - - esp.rst diff --git a/docs/library/uio.rst b/docs/library/io.rst index d1f7c111f..37e3eb7c9 100644 --- a/docs/library/uio.rst +++ b/docs/library/io.rst @@ -1,9 +1,7 @@ -:mod:`uio` -- input/output streams +:mod:`io` -- input/output streams ================================== -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: uio +.. module:: io :synopsis: input/output streams |see_cpython_module| :mod:`cpython:io`. diff --git a/docs/library/ujson.rst b/docs/library/json.rst index 4ed91f053..21574e556 100644 --- a/docs/library/ujson.rst +++ b/docs/library/json.rst @@ -1,9 +1,7 @@ -:mod:`ujson` -- JSON encoding and decoding +:mod:`json` -- JSON encoding and decoding ========================================== -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: ujson +.. module:: json :synopsis: JSON encoding and decoding |see_cpython_module| :mod:`cpython:json`. diff --git a/docs/library/network.rst b/docs/library/network.rst deleted file mode 100644 index 3bd41150d..000000000 --- a/docs/library/network.rst +++ /dev/null @@ -1,278 +0,0 @@ -**************************************** -:mod:`network` --- network configuration -**************************************** - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: network - :noindex: - :synopsis: network configuration - -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:`usocket` -module. - -For example:: - - # connect/ show IP config a specific network interface - # see below for examples of specific drivers - import network - import utime - nic = network.Driver(...) - if not nic.isconnected(): - nic.connect() - print("Waiting for connection...") - while not nic.isconnected(): - utime.sleep(1) - print(nic.ifconfig()) - - # now use usocket as usual - import usocket as socket - addr = socket.getaddrinfo('micropython.org', 80)[0][-1] - s = socket.socket() - s.connect(addr) - s.send(b'GET / HTTP/1.1\r\nHost: micropython.org\r\n\r\n') - data = s.recv(1000) - s.close() - -Common network adapter interface -================================ - -This section describes an (implied) abstract base class for all network -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, ...) - -Instantiate a network interface object. Parameters are network interface -dependent. If there are more than one interface of the same type, the first -parameter should be `id`. - - .. method:: active([is_active]) - - Activate ("up") or deactivate ("down") the network interface, if - a boolean argument is passed. Otherwise, query current state if - no argument is provided. Most other methods require an active - interface (behavior of calling them on inactive interface is - undefined). - - .. method:: connect([service_id, key=None, \*, ...]) - - Connect the interface to a network. This method is optional, and - available only for interfaces which are not "always connected". - If no parameters are given, connect to the default (or the only) - service. If a single parameter is given, it is the primary identifier - of a service to connect to. It may be accompanied by a key - (password) required to access said service. There can be further - arbitrary keyword-only parameters, depending on the networking medium - type and/or particular device. Parameters can be used to: a) - specify alternative service identifier types; b) provide additional - connection parameters. For various medium types, there are different - sets of predefined/recommended parameters, among them: - - * WiFi: *bssid* keyword to connect to a specific BSSID (MAC address) - - .. method:: disconnect() - - Disconnect from network. - - .. method:: isconnected() - - Returns ``True`` if connected to network, otherwise returns ``False``. - - .. method:: scan(\*, ...) - - Scan for the available network services/connections. Returns a - list of tuples with discovered service parameters. For various - network media, there are different variants of predefined/ - recommended tuple formats, among them: - - * WiFi: (ssid, bssid, channel, RSSI, authmode, hidden). There - may be further fields, specific to a particular device. - - The function may accept additional keyword arguments to filter scan - results (e.g. scan for a particular service, on a particular channel, - for services of a particular set, etc.), and to affect scan - duration and other parameters. Where possible, parameter names - should match those in connect(). - - .. method:: status() - - Return detailed status of the interface, values are dependent - on the network medium/technology. - - .. method:: ifconfig([(ip, subnet, gateway, dns)]) - - Get/set IP-level network interface parameters: IP address, subnet mask, - gateway and DNS server. When called with no arguments, this method returns - a 4-tuple with the above information. To set the above values, pass a - 4-tuple with the required information. For example:: - - nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) - - .. method:: config('param') - config(param=value, ...) - - Get or set general network interface parameters. These methods allow to work - with additional parameters beyond standard IP configuration (as dealt with by - `ifconfig()`). These include network-specific and hardware-specific - parameters and status values. For setting parameters, the keyword argument - syntax should be used, and multiple parameters can be set at once. For - querying, a parameter name should be quoted as a string, and only one - parameter can be queried at a time:: - - # Set WiFi access point name (formally known as ESSID) and WiFi channel - ap.config(essid='My AP', channel=11) - # Query params one by one - print(ap.config('essid')) - print(ap.config('channel')) - # Extended status information also available this way - print(sta.config('rssi')) - -.. _network.WLAN: - -Functions -========= - -.. function:: phy_mode([mode]) - - Get or set the PHY mode. - - If the *mode* parameter is provided, sets the mode to its value. If - the function is called without parameters, returns the current mode. - - The possible modes are defined as constants: - * ``MODE_11B`` -- IEEE 802.11b, - * ``MODE_11G`` -- IEEE 802.11g, - * ``MODE_11N`` -- IEEE 802.11n. - -class WLAN -========== - -This class provides a driver for WiFi network processor in the ESP8266. Example usage:: - - import network - # enable station interface and connect to WiFi access point - nic = network.WLAN(network.STA_IF) - nic.active(True) - nic.connect('your-ssid', 'your-password') - # now use sockets as usual - -Constructors ------------- -.. class:: WLAN(interface_id) - -Create a WLAN network interface object. Supported interfaces are -``network.STA_IF`` (station aka client, connects to upstream WiFi access -points) and ``network.AP_IF`` (access point, allows other WiFi clients to -connect). Availability of the methods below depends on interface type. -For example, only STA interface may `connect()` to an access point. - -Methods -------- - -.. method:: wlan.active([is_active]) - - Activate ("up") or deactivate ("down") network interface, if boolean - argument is passed. Otherwise, query current state if no argument is - provided. Most other methods require active interface. - -.. 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() - - Disconnect from the currently connected wireless network. - -.. method:: wlan.scan() - - Scan for the available wireless networks. - - Scanning is only possible on STA interface. Returns list of tuples with - the information about WiFi access points: - - (ssid, bssid, channel, RSSI, authmode, hidden) - - *bssid* is hardware address of an access point, in binary form, returned as - bytes object. You can use `binascii.hexlify()` to convert it to ASCII form. - - There are five values for authmode: - - * 0 -- open - * 1 -- WEP - * 2 -- WPA-PSK - * 3 -- WPA2-PSK - * 4 -- WPA/WPA2-PSK - - and two for hidden: - - * 0 -- visible - * 1 -- hidden - -.. method:: wlan.status() - - Return the current status of the wireless connection. - - The possible statuses are defined as constants: - - * ``STAT_IDLE`` -- no connection and no activity, - * ``STAT_CONNECTING`` -- connecting in progress, - * ``STAT_WRONG_PASSWORD`` -- failed due to incorrect password, - * ``STAT_NO_AP_FOUND`` -- failed because no access point replied, - * ``STAT_CONNECT_FAIL`` -- failed due to other problems, - * ``STAT_GOT_IP`` -- connection successful. - -.. method:: wlan.isconnected() - - In case of STA mode, returns ``True`` if connected to a WiFi access - point and has a valid IP address. In AP mode returns ``True`` when a - station is connected. Returns ``False`` otherwise. - -.. method:: wlan.ifconfig([(ip, subnet, gateway, dns)]) - - Get/set IP-level network interface parameters: IP address, subnet mask, - gateway and DNS server. When called with no arguments, this method returns - a 4-tuple with the above information. To set the above values, pass a - 4-tuple with the required information. For example:: - - nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) - -.. method:: wlan.config('param') - wlan.config(param=value, ...) - - Get or set general network interface parameters. These methods allow to work - with additional parameters beyond standard IP configuration (as dealt with by - `wlan.ifconfig()`). These include network-specific and hardware-specific - parameters. For setting parameters, keyword argument syntax should be used, - multiple parameters can be set at once. For querying, parameters name should - be quoted as a string, and only one parameter can be queries at time:: - - # Set WiFi access point name (formally known as ESSID) and WiFi channel - ap.config(essid='My AP', channel=11) - # Query params one by one - print(ap.config('essid')) - print(ap.config('channel')) - - 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) - dhcp_hostname The DHCP hostname to use - ============= =========== diff --git a/docs/library/ure.rst b/docs/library/re.rst index 4af182b01..bdcc9f52c 100644 --- a/docs/library/ure.rst +++ b/docs/library/re.rst @@ -1,9 +1,7 @@ -:mod:`ure` -- simple regular expressions +:mod:`re` -- simple regular expressions ======================================== -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: ure +.. module:: re :synopsis: regular expressions |see_cpython_module| :mod:`cpython:re`. @@ -77,7 +75,7 @@ Regex objects ------------- Compiled regular expression. Instances of this class are created using -`ure.compile()`. +`re.compile()`. .. method:: regex.match(string) regex.search(string) diff --git a/docs/shared_bindings_matrix.py b/docs/shared_bindings_matrix.py index f38c0b64a..e62b1d218 100644 --- a/docs/shared_bindings_matrix.py +++ b/docs/shared_bindings_matrix.py @@ -30,7 +30,7 @@ import sys from concurrent.futures import ThreadPoolExecutor -SUPPORTED_PORTS = ['atmel-samd', 'esp32s2', 'litex', 'mimxrt10xx', 'nrf', 'stm'] +SUPPORTED_PORTS = ['atmel-samd', 'cxd56', 'esp32s2', 'litex', 'mimxrt10xx', 'nrf', 'raspberrypi', 'stm'] def get_circuitpython_root_dir(): """ The path to the root './circuitpython' directory @@ -44,7 +44,7 @@ def get_shared_bindings(): """ Get a list of modules in shared-bindings based on folder names """ shared_bindings_dir = get_circuitpython_root_dir() / "shared-bindings" - return [item.name for item in shared_bindings_dir.iterdir()] + ["ulab"] + return [item.name for item in shared_bindings_dir.iterdir()] + ["binascii", "errno", "json", "re", "ulab"] def read_mpconfig(): |