From 733094aead6e84b42da54655b2b0a5d0dbd1a503 Mon Sep 17 00:00:00 2001 From: Scott Shawcroft Date: Wed, 20 Jan 2021 16:47:18 -0800 Subject: Add initial RP2040 support The RP2040 is new microcontroller from Raspberry Pi that features two Cortex M0s and eight PIO state machines that are good for crunching lots of data. It has 264k RAM and a built in UF2 bootloader too. Datasheet: https://pico.raspberrypi.org/files/rp2040_datasheet.pdf --- docs/supported_ports.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/supported_ports.rst b/docs/supported_ports.rst index e74067e28..b83ef12d3 100644 --- a/docs/supported_ports.rst +++ b/docs/supported_ports.rst @@ -13,8 +13,9 @@ is limited. ../ports/atmel-samd/README ../ports/cxd56/README + ../ports/esp32s2/README ../ports/litex/README ../ports/mimxrt10xx/README ../ports/nrf/README + ../ports/raspberrypi/README ../ports/stm/README - ../ports/esp32s2/README -- cgit v1.2.3 From 69869e1439a1ebad383b75b28e7e88f21ccab732 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Sun, 24 Jan 2021 22:49:28 -0500 Subject: CIRCUITPY_* switches for JSON, RE, etc. Doc cleanup --- docs/library/errno.rst | 32 ++++++ docs/library/index.rst | 51 +++------ docs/library/io.rst | 114 ++++++++++++++++++++ docs/library/json.rst | 35 +++++++ docs/library/re.rst | 101 ++++++++++++++++++ docs/library/uerrno.rst | 34 ------ docs/library/uio.rst | 116 --------------------- docs/library/ujson.rst | 37 ------- docs/library/ure.rst | 103 ------------------ docs/shared_bindings_matrix.py | 4 +- .../mpconfigboard.h | 3 +- ports/atmel-samd/mpconfigport.h | 7 -- ports/atmel-samd/mpconfigport.mk | 52 +++------ ports/esp32s2/mpconfigport.h | 1 - ports/litex/mpconfigport.h | 2 - ports/mimxrt10xx/mpconfigport.h | 2 - ports/nrf/mpconfigport.h | 3 - ports/raspberrypi/mpconfigport.h | 4 +- ports/stm/mpconfigport.h | 2 - py/circuitpy_mpconfig.h | 73 ++++++------- py/circuitpy_mpconfig.mk | 12 +++ shared-bindings/support_matrix.rst | 4 +- 22 files changed, 367 insertions(+), 425 deletions(-) create mode 100644 docs/library/errno.rst create mode 100644 docs/library/io.rst create mode 100644 docs/library/json.rst create mode 100644 docs/library/re.rst delete mode 100644 docs/library/uerrno.rst delete mode 100644 docs/library/uio.rst delete mode 100644 docs/library/ujson.rst delete mode 100644 docs/library/ure.rst (limited to 'docs') diff --git a/docs/library/errno.rst b/docs/library/errno.rst new file mode 100644 index 000000000..96777b205 --- /dev/null +++ b/docs/library/errno.rst @@ -0,0 +1,32 @@ +:mod:`errno` -- system error codes +=================================== + +.. module:: errno + :synopsis: system error codes + +|see_cpython_module| :mod:`cpython:errno`. + +This module provides access to symbolic error codes for `OSError` exception. + +Constants +--------- + +.. data:: EEXIST, EAGAIN, etc. + + Error codes, based on ANSI C/POSIX standard. All error codes start with + "E". Errors are usually accessible as ``exc.args[0]`` + where ``exc`` is an instance of `OSError`. Usage example:: + + try: + os.mkdir("my_dir") + except OSError as exc: + if exc.args[0] == errno.EEXIST: + print("Directory already exists") + +.. data:: errorcode + + Dictionary mapping numeric error codes to strings with symbolic error + code (see above):: + + >>> print(errno.errorcode[uerrno.EEXIST]) + EEXIST diff --git a/docs/library/index.rst b/docs/library/index.rst index e91387242..94bd8a656 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -7,34 +7,20 @@ 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. +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``, ``uio``, ``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/io.rst b/docs/library/io.rst new file mode 100644 index 000000000..37e3eb7c9 --- /dev/null +++ b/docs/library/io.rst @@ -0,0 +1,114 @@ +:mod:`io` -- input/output streams +================================== + +.. module:: io + :synopsis: input/output streams + +|see_cpython_module| :mod:`cpython:io`. + +This module contains additional types of ``stream`` (file-like) objects +and helper functions. + +Conceptual hierarchy +-------------------- + +.. admonition:: Difference to CPython + :class: attention + + Conceptual hierarchy of stream base classes is simplified in MicroPython, + as described in this section. + +(Abstract) base stream classes, which serve as a foundation for behavior +of all the concrete classes, adhere to few dichotomies (pair-wise +classifications) in CPython. In MicroPython, they are somewhat simplified +and made implicit to achieve higher efficiencies and save resources. + +An important dichotomy in CPython is unbuffered vs buffered streams. In +MicroPython, all streams are currently unbuffered. This is because all +modern OSes, and even many RTOSes and filesystem drivers already perform +buffering on their side. Adding another layer of buffering is counter- +productive (an issue known as "bufferbloat") and takes precious memory. +Note that there still cases where buffering may be useful, so we may +introduce optional buffering support at a later time. + +But in CPython, another important dichotomy is tied with "bufferedness" - +it's whether a stream may incur short read/writes or not. A short read +is when a user asks e.g. 10 bytes from a stream, but gets less, similarly +for writes. In CPython, unbuffered streams are automatically short +operation susceptible, while buffered are guarantee against them. The +no short read/writes is an important trait, as it allows to develop +more concise and efficient programs - something which is highly desirable +for MicroPython. So, while MicroPython doesn't support buffered streams, +it still provides for no-short-operations streams. Whether there will +be short operations or not depends on each particular class' needs, but +developers are strongly advised to favor no-short-operations behavior +for the reasons stated above. For example, MicroPython sockets are +guaranteed to avoid short read/writes. Actually, at this time, there is +no example of a short-operations stream class in the core, and one would +be a port-specific class, where such a need is governed by hardware +peculiarities. + +The no-short-operations behavior gets tricky in case of non-blocking +streams, blocking vs non-blocking behavior being another CPython dichotomy, +fully supported by MicroPython. Non-blocking streams never wait for +data either to arrive or be written - they read/write whatever possible, +or signal lack of data (or ability to write data). Clearly, this conflicts +with "no-short-operations" policy, and indeed, a case of non-blocking +buffered (and this no-short-ops) streams is convoluted in CPython - in +some places, such combination is prohibited, in some it's undefined or +just not documented, in some cases it raises verbose exceptions. The +matter is much simpler in MicroPython: non-blocking stream are important +for efficient asynchronous operations, so this property prevails on +the "no-short-ops" one. So, while blocking streams will avoid short +reads/writes whenever possible (the only case to get a short read is +if end of file is reached, or in case of error (but errors don't +return short data, but raise exceptions)), non-blocking streams may +produce short data to avoid blocking the operation. + +The final dichotomy is binary vs text streams. MicroPython of course +supports these, but while in CPython text streams are inherently +buffered, they aren't in MicroPython. (Indeed, that's one of the cases +for which we may introduce buffering support.) + +Note that for efficiency, MicroPython doesn't provide abstract base +classes corresponding to the hierarchy above, and it's not possible +to implement, or subclass, a stream class in pure Python. + +Functions +--------- + +.. function:: open(name, mode='r', **kwargs) + + Open a file. Builtin ``open()`` function is aliased to this function. + All ports (which provide access to file system) are required to support + ``mode`` parameter, but support for other arguments vary by port. + +Classes +------- + +.. class:: FileIO(...) + + This is type of a file open in binary mode, e.g. using ``open(name, "rb")``. + You should not instantiate this class directly. + +.. class:: TextIOWrapper(...) + + This is type of a file open in text mode, e.g. using ``open(name, "rt")``. + You should not instantiate this class directly. + +.. class:: StringIO([string]) +.. class:: BytesIO([string]) + + In-memory file-like objects for input/output. `StringIO` is used for + text-mode I/O (similar to a normal file opened with "t" modifier). + `BytesIO` is used for binary-mode I/O (similar to a normal file + opened with "b" modifier). Initial contents of file-like objects + can be specified with `string` parameter (should be normal string + for `StringIO` or bytes object for `BytesIO`). All the usual file + methods like ``read()``, ``write()``, ``seek()``, ``flush()``, + ``close()`` are available on these objects, and additionally, a + following method: + + .. method:: getvalue() + + Get the current contents of the underlying buffer which holds data. diff --git a/docs/library/json.rst b/docs/library/json.rst new file mode 100644 index 000000000..21574e556 --- /dev/null +++ b/docs/library/json.rst @@ -0,0 +1,35 @@ +:mod:`json` -- JSON encoding and decoding +========================================== + +.. module:: json + :synopsis: JSON encoding and decoding + +|see_cpython_module| :mod:`cpython:json`. + +This modules allows to convert between Python objects and the JSON +data format. + +Functions +--------- + +.. function:: dump(obj, stream) + + Serialise ``obj`` to a JSON string, writing it to the given *stream*. + +.. function:: dumps(obj) + + Return ``obj`` represented as a JSON string. + +.. function:: load(stream) + + Parse the given ``stream``, interpreting it as a JSON string and + deserialising the data to a Python object. The resulting object is + returned. + + Parsing continues until end-of-file is encountered. + A :exc:`ValueError` is raised if the data in ``stream`` is not correctly formed. + +.. function:: loads(str) + + Parse the JSON *str* and return an object. Raises :exc:`ValueError` if the + string is not correctly formed. diff --git a/docs/library/re.rst b/docs/library/re.rst new file mode 100644 index 000000000..bdcc9f52c --- /dev/null +++ b/docs/library/re.rst @@ -0,0 +1,101 @@ +:mod:`re` -- simple regular expressions +======================================== + +.. module:: re + :synopsis: regular expressions + +|see_cpython_module| :mod:`cpython:re`. + +This module implements regular expression operations. Regular expression +syntax supported is a subset of CPython ``re`` module (and actually is +a subset of POSIX extended regular expressions). + +Supported operators are: + +``'.'`` + Match any character. + +``'[...]'`` + Match set of characters. Individual characters and ranges are supported, + including negated sets (e.g. ``[^a-c]``). + +``'^'`` + +``'$'`` + +``'?'`` + +``'*'`` + +``'+'`` + +``'??'`` + +``'*?'`` + +``'+?'`` + +``'|'`` + +``'(...)'`` + Grouping. Each group is capturing (a substring it captures can be accessed + with `match.group()` method). + +**NOT SUPPORTED**: Counted repetitions (``{m,n}``), more advanced assertions +(``\b``, ``\B``), named groups (``(?P...)``), non-capturing groups +(``(?:...)``), etc. + + +Functions +--------- + +.. function:: compile(regex_str, [flags]) + + Compile regular expression, return `regex ` object. + +.. function:: match(regex_str, string) + + Compile *regex_str* and match against *string*. Match always happens + from starting position in a string. + +.. function:: search(regex_str, string) + + Compile *regex_str* and search it in a *string*. Unlike `match`, this will search + string for first position which matches regex (which still may be + 0 if regex is anchored). + +.. data:: DEBUG + + Flag value, display debug information about compiled expression. + + +.. _regex: + +Regex objects +------------- + +Compiled regular expression. Instances of this class are created using +`re.compile()`. + +.. method:: regex.match(string) + regex.search(string) + + Similar to the module-level functions :meth:`match` and :meth:`search`. + Using methods is (much) more efficient if the same regex is applied to + multiple strings. + +.. method:: regex.split(string, max_split=-1) + + Split a *string* using regex. If *max_split* is given, it specifies + maximum number of splits to perform. Returns list of strings (there + may be up to *max_split+1* elements if it's specified). + +Match objects +------------- + +Match objects as returned by `match()` and `search()` methods. + +.. method:: match.group([index]) + + Return matching (sub)string. *index* is 0 for entire match, + 1 and above for each capturing group. Only numeric groups are supported. diff --git a/docs/library/uerrno.rst b/docs/library/uerrno.rst deleted file mode 100644 index 72f71f0aa..000000000 --- a/docs/library/uerrno.rst +++ /dev/null @@ -1,34 +0,0 @@ -:mod:`uerrno` -- system error codes -=================================== - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: uerrno - :synopsis: system error codes - -|see_cpython_module| :mod:`cpython:errno`. - -This module provides access to symbolic error codes for `OSError` exception. - -Constants ---------- - -.. data:: EEXIST, EAGAIN, etc. - - Error codes, based on ANSI C/POSIX standard. All error codes start with - "E". Errors are usually accessible as ``exc.args[0]`` - where ``exc`` is an instance of `OSError`. Usage example:: - - try: - os.mkdir("my_dir") - except OSError as exc: - if exc.args[0] == uerrno.EEXIST: - print("Directory already exists") - -.. data:: errorcode - - Dictionary mapping numeric error codes to strings with symbolic error - code (see above):: - - >>> print(uerrno.errorcode[uerrno.EEXIST]) - EEXIST diff --git a/docs/library/uio.rst b/docs/library/uio.rst deleted file mode 100644 index d1f7c111f..000000000 --- a/docs/library/uio.rst +++ /dev/null @@ -1,116 +0,0 @@ -:mod:`uio` -- input/output streams -================================== - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: uio - :synopsis: input/output streams - -|see_cpython_module| :mod:`cpython:io`. - -This module contains additional types of ``stream`` (file-like) objects -and helper functions. - -Conceptual hierarchy --------------------- - -.. admonition:: Difference to CPython - :class: attention - - Conceptual hierarchy of stream base classes is simplified in MicroPython, - as described in this section. - -(Abstract) base stream classes, which serve as a foundation for behavior -of all the concrete classes, adhere to few dichotomies (pair-wise -classifications) in CPython. In MicroPython, they are somewhat simplified -and made implicit to achieve higher efficiencies and save resources. - -An important dichotomy in CPython is unbuffered vs buffered streams. In -MicroPython, all streams are currently unbuffered. This is because all -modern OSes, and even many RTOSes and filesystem drivers already perform -buffering on their side. Adding another layer of buffering is counter- -productive (an issue known as "bufferbloat") and takes precious memory. -Note that there still cases where buffering may be useful, so we may -introduce optional buffering support at a later time. - -But in CPython, another important dichotomy is tied with "bufferedness" - -it's whether a stream may incur short read/writes or not. A short read -is when a user asks e.g. 10 bytes from a stream, but gets less, similarly -for writes. In CPython, unbuffered streams are automatically short -operation susceptible, while buffered are guarantee against them. The -no short read/writes is an important trait, as it allows to develop -more concise and efficient programs - something which is highly desirable -for MicroPython. So, while MicroPython doesn't support buffered streams, -it still provides for no-short-operations streams. Whether there will -be short operations or not depends on each particular class' needs, but -developers are strongly advised to favor no-short-operations behavior -for the reasons stated above. For example, MicroPython sockets are -guaranteed to avoid short read/writes. Actually, at this time, there is -no example of a short-operations stream class in the core, and one would -be a port-specific class, where such a need is governed by hardware -peculiarities. - -The no-short-operations behavior gets tricky in case of non-blocking -streams, blocking vs non-blocking behavior being another CPython dichotomy, -fully supported by MicroPython. Non-blocking streams never wait for -data either to arrive or be written - they read/write whatever possible, -or signal lack of data (or ability to write data). Clearly, this conflicts -with "no-short-operations" policy, and indeed, a case of non-blocking -buffered (and this no-short-ops) streams is convoluted in CPython - in -some places, such combination is prohibited, in some it's undefined or -just not documented, in some cases it raises verbose exceptions. The -matter is much simpler in MicroPython: non-blocking stream are important -for efficient asynchronous operations, so this property prevails on -the "no-short-ops" one. So, while blocking streams will avoid short -reads/writes whenever possible (the only case to get a short read is -if end of file is reached, or in case of error (but errors don't -return short data, but raise exceptions)), non-blocking streams may -produce short data to avoid blocking the operation. - -The final dichotomy is binary vs text streams. MicroPython of course -supports these, but while in CPython text streams are inherently -buffered, they aren't in MicroPython. (Indeed, that's one of the cases -for which we may introduce buffering support.) - -Note that for efficiency, MicroPython doesn't provide abstract base -classes corresponding to the hierarchy above, and it's not possible -to implement, or subclass, a stream class in pure Python. - -Functions ---------- - -.. function:: open(name, mode='r', **kwargs) - - Open a file. Builtin ``open()`` function is aliased to this function. - All ports (which provide access to file system) are required to support - ``mode`` parameter, but support for other arguments vary by port. - -Classes -------- - -.. class:: FileIO(...) - - This is type of a file open in binary mode, e.g. using ``open(name, "rb")``. - You should not instantiate this class directly. - -.. class:: TextIOWrapper(...) - - This is type of a file open in text mode, e.g. using ``open(name, "rt")``. - You should not instantiate this class directly. - -.. class:: StringIO([string]) -.. class:: BytesIO([string]) - - In-memory file-like objects for input/output. `StringIO` is used for - text-mode I/O (similar to a normal file opened with "t" modifier). - `BytesIO` is used for binary-mode I/O (similar to a normal file - opened with "b" modifier). Initial contents of file-like objects - can be specified with `string` parameter (should be normal string - for `StringIO` or bytes object for `BytesIO`). All the usual file - methods like ``read()``, ``write()``, ``seek()``, ``flush()``, - ``close()`` are available on these objects, and additionally, a - following method: - - .. method:: getvalue() - - Get the current contents of the underlying buffer which holds data. diff --git a/docs/library/ujson.rst b/docs/library/ujson.rst deleted file mode 100644 index 4ed91f053..000000000 --- a/docs/library/ujson.rst +++ /dev/null @@ -1,37 +0,0 @@ -:mod:`ujson` -- JSON encoding and decoding -========================================== - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: ujson - :synopsis: JSON encoding and decoding - -|see_cpython_module| :mod:`cpython:json`. - -This modules allows to convert between Python objects and the JSON -data format. - -Functions ---------- - -.. function:: dump(obj, stream) - - Serialise ``obj`` to a JSON string, writing it to the given *stream*. - -.. function:: dumps(obj) - - Return ``obj`` represented as a JSON string. - -.. function:: load(stream) - - Parse the given ``stream``, interpreting it as a JSON string and - deserialising the data to a Python object. The resulting object is - returned. - - Parsing continues until end-of-file is encountered. - A :exc:`ValueError` is raised if the data in ``stream`` is not correctly formed. - -.. function:: loads(str) - - Parse the JSON *str* and return an object. Raises :exc:`ValueError` if the - string is not correctly formed. diff --git a/docs/library/ure.rst b/docs/library/ure.rst deleted file mode 100644 index 4af182b01..000000000 --- a/docs/library/ure.rst +++ /dev/null @@ -1,103 +0,0 @@ -:mod:`ure` -- simple regular expressions -======================================== - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: ure - :synopsis: regular expressions - -|see_cpython_module| :mod:`cpython:re`. - -This module implements regular expression operations. Regular expression -syntax supported is a subset of CPython ``re`` module (and actually is -a subset of POSIX extended regular expressions). - -Supported operators are: - -``'.'`` - Match any character. - -``'[...]'`` - Match set of characters. Individual characters and ranges are supported, - including negated sets (e.g. ``[^a-c]``). - -``'^'`` - -``'$'`` - -``'?'`` - -``'*'`` - -``'+'`` - -``'??'`` - -``'*?'`` - -``'+?'`` - -``'|'`` - -``'(...)'`` - Grouping. Each group is capturing (a substring it captures can be accessed - with `match.group()` method). - -**NOT SUPPORTED**: Counted repetitions (``{m,n}``), more advanced assertions -(``\b``, ``\B``), named groups (``(?P...)``), non-capturing groups -(``(?:...)``), etc. - - -Functions ---------- - -.. function:: compile(regex_str, [flags]) - - Compile regular expression, return `regex ` object. - -.. function:: match(regex_str, string) - - Compile *regex_str* and match against *string*. Match always happens - from starting position in a string. - -.. function:: search(regex_str, string) - - Compile *regex_str* and search it in a *string*. Unlike `match`, this will search - string for first position which matches regex (which still may be - 0 if regex is anchored). - -.. data:: DEBUG - - Flag value, display debug information about compiled expression. - - -.. _regex: - -Regex objects -------------- - -Compiled regular expression. Instances of this class are created using -`ure.compile()`. - -.. method:: regex.match(string) - regex.search(string) - - Similar to the module-level functions :meth:`match` and :meth:`search`. - Using methods is (much) more efficient if the same regex is applied to - multiple strings. - -.. method:: regex.split(string, max_split=-1) - - Split a *string* using regex. If *max_split* is given, it specifies - maximum number of splits to perform. Returns list of strings (there - may be up to *max_split+1* elements if it's specified). - -Match objects -------------- - -Match objects as returned by `match()` and `search()` methods. - -.. method:: match.group([index]) - - Return matching (sub)string. *index* is 0 for entire match, - 1 and above for each capturing group. Only numeric groups are supported. diff --git a/docs/shared_bindings_matrix.py b/docs/shared_bindings_matrix.py index f38c0b64a..ca6ddd3ed 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', '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(): diff --git a/ports/atmel-samd/boards/circuitplayground_express_displayio/mpconfigboard.h b/ports/atmel-samd/boards/circuitplayground_express_displayio/mpconfigboard.h index 4b0c324fa..fc189e662 100644 --- a/ports/atmel-samd/boards/circuitplayground_express_displayio/mpconfigboard.h +++ b/ports/atmel-samd/boards/circuitplayground_express_displayio/mpconfigboard.h @@ -44,4 +44,5 @@ #define IGNORE_PIN_PA24 1 #define IGNORE_PIN_PA25 1 -#define MICROPY_PY_URE 0 +// Can't fit. +#define CIRCUITPY_RE 0 diff --git a/ports/atmel-samd/mpconfigport.h b/ports/atmel-samd/mpconfigport.h index bce89e0b9..d2a529485 100644 --- a/ports/atmel-samd/mpconfigport.h +++ b/ports/atmel-samd/mpconfigport.h @@ -45,11 +45,7 @@ #define MICROPY_PY_BUILTINS_COMPLEX (0) #define MICROPY_PY_BUILTINS_NOTIMPLEMENTED (0) #define MICROPY_PY_FUNCTION_ATTRS (0) -// MICROPY_PY_UJSON depends on MICROPY_PY_IO -#define MICROPY_PY_IO (0) #define MICROPY_PY_REVERSE_SPECIAL_METHODS (0) -#define MICROPY_PY_UBINASCII (0) -#define MICROPY_PY_UJSON (0) #define MICROPY_PY_COLLECTIONS_ORDEREDDICT (0) #define MICROPY_PY_UERRNO_LIST \ X(EPERM) \ @@ -84,9 +80,6 @@ #define SPI_FLASH_MAX_BAUDRATE 24000000 #define MICROPY_PY_BUILTINS_NOTIMPLEMENTED (1) #define MICROPY_PY_FUNCTION_ATTRS (1) -// MICROPY_PY_UJSON depends on MICROPY_PY_IO -#define MICROPY_PY_IO (1) -#define MICROPY_PY_UJSON (1) // MICROPY_PY_UERRNO_LIST - Use the default #endif // SAM_D5X_E5X diff --git a/ports/atmel-samd/mpconfigport.mk b/ports/atmel-samd/mpconfigport.mk index 17e3995bf..fb9cdf2e6 100644 --- a/ports/atmel-samd/mpconfigport.mk +++ b/ports/atmel-samd/mpconfigport.mk @@ -20,26 +20,16 @@ endif # Put samd21-only choices here. ifeq ($(CHIP_FAMILY),samd21) -# frequencyio not yet verified as working on SAMD21, though make it possible to override. -ifndef CIRCUITPY_AUDIOMIXER -CIRCUITPY_AUDIOMIXER = 0 -endif - -ifndef CIRCUITPY_AUDIOMP3 -CIRCUITPY_AUDIOMP3 = 0 -endif - -ifndef CIRCUITPY_BUILTINS_POW3 -CIRCUITPY_BUILTINS_POW3 = 0 -endif -ifndef CIRCUITPY_FREQUENCYIO -CIRCUITPY_FREQUENCYIO = 0 -endif +# The ?='s allow overriding in mpconfigboard.mk. -ifndef CIRCUITPY_TOUCHIO_USE_NATIVE -CIRCUITPY_TOUCHIO_USE_NATIVE = 1 -endif +CIRCUITPY_AUDIOMIXER ?= 0 +CIRCUITPY_BINASCII ?= 0 +CIRCUITPY_AUDIOMP3 ?= 0 +CIRCUITPY_BUILTINS_POW3 ?= 0 +CIRCUITPY_FREQUENCYIO ?= 0 +CIRCUITPY_JSON ?= 0 +CIRCUITPY_TOUCHIO_USE_NATIVE ?= 1 # No room for HCI _bleio on SAMD21. CIRCUITPY_BLEIO_HCI = 0 @@ -71,27 +61,13 @@ ifeq ($(CHIP_FAMILY),samd51) # No native touchio on SAMD51. CIRCUITPY_TOUCHIO_USE_NATIVE = 0 -# The ifndef's allow overriding in mpconfigboard.mk. - -ifndef CIRCUITPY_NETWORK -CIRCUITPY_NETWORK = 0 -endif - -ifndef CIRCUITPY_PS2IO -CIRCUITPY_PS2IO = 1 -endif - -ifndef CIRCUITPY_SAMD -CIRCUITPY_SAMD = 1 -endif - -ifndef CIRCUITPY_RGBMATRIX -CIRCUITPY_RGBMATRIX = $(CIRCUITPY_FULL_BUILD) -endif +# The ?='s allow overriding in mpconfigboard.mk. -ifndef CIRCUITPY_FRAMEBUFFERIO -CIRCUITPY_FRAMEBUFFERIO = $(CIRCUITPY_FULL_BUILD) -endif +CIRCUITPY_NETWORK ?= 0 +CIRCUITPY_PS2IO ?= 1 +CIRCUITPY_SAMD ?= 1 +CIRCUITPY_RGBMATRIX ?= $(CIRCUITPY_FULL_BUILD) +CIRCUITPY_FRAMEBUFFERIO ?= $(CIRCUITPY_FULL_BUILD) endif # samd51 diff --git a/ports/esp32s2/mpconfigport.h b/ports/esp32s2/mpconfigport.h index 9c0fd9da3..0cf695bc9 100644 --- a/ports/esp32s2/mpconfigport.h +++ b/ports/esp32s2/mpconfigport.h @@ -30,7 +30,6 @@ #define MICROPY_NLR_THUMB (0) -#define MICROPY_PY_UJSON (1) #define MICROPY_USE_INTERNAL_PRINTF (0) #define MICROPY_PY_SYS_PLATFORM "Espressif ESP32-S2" diff --git a/ports/litex/mpconfigport.h b/ports/litex/mpconfigport.h index a7caf8526..5f739e49e 100644 --- a/ports/litex/mpconfigport.h +++ b/ports/litex/mpconfigport.h @@ -31,8 +31,6 @@ #define CIRCUITPY_INTERNAL_NVM_SIZE (0) #define MICROPY_NLR_THUMB (0) #define MICROPY_PY_REVERSE_SPECIAL_METHODS (1) -#define MICROPY_PY_UBINASCII (1) -#define MICROPY_PY_UJSON (1) #include "py/circuitpy_mpconfig.h" diff --git a/ports/mimxrt10xx/mpconfigport.h b/ports/mimxrt10xx/mpconfigport.h index 7496256d0..51e0ef9ff 100644 --- a/ports/mimxrt10xx/mpconfigport.h +++ b/ports/mimxrt10xx/mpconfigport.h @@ -41,8 +41,6 @@ extern uint8_t _ld_default_stack_size; #define CIRCUITPY_DEFAULT_STACK_SIZE ((uint32_t) &_ld_default_stack_size) #define MICROPY_PY_BUILTINS_NOTIMPLEMENTED (0) #define MICROPY_PY_FUNCTION_ATTRS (0) -#define MICROPY_PY_IO (1) -#define MICROPY_PY_UJSON (1) #define MICROPY_PY_REVERSE_SPECIAL_METHODS (1) diff --git a/ports/nrf/mpconfigport.h b/ports/nrf/mpconfigport.h index 4ed42cd82..3ac41a5e4 100644 --- a/ports/nrf/mpconfigport.h +++ b/ports/nrf/mpconfigport.h @@ -35,11 +35,8 @@ #include "peripherals/nrf/nvm.h" // for FLASH_PAGE_SIZE #define MICROPY_PY_FUNCTION_ATTRS (1) -#define MICROPY_PY_IO (1) #define MICROPY_PY_REVERSE_SPECIAL_METHODS (1) #define MICROPY_PY_SYS_STDIO_BUFFER (1) -#define MICROPY_PY_UBINASCII (1) -#define MICROPY_PY_UJSON (1) // 24kiB stack #define CIRCUITPY_DEFAULT_STACK_SIZE (24*1024) diff --git a/ports/raspberrypi/mpconfigport.h b/ports/raspberrypi/mpconfigport.h index 3fdc8febb..75cbd1ba8 100644 --- a/ports/raspberrypi/mpconfigport.h +++ b/ports/raspberrypi/mpconfigport.h @@ -27,7 +27,9 @@ #ifndef __INCLUDED_MPCONFIGPORT_H #define __INCLUDED_MPCONFIGPORT_H -#define MICROPY_PY_UJSON (1) +#define CIRCUITPY_BINASCII (1) +#define CIRCUITPY_ERRNO (1) +#define CIRCUITPY_JSON (1) #define CIRCUITPY_INTERNAL_NVM_SIZE 0 diff --git a/ports/stm/mpconfigport.h b/ports/stm/mpconfigport.h index 9489b4765..7cdab04f6 100644 --- a/ports/stm/mpconfigport.h +++ b/ports/stm/mpconfigport.h @@ -31,9 +31,7 @@ #include #define MICROPY_PY_FUNCTION_ATTRS (1) -#define MICROPY_PY_IO (1) #define MICROPY_PY_REVERSE_SPECIAL_METHODS (1) -#define MICROPY_PY_UJSON (1) extern uint8_t _ld_default_stack_size; diff --git a/py/circuitpy_mpconfig.h b/py/circuitpy_mpconfig.h index 35f1227a9..c193e61c4 100644 --- a/py/circuitpy_mpconfig.h +++ b/py/circuitpy_mpconfig.h @@ -195,21 +195,14 @@ typedef long mp_off_t; #define MICROPY_PY_BUILTINS_STR_CENTER (CIRCUITPY_FULL_BUILD) #define MICROPY_PY_BUILTINS_STR_PARTITION (CIRCUITPY_FULL_BUILD) #define MICROPY_PY_BUILTINS_STR_SPLITLINES (CIRCUITPY_FULL_BUILD) -#define MICROPY_PY_UERRNO (CIRCUITPY_FULL_BUILD) #ifndef MICROPY_PY_COLLECTIONS_ORDEREDDICT #define MICROPY_PY_COLLECTIONS_ORDEREDDICT (CIRCUITPY_FULL_BUILD) #endif -#ifndef MICROPY_PY_UBINASCII -#define MICROPY_PY_UBINASCII (CIRCUITPY_FULL_BUILD) -#endif // Opposite setting is deliberate. -#define MICROPY_PY_UERRNO_ERRORCODE (!CIRCUITPY_FULL_BUILD) -#ifndef MICROPY_PY_URE -#define MICROPY_PY_URE (CIRCUITPY_FULL_BUILD) -#endif -#define MICROPY_PY_URE_MATCH_GROUPS (CIRCUITPY_FULL_BUILD) -#define MICROPY_PY_URE_MATCH_SPAN_START_END (CIRCUITPY_FULL_BUILD) -#define MICROPY_PY_URE_SUB (CIRCUITPY_FULL_BUILD) +#define MICROPY_PY_UERRNO_ERRORCODE (!CIRCUITPY_RE) +#define MICROPY_PY_URE_MATCH_GROUPS (CIRCUITPY_RE) +#define MICROPY_PY_URE_MATCH_SPAN_START_END (CIRCUITPY_RE) +#define MICROPY_PY_URE_SUB (CIRCUITPY_RE) // LONGINT_IMPL_xxx are defined in the Makefile. // @@ -301,6 +294,13 @@ extern const struct _mp_obj_module_t audiopwmio_module; #define AUDIOPWMIO_MODULE #endif +#if CIRCUITPY_BINASCII +#define MICROPY_PY_UBINASCII CIRCUITPY_BINASCII +#define BINASCII_MODULE { MP_ROM_QSTR(MP_QSTR_binascii), MP_ROM_PTR(&mp_module_ubinascii) }, +#else +#define BINASCII_MODULE +#endif + #if CIRCUITPY_BITBANGIO #define BITBANGIO_MODULE { MP_OBJ_NEW_QSTR(MP_QSTR_bitbangio), (mp_obj_t)&bitbangio_module }, extern const struct _mp_obj_module_t bitbangio_module; @@ -399,6 +399,13 @@ extern const struct _mp_obj_module_t terminalio_module; #define TERMINALIO_MODULE #endif +#if CIRCUITPY_ERRNO +#define MICROPY_PY_UERRNO (1) +#define ERRNO_MODULE { MP_ROM_QSTR(MP_QSTR_errno), MP_ROM_PTR(&mp_module_uerrno) }, +#else +#define ERRNO_MODULE +#endif + #if CIRCUITPY_ESPIDF extern const struct _mp_obj_module_t espidf_module; #define ESPIDF_MODULE { MP_OBJ_NEW_QSTR(MP_QSTR_espidf),(mp_obj_t)&espidf_module }, @@ -470,6 +477,18 @@ extern const struct _mp_obj_module_t ipaddress_module; #define IPADDRESS_MODULE #endif +#if CIRCUITPY_JSON +#define MICROPY_PY_UJSON (1) +#define MICROPY_PY_IO (1) +#define JSON_MODULE { MP_ROM_QSTR(MP_QSTR_json), MP_ROM_PTR(&mp_module_ujson) }, +#else +#ifndef MICROPY_PY_IO +// We don't need MICROPY_PY_IO unless someone else wants it. +#define MICROPY_PY_IO (0) +#endif +#define JSON_MODULE +#endif + #if CIRCUITPY_MATH extern const struct _mp_obj_module_t math_module; #define MATH_MODULE { MP_OBJ_NEW_QSTR(MP_QSTR_math), (mp_obj_t)&math_module }, @@ -588,6 +607,13 @@ extern const struct _mp_obj_module_t random_module; #define RANDOM_MODULE #endif +#if CIRCUITPY_RE +#define MICROPY_PY_URE (1) +#define RE_MODULE { MP_ROM_QSTR(MP_QSTR_re), MP_ROM_PTR(&mp_module_ure) }, +#else +#define RE_MODULE +#endif + #if CIRCUITPY_RGBMATRIX extern const struct _mp_obj_module_t rgbmatrix_module; #define RGBMATRIX_MODULE { MP_OBJ_NEW_QSTR(MP_QSTR_rgbmatrix),(mp_obj_t)&rgbmatrix_module }, @@ -730,25 +756,6 @@ extern const struct _mp_obj_module_t ustack_module; #define USTACK_MODULE #endif -// These modules are not yet in shared-bindings, but we prefer the non-uxxx names. -#if MICROPY_PY_UBINASCII -#define BINASCII_MODULE { MP_ROM_QSTR(MP_QSTR_binascii), MP_ROM_PTR(&mp_module_ubinascii) }, -#else -#define BINASCII_MODULE -#endif - -#if MICROPY_PY_UERRNO -#define ERRNO_MODULE { MP_ROM_QSTR(MP_QSTR_errno), MP_ROM_PTR(&mp_module_uerrno) }, -#else -#define ERRNO_MODULE -#endif - -#if MICROPY_PY_UJSON -#define JSON_MODULE { MP_ROM_QSTR(MP_QSTR_json), MP_ROM_PTR(&mp_module_ujson) }, -#else -#define JSON_MODULE -#endif - #if defined(CIRCUITPY_ULAB) && CIRCUITPY_ULAB // ulab requires reverse special methods #if defined(MICROPY_PY_REVERSE_SPECIAL_METHODS) && !MICROPY_PY_REVERSE_SPECIAL_METHODS @@ -760,12 +767,6 @@ extern const struct _mp_obj_module_t ustack_module; #define ULAB_MODULE #endif -#if MICROPY_PY_URE -#define RE_MODULE { MP_ROM_QSTR(MP_QSTR_re), MP_ROM_PTR(&mp_module_ure) }, -#else -#define RE_MODULE -#endif - // This is not a top-level module; it's microcontroller.watchdog. #if CIRCUITPY_WATCHDOG extern const struct _mp_obj_module_t watchdog_module; diff --git a/py/circuitpy_mpconfig.mk b/py/circuitpy_mpconfig.mk index 9c9b17f4b..141ad05f8 100644 --- a/py/circuitpy_mpconfig.mk +++ b/py/circuitpy_mpconfig.mk @@ -86,6 +86,9 @@ endif endif CFLAGS += -DCIRCUITPY_AUDIOMP3=$(CIRCUITPY_AUDIOMP3) +CIRCUITPY_BINASCII ?= $(CIRCUITPY_FULL_BUILD) +CFLAGS += -DCIRCUITPY_BINASCII=$(CIRCUITPY_BINASCII) + CIRCUITPY_BITBANGIO ?= $(CIRCUITPY_FULL_BUILD) CFLAGS += -DCIRCUITPY_BITBANGIO=$(CIRCUITPY_BITBANGIO) @@ -124,6 +127,9 @@ CFLAGS += -DCIRCUITPY_COUNTIO=$(CIRCUITPY_COUNTIO) CIRCUITPY_DISPLAYIO ?= $(CIRCUITPY_FULL_BUILD) CFLAGS += -DCIRCUITPY_DISPLAYIO=$(CIRCUITPY_DISPLAYIO) +CIRCUITPY_ERRNO ?= $(CIRCUITPY_FULL_BUILD) +CFLAGS += -DCIRCUITPY_ERRNO=$(CIRCUITPY_ERRNO) + # CIRCUITPY_ESPIDF is handled in the esp32s2 tree. # Only for ESP32S chips. # Assume not a ESP build. @@ -158,6 +164,9 @@ CFLAGS += -DCIRCUITPY_I2CPERIPHERAL=$(CIRCUITPY_I2CPERIPHERAL) CIRCUITPY_IPADDRESS ?= $(CIRCUITPY_WIFI) CFLAGS += -DCIRCUITPY_IPADDRESS=$(CIRCUITPY_IPADDRESS) +CIRCUITPY_JSON ?= $(CIRCUITPY_FULL_BUILD) +CFLAGS += -DCIRCUITPY_JSON=$(CIRCUITPY_JSON) + CIRCUITPY_MATH ?= 1 CFLAGS += -DCIRCUITPY_MATH=$(CIRCUITPY_MATH) @@ -204,6 +213,9 @@ CFLAGS += -DCIRCUITPY_PWMIO=$(CIRCUITPY_PWMIO) CIRCUITPY_RANDOM ?= 1 CFLAGS += -DCIRCUITPY_RANDOM=$(CIRCUITPY_RANDOM) +CIRCUITPY_RE ?= $(CIRCUITPY_FULL_BUILD) +CFLAGS += -DCIRCUITPY_RE=$(CIRCUITPY_RE) + # CIRCUITPY_RP2PIO is handled in the raspberrypi tree. # Only for rp2 chips. # Assume not a rp2 build. diff --git a/shared-bindings/support_matrix.rst b/shared-bindings/support_matrix.rst index 1b75e0256..a2fb7987d 100644 --- a/shared-bindings/support_matrix.rst +++ b/shared-bindings/support_matrix.rst @@ -1,7 +1,7 @@ .. _module-support-matrix: -Support Matrix -=============== +Module Support Matrix - Which Modules Are Available on Which Boards +=================================================================== The following table lists the available built-in modules for each CircuitPython capable board. -- cgit v1.2.3 From 34d63debd5c339a37009b961b9b51defcdf540ae Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Mon, 25 Jan 2021 08:21:55 -0500 Subject: Remove obsolete esp.rst, network.rst --- docs/library/esp.rst | 85 --------------- docs/library/network.rst | 278 ----------------------------------------------- 2 files changed, 363 deletions(-) delete mode 100644 docs/library/esp.rst delete mode 100644 docs/library/network.rst (limited to 'docs') 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/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 `` -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 - ============= =========== -- cgit v1.2.3 From a9f339b4619a55cf5748124180e43afca32d8fb7 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Mon, 25 Jan 2021 22:40:31 -0500 Subject: typo in circuitpy_mpconfig.h; forgot cxd56 port --- docs/shared_bindings_matrix.py | 2 +- py/circuitpy_mpconfig.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/shared_bindings_matrix.py b/docs/shared_bindings_matrix.py index ca6ddd3ed..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', 'raspberrypi', 'stm'] +SUPPORTED_PORTS = ['atmel-samd', 'cxd56', 'esp32s2', 'litex', 'mimxrt10xx', 'nrf', 'raspberrypi', 'stm'] def get_circuitpython_root_dir(): """ The path to the root './circuitpython' directory diff --git a/py/circuitpy_mpconfig.h b/py/circuitpy_mpconfig.h index c193e61c4..7c7768391 100644 --- a/py/circuitpy_mpconfig.h +++ b/py/circuitpy_mpconfig.h @@ -199,7 +199,7 @@ typedef long mp_off_t; #define MICROPY_PY_COLLECTIONS_ORDEREDDICT (CIRCUITPY_FULL_BUILD) #endif // Opposite setting is deliberate. -#define MICROPY_PY_UERRNO_ERRORCODE (!CIRCUITPY_RE) +#define MICROPY_PY_UERRNO_ERRORCODE (!CIRCUITPY_FULL_BUILD) #define MICROPY_PY_URE_MATCH_GROUPS (CIRCUITPY_RE) #define MICROPY_PY_URE_MATCH_SPAN_START_END (CIRCUITPY_RE) #define MICROPY_PY_URE_SUB (CIRCUITPY_RE) -- cgit v1.2.3 From 5b4249e365f620f7732ff2079fe345eda5074cbf Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Mon, 25 Jan 2021 23:06:47 -0500 Subject: fix doc typos --- docs/library/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/library/index.rst b/docs/library/index.rst index 94bd8a656..181ff0109 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -6,7 +6,7 @@ MicroPython libraries Python standard libraries and micro-libraries --------------------------------------------- -These libraries are inherited from MicroPython. +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. @@ -20,7 +20,7 @@ limited flash memory, usually on non-Express builds: These libraries are not currently enabled in any CircuitPython build, but may be in the future, with the ``u`` prefix dropped: -``uctypes`, ``uhashlib``, ``uio``, ``uzlib``. +``uctypes``, ``uhashlib``, ``uzlib``. .. toctree:: :maxdepth: 1 -- cgit v1.2.3 From 365fafb32bc2e395b1d50e75c1a7160ee31eefcd Mon Sep 17 00:00:00 2001 From: "Ryan A. Pavlik" Date: Tue, 26 Jan 2021 10:36:40 -0600 Subject: Update design_guide.rst Add CO2 as a member name, and clarify the description of eCO2. --- docs/design_guide.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') 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 | +-----------------------+-----------------------+-------------------------------------------------------------------------+ -- cgit v1.2.3