` class::
- The default setting is for 3.3V. Other values are:
+ from machine import ADC
- ==== ============================== ===============================
- vref SAMD21 SAMD51
- ==== ============================== ===============================
- 0 1.0V voltage reference internal bandgap reference (1V)
- 1 1/1.48 Analogue voltage supply Analogue voltage supply
- 2 1/2 Analogue voltage supply 1/2 Analogue voltage supply
- 3 External reference A External reference A
- 4 External reference B External reference B
- 5 - External reference C
- ==== ============================== ===============================
+ adc0 = ADC(Pin("A0")) # create ADC object on ADC pin, average=16
+ adc0.read_u16() # read value, 0-65536 across voltage range 0.0v - 3.3v
+ adc1 = ADC(Pin("A1"), average=1) # create ADC object on ADC pin, average=1
+
+The resolution of the ADC is set by the bits keyword option. The default is 12.
+Suitable values are 8, 10 and 12. If you need a higher resolution or better
+accuracy, use an external ADC. The default value of average is 16.
+Averaging is used to reduce the noise. With a value of 16 the LSB noise is
+about 1 digit. When averaging is enabled, the resolution is forced to
+12 bits. The vref=n option sets the reference voltage for the ADC.
+The default setting is for 3.3V. Other values are:
+
+========= ===== ============================== =============================
+Symbol Value SAMD21 SAMD51
+========= ===== ============================== =============================
+INT_VREF 0 1.0V voltage reference 1V internal bandgap reference
+VDDA 1 1/1.48 Analogue voltage supply Analogue voltage supply
+VDDA2 2 1/2 Analogue voltage supply 1/2 Analogue voltage supply
+AREF 3 External reference A (PA03) External reference A (PA03)
+AREFB 4 External reference B (PA04) External reference B (PA04)
+AREFC 5 External reference C (PA06)
+========= ===== ============================== =============================
+
+The callback keyword option is used for timed ADC sampling. The callback is executed
+when all data has been sampled.
ADC Methods
```````````
@@ -294,38 +304,78 @@ ADC Methods
Read a single ADC value as unsigned 16 bit quantity. The voltage range is defined
by the vref option of the constructor, the resolutions by the bits option.
-DAC (digital to analog conversion)
-----------------------------------
+.. method:: read_timed(data, freq)
-The DAC class provides a fast digital to analog conversion. Usage example::
+Read ADC values into the data buffer at a supplied frequency. The buffer
+must be preallocated. Values are stored as 16 bit quantities in the binary
+range given by the bits option. If bits=12, the value range is 0-4095.
+The voltage range is defined by the vref option.
+The sampling frequency range depends on the bits and average setting. At bits=8
+and average=1, the largest rate is >1 MHz for SAMD51 and 350kHz for SAMD21.
+the lowest sampling rate is 1 Hz. The call to the method returns immediately,
+The data transfer is done by DMA in the background, controlled by a hardware timer.
+If in the constructor a callback was defined, it will be called after all data has been
+read. Alternatively, the method busy() can be used to tell, if the capture has finished.
- from machine import DAC
+Example for a call to adc.read_timed() and a callback::
- dac0 = DAC(0) # create DAC object on DAC pin A0
- dac0.write(1023) # write value, 0-4095 across voltage range 0.0v - 3.3v
- dac1 = DAC(1) # create DAC object on DAC pin A1
- dac1.write(2000) # write value, 0-4095 across voltage range 0.0v - 3.3v
+ from machine import ADC
+ from array import array
-The resolution of the DAC is 12 bit for SAMD51 and 10 bit for SAMD21. SAMD21 devices
-have 1 DAC channel at GPIO PA02, SAMD51 devices have 2 DAC channels at GPIO PA02 and PA05.
+ def finished(adc_o):
+ print("Sampling finished on ADC", adc_o)
+
+ # create ADC object on ADC pin A0, average=1
+ adc = ADC(Pin("A0"), average=1, callback=finished)
+ buffer = array("H", bytearray(512)) # create an array for 256 ADC values
+ adc.read_timed(buffer, 10000) # read 256 12 bit values at a frequency of
+ # 10 kHz and call finished() when done.
+
+.. method:: busy()
+
+busy() returns `True` while the data acquisition using read_timed() is ongoing, `False`
+otherwise.
+
+.. method deinit()
+
+Deinitialize an ADC object and release the resources used by it, especially the ADC
+channel and the timer used for read_timed().
+
+
+DAC (digital to analogue conversion)
+------------------------------------
DAC Constructor
```````````````
-.. class:: DAC(id, *, vref=3)
+.. class:: DAC(id, *, vref=3, callback=None)
:noindex:
+
+The DAC class provides a fast digital to analogue conversion. Usage example::
+
+ from machine import DAC
+
+ dac0 = DAC(0) # create DAC object on DAC pin A0
+ dac0.write(1023) # write value, 0-4095 across voltage range 0.0V - 3.3V
+ dac1 = DAC(1) # create DAC object on DAC pin A1
+ dac1.write(2000) # write value, 0-4095 across voltage range 0.0V - 3.3V
+
+The resolution of the DAC is 12 bit for SAMD51 and 10 bit for SAMD21. SAMD21 devices
+have 1 DAC channel at GPIO PA02, accepting only 0 as id. SAMD51 devices have
+2 DAC channels at GPIO PA02 and PA05 with values 0 and 1 for the id.
The vref arguments defines the output voltage range, the callback option is used for
dac_timed(). Suitable values for vref are:
-==== ============================ ================================
-vref SAMD21 SAMD51
-==== ============================ ================================
-0 Internal voltage reference Internal bandgap reference (~1V)
-1 Analogue voltage supply Analogue voltage supply
-2 External reference Unbuffered external reference
-3 - Buffered external reference
-==== ============================ ================================
+========= ===== ============================ ================================
+Symbol Value SAMD21 SAMD51
+========= ===== ============================ ================================
+INT_VREF 0 Internal voltage reference Internal bandgap reference (~1V)
+VDDA 1 Analogue voltage supply Analogue voltage supply
+AREF 2 External reference Unbuffered external reference
+AREFB 3 Buffered external reference
+========= ===== ============================ ================================
+
DAC Methods
```````````
@@ -335,6 +385,52 @@ DAC Methods
Write a single value to the selected DAC output. The value range is 0-1023 for
SAMD21 and 0-4095 for SAMD51. The voltage range depends on the vref setting.
+.. method:: write_timed(data, freq [, count=1])
+
+The call to dac_timed() allows to output a series of analogue values at a given rate.
+data must be a buffer with 16 bit values in the range of the DAC (10 bit of 12 bit).
+freq may have a range of 1Hz to ~200kHz for SAMD21 and 1 Hz to ~500kHz for SAMD51.
+The optional argument count specifies, how often data output will be repeated. The
+range is 1 - (2**32 - 1). If count == 0, the data output will be repeated until stopped
+by a call to deinit(). If the data has been output count times, a callback will
+be called, if given.
+
+Example::
+
+ from machine import DAC
+ from array import array
+
+ data = array("H", [i for i in range(0, 4096, 256)]) # create a step sequence
+
+ def done(dac_o):
+ print("Sequence done at", dac_o)
+
+ dac = DAC(0, callback=done)
+ dac.write_timed(data, 1000, 10) # output data 10 times at a rate of 1000 values/s
+ # and call done() when finished.
+
+The data transfer is done by DMA and not affected by python code execution.
+It is possible to restart dac.write_timed() in the callback function with changed
+parameters.
+
+
+.. method:: busy()
+ :noindex:
+
+Tell, whether a write_timed() activity is ongoing. It returns `True` if yes, `False`
+otherwise.
+
+
+.. method:: deinit()
+
+Deinitialize the DAC and release the resources used by it, especially the DMA channel
+and the Timer. On most SAMD21 boards, there is just one timer available for
+dac.write_timed() and adc.read_timed(). So they cannot run both at the same time,
+and releasing the timer may be important. The DAC driver consumes a substantial amount
+of current. deinit() will reduce that as well. After calling deinit(), the
+DAC objects cannot be used any more and must be recreated.
+
+
Software SPI bus
----------------
diff --git a/docs/templates/topindex.html b/docs/templates/topindex.html
index e3bcd7cce14..344b971ea79 100644
--- a/docs/templates/topindex.html
+++ b/docs/templates/topindex.html
@@ -57,6 +57,10 @@ MicroPython documentation
Quick reference for the ESP32
pinout for ESP32-based boards, snippets of useful code, and a tutorial
+
+ Quick reference for the PSOC™ Edge
+ general information for PSOC™ Edge based boards and snippets of useful code
+
Quick reference for the Raspberry Pi RP2xxx
pinout for rp2xxx-based boards, snippets of useful code, and a tutorial
diff --git a/docs/zephyr/quickref.rst b/docs/zephyr/quickref.rst
index 63d4bced039..be468833960 100644
--- a/docs/zephyr/quickref.rst
+++ b/docs/zephyr/quickref.rst
@@ -29,32 +29,68 @@ Use the :mod:`time
-This is the MicroPython project, which aims to put an implementation
-of Python 3.x on microcontrollers and small embedded systems.
+This is the MicroPython project, an implementation of Python 3.x for
+microcontrollers, embedded systems and other constrained platforms.
You can find the official website at [micropython.org](http://www.micropython.org).
-WARNING: this project is in beta stage and is subject to changes of the
-code-base, including project-wide name changes and API changes.
-
MicroPython implements the entire Python 3.4 syntax (including exceptions,
`with`, `yield from`, etc., and additionally `async`/`await` keywords from
Python 3.5 and some select features from later versions). The following core
@@ -53,6 +50,44 @@ the officially supported board from the
see the [schematics and pinouts](http://github.com/micropython/pyboard) and
[documentation](https://docs.micropython.org/en/latest/pyboard/quickref.html).
+MicroPython design values
+-------------------------
+
+"Perfection is achieved, not when there is nothing more to add, but when there
+is nothing left to take away." ―- Antoine de Saint-Exupéry.
+
+For its design and implementation, MicroPython aims to follow a set of values.
+Although not a strict set of rules, these values and principles serve as a
+useful guide for new and seasoned contributors, as well as maintainers.
+
+MicroPython is at heart a combination of "Micro" and "Python": it's about
+resource constrained systems running the Python programming language. Both of
+these concepts balance off against each other in all parts of MicroPython's
+design and implementation.
+
+The key concepts that focus the development of MicroPython are:
+- Minimalism: do lots with little.
+- Efficiency: engineering, build, execution, storage, power consumption.
+- Consistency: the whole system feels like it was designed at once.
+
+When using MicroPython, the Python language is used as the human interface to a
+system, giving fine control over the entities attached to that system.
+In a hardware setting, MicroPython aims to give the user a bare-metal feeling:
+one should feel like they have complete control over the system, with very
+little between the programmer and the physical world.
+
+MicroPython recognises that systems can be very complex. The existing Python
+libraries in combination with the MicroPython-specific libraries provide a
+user-friendly way to harness the complexity of a system.
+
+Python language compatibility is very important to MicroPython, and at first
+glance MicroPython should look just like regular Python. In the first instance,
+most Python scripts should run unchanged on MicroPython, even on devices with very
+tight resources. Beyond that, there are ways to extend MicroPython if needed to
+better match Python. The provided built-in modules are an efficient subset of
+the corresponding Python ones, without duplication of functionality, and allow
+extension in Python if needed.
+
Contributing
------------
@@ -80,9 +115,8 @@ This repository contains the following components:
- [examples/](examples/) -- a few example Python scripts.
"make" is used to build the components, or "gmake" on BSD-based systems.
-You will also need bash, gcc, and Python 3.3+ available as the command `python3`
-(if your system only has Python 2.7 then invoke make with the additional option
-`PYTHON=python2`). Some ports (rp2 and esp32) additionally use CMake.
+You will also need bash, gcc, and Python 3.3+ available as the command `python3`.
+Some ports (rp2 and esp32) additionally use CMake.
Supported platforms & architectures
-----------------------------------
@@ -99,28 +133,74 @@ development and testing of MicroPython itself, as well as providing
lightweight alternative to CPython on these platforms (in particular on
embedded Linux systems).
-The ["minimal"](ports/minimal) port provides an example of a very basic
-MicroPython port and can be compiled as both a standalone Linux binary as
-well as for ARM Cortex M4. Start with this if you want to port MicroPython to
-another microcontroller. Additionally the ["bare-arm"](ports/bare-arm) port
-is an example of the absolute minimum configuration, and is used to keep
-track of the code size of the core runtime and VM.
-
-In addition, the following ports are provided in this repository:
- - [cc3200](ports/cc3200) -- Texas Instruments CC3200 (including PyCom WiPy).
- - [esp32](ports/esp32) -- Espressif ESP32 SoC (including ESP32S2, ESP32S3, ESP32C3, ESP32C6).
- - [esp8266](ports/esp8266) -- Espressif ESP8266 SoC.
- - [mimxrt](ports/mimxrt) -- NXP m.iMX RT (including Teensy 4.x).
- - [nrf](ports/nrf) -- Nordic Semiconductor nRF51 and nRF52.
- - [pic16bit](ports/pic16bit) -- Microchip PIC 16-bit.
- - [powerpc](ports/powerpc) -- IBM PowerPC (including Microwatt)
- - [qemu](ports/qemu) -- QEMU-based emulated target (for testing)
- - [renesas-ra](ports/renesas-ra) -- Renesas RA family.
- - [rp2](ports/rp2) -- Raspberry Pi RP2040 (including Pico and Pico W).
- - [samd](ports/samd) -- Microchip (formerly Atmel) SAMD21 and SAMD51.
- - [stm32](ports/stm32) -- STMicroelectronics STM32 family (including F0, F4, F7, G0, G4, H7, L0, L4, WB)
- - [webassembly](ports/webassembly) -- Emscripten port targeting browsers and NodeJS.
- - [zephyr](ports/zephyr) -- Zephyr RTOS.
+Over twenty different MicroPython ports are provided in this repository,
+split across three
+[MicroPython Support Tiers](https://docs.micropython.org/en/latest/develop/support_tiers.html).
+
+Tier 1 Ports
+============
+
+👑 Ports in [Tier 1](https://docs.micropython.org/en/latest/develop/support_tiers.html)
+are mature and have the most active development, support and testing:
+
+| Port | Target | Quick Reference |
+|--------------------------|----------------------------------------------------------------------------------------|----------------------------------------------------------------------|
+| [esp32](ports/esp32)* | Espressif ESP32 SoCs (ESP32, ESP32S2, ESP32S3, ESP32C3, ESP32C6) | [here](https://docs.micropython.org/en/latest/esp32/quickref.html) |
+| [mimxrt](ports/mimxrt) | NXP m.iMX RT | [here](https://docs.micropython.org/en/latest/mimxrt/quickref.html) |
+| [rp2](ports/rp2) | Raspberry Pi RP2040 and RP2350 | [here](https://docs.micropython.org/en/latest/rp2/quickref.html) |
+| [samd](ports/samd) | Microchip (formerly Atmel) SAMD21 and SAMD51 | [here](https://docs.micropython.org/en/latest/samd/quickref.html) |
+| [stm32](ports/stm32) | STMicroelectronics STM32 MCUs (F0, F4, F7, G0, G4, H5, H7, L0, L1, L4, N6, WB, WL) | [here](https://docs.micropython.org/en/latest/pyboard/quickref.html) |
+| [unix](ports/unix) | Linux, BSD, macOS, WSL | [here](https://docs.micropython.org/en/latest/unix/quickref.html) |
+| [windows](ports/windows) | Microsoft Windows | [here](https://docs.micropython.org/en/latest/unix/quickref.html) |
+
+An asterisk indicates that the port has ongoing financial support from the vendor.
+
+Tier 2 Ports
+============
+
+✔ Ports in [Tier 2](https://docs.micropython.org/en/latest/develop/support_tiers.html)
+are less mature and less actively developed and tested than Tier 1, but
+still fully supported:
+
+| Port | Target | Quick Reference |
+|----------------------------------|-------------------------------------------------------------|-------------------------------------------------------------------------|
+| [alif](ports/alif) | Alif Semiconductor Ensemble MCUs (E3, E7) | |
+| [embed](ports/embed) | Generates a set of .c/.h files for embedding into a project | |
+| [nrf](ports/nrf) | Nordic Semiconductor nRF51 and nRF52 | |
+| [psoc-edge](ports/psoc-edge) | Infineon PSOC™ Edge | [here](https://docs.micropython.org/en/latest/psoc-edge/quickref.html) |
+| [renesas-ra](ports/renesas-ra) | Renesas RA family | [here](https://docs.micropython.org/en/latest/renesas-ra/quickref.html) |
+| [webassembly](ports/webassembly) | Emscripten port targeting browsers and NodeJS | |
+| [zephyr](ports/zephyr) | Zephyr RTOS | [here](https://docs.micropython.org/en/latest/zephyr/quickref.html) |
+
+Tier 3 Ports
+============
+
+Ports in [Tier 3](https://docs.micropython.org/en/latest/develop/support_tiers.html)
+are built in CI but not regularly tested by the MicroPython maintainers:
+
+| Port | Target | Quick Reference |
+|----------------------------|-------------------------------------------------------------------|-------------------------------------------------------------------------|
+| [cc3200](ports/cc3200) | Texas Instruments CC3200 | [For WiPy](https://docs.micropython.org/en/latest/wipy/quickref.html) |
+| [esp8266](ports/esp8266) | Espressif ESP8266 SoC | [here](https://docs.micropython.org/en/latest/esp8266/quickref.html) |
+| [pic16bit](ports/pic16bit) | Microchip PIC 16-bit | |
+
+Additional Ports
+================
+
+In addition to the above there is a Tier M containing ports that are used
+primarily for maintenance, development and testing:
+
+- The ["bare-arm"](ports/bare-arm) port is an example of the absolute minimum
+ configuration that still includes the compiler, and is used to keep track
+ of the code size of the core runtime and VM.
+
+- The ["minimal"](ports/minimal) port provides an example of a very basic
+ MicroPython port and can be compiled as both a standalone Linux binary as
+ well as for ARM Cortex-M4. Start with this if you want to port MicroPython
+ to another microcontroller.
+
+- The [qemu](ports/qemu) port is a QEMU-based emulated target for Cortex-A,
+ Cortex-M, RISC-V 32-bit, RISC-V 64-bit, and PowerPC 64-bit architectures.
The MicroPython cross-compiler, mpy-cross
-----------------------------------------
diff --git a/docs/README.md b/docs/README.md
index 892726ba17f..9b3b036e063 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -13,8 +13,7 @@ Building the documentation locally
If you're making changes to the documentation, you may want to build the
documentation locally so that you can preview your changes.
-Install Sphinx, and optionally (for the RTD-styling), sphinx_rtd_theme,
-preferably in a virtualenv:
+Install Sphinx and sphinx_rtd_theme, preferably in a virtualenv:
pip install sphinx
pip install sphinx_rtd_theme
@@ -25,6 +24,21 @@ In `micropython/docs`, build the docs:
You'll find the index page at `micropython/docs/build/html/index.html`.
+Documentation autobuild
+-----------------------
+
+For a more convenient development experience, you can use `sphinx-autobuild`
+to automatically rebuild and serve the documentation when you make changes:
+
+ pip install sphinx-autobuild
+
+Then run from the `micropython/docs` directory:
+
+ sphinx-autobuild . build/html
+
+This will start a local web server (typically at `http://127.0.0.1:8000`)
+and automatically rebuild the documentation whenever you save changes to the source files.
+
Having readthedocs.org build the documentation
----------------------------------------------
diff --git a/docs/conf.py b/docs/conf.py
index eb614875820..f80ca97edca 100755
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -55,6 +55,7 @@
"sphinx.ext.todo",
"sphinx.ext.coverage",
"sphinxcontrib.jquery",
+ "sphinx_rtd_theme",
]
# Add any paths that contain templates here, relative to this directory.
@@ -71,7 +72,7 @@
# General information about the project.
project = "MicroPython"
-copyright = "- The MicroPython Documentation is Copyright © 2014-2025, " + micropy_authors
+copyright = "- The MicroPython Documentation is Copyright © 2014-2026, " + micropy_authors
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -128,20 +129,9 @@
# -- Options for HTML output ----------------------------------------------
-# on_rtd is whether we are on readthedocs.org
-on_rtd = os.environ.get("READTHEDOCS", None) == "True"
+import sphinx_rtd_theme
-if not on_rtd: # only import and set the theme if we're building docs locally
- try:
- import sphinx_rtd_theme
-
- html_theme = "sphinx_rtd_theme"
- html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), "."]
- except:
- html_theme = "default"
- html_theme_path = ["."]
-else:
- html_theme_path = ["."]
+html_theme = "sphinx_rtd_theme"
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
diff --git a/docs/develop/cmodules.rst b/docs/develop/cmodules.rst
index c5aa919b764..e1c6658f075 100644
--- a/docs/develop/cmodules.rst
+++ b/docs/develop/cmodules.rst
@@ -8,8 +8,8 @@ limitations with the Python environment, often due to an inability to access
certain hardware resources or Python speed limitations.
If your limitations can't be resolved with suggestions in :ref:`speed_python`,
-writing some or all of your module in C (and/or C++ if implemented for your port)
-is a viable option.
+writing some or all of your module in C (and/or
+:ref:`C++ if implemented for your port