Merge branch 'master' of https://github.com/micropython/micropython

Author: tuxlinuxien

docs/conf.py

@@ -74,7 +74,7 @@
 #
 # We don't follow "The short X.Y version" vs "The full version, including alpha/beta/rc tags"
 # breakdown, so use the same version identifier for both to avoid confusion.
-version = release = '1.11'
+version = release = '1.12'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/develop/cmodules.rst

@@ -1,3 +1,5 @@
+.. _cmodules:
+
 MicroPython external C modules
 ==============================
 
@@ -17,6 +19,10 @@ more sense to keep this external to the main MicroPython repository.
 This chapter describes how to compile such external modules into the
 MicroPython executable or firmware image.
 
+An alternative approach is to use :ref:`natmod` which allows writing custom C
+code that is placed in a .mpy file, which can be imported dynamically in to
+a running MicroPython system without the need to recompile the main firmware.
+
 
 Structure of an external C module
 ---------------------------------

docs/develop/index.rst

@@ -11,3 +11,4 @@ See the `getting started guide
 
  cmodules.rst
  qstr.rst
+ natmod.rst

docs/develop/natmod.rst

@@ -0,0 +1,202 @@
+.. _natmod:
+
+Native machine code in .mpy files
+=================================
+
+This section describes how to build and work with .mpy files that contain native
+machine code from a language other than Python. This allows you to
+write code in a language like C, compile and link it into a .mpy file, and then
+import this file like a normal Python module. This can be used for implementing
+functionality which is performance critical, or for including an existing
+library written in another language.
+
+One of the main advantages of using native .mpy files is that native machine code
+can be imported by a script dynamically, without the need to rebuild the main
+MicroPython firmware. This is in contrast to :ref:`cmodules` which also allows
+defining custom modules in C but they must be compiled into the main firmware image.
+
+The focus here is on using C to build native modules, but in principle any
+language which can be compiled to stand-alone machine code can be put into a
+.mpy file.
+
+A native .mpy module is built using the ``mpy_ld.py`` tool, which is found in the
+``tools/`` directory of the project. This tool takes a set of object files
+(.o files) and links them together to create a native .mpy files.
+
+Supported features and limitations
+----------------------------------
+
+A .mpy file can contain MicroPython bytecode and/or native machine code. If it
+contains native machine code then the .mpy file has a specific architecture
+associated with it. Current supported architectures are (these are the valid
+options for the ``ARCH`` variable, see below):
+
+* ``x86`` (32 bit)
+* ``x64`` (64 bit x86)
+* ``armv7m`` (ARM Thumb 2, eg Cortex-M3)
+* ``armv7emsp`` (ARM Thumb 2, single precision float, eg Cortex-M4F, Cortex-M7)
+* ``armv7emdp`` (ARM Thumb 2, double precision float, eg Cortex-M7)
+* ``xtensa`` (non-windowed, eg ESP8266)
+* ``xtensawin`` (windowed with window size 8, eg ESP32)
+
+When compiling and linking the native .mpy file the architecture must be chosen
+and the corresponding file can only be imported on that architecture. For more
+details about .mpy files see :ref:`mpy_files`.
+
+Native code must be compiled as position independent code (PIC) and use a global
+offset table (GOT), although the details of this varies from architecture to
+architecture. When importing .mpy files with native code the import machinery
+is able to do some basic relocation of the native code. This includes
+relocating text, rodata and BSS sections.
+
+Supported features of the linker and dynamic loader are:
+
+* executable code (text)
+* read-only data (rodata), including strings and constant data (arrays, structs, etc)
+* zeroed data (BSS)
+* pointers in text to text, rodata and BSS
+* pointers in rodata to text, rodata and BSS
+
+The known limitations are:
+
+* data sections are not supported; workaround: use BSS data and initialise the
+ data values explicitly
+
+* static BSS variables are not supported; workaround: use global BSS variables
+
+So, if your C code has writable data, make sure the data is defined globally,
+without an initialiser, and only written to within functions.
+
+Defining a native module
+------------------------
+
+A native .mpy module is defined by a set of files that are used to build the .mpy.
+The filesystem layout consists of two main parts, the source files and the Makefile:
+
+* In the simplest case only a single C source file is required, which contains all
+ the code that will be compiled into the .mpy module. This C source code must
+ include the ``py/dynruntime.h`` file to access the MicroPython dynamic API, and
+ must at least define a function called ``mpy_init``. This function will be the
+ entry point of the module, called when the module is imported.
+
+ The module can be split into multiple C source files if desired. Parts of the
+ module can also be implemented in Python. All source files should be listed in
+ the Makefile, by adding them to the ``SRC`` variable (see below). This includes
+ both C source files as well as any Python files which will be included in the
+ resulting .mpy file.
+
+* The ``Makefile`` contains the build configuration for the module and list the
+ source files used to build the .mpy module. It should define ``MPY_DIR`` as the
+ location of the MicroPython repository (to find header files, the relevant Makefile
+ fragment, and the ``mpy_ld.py`` tool), ``MOD`` as the name of the module, ``SRC``
+ as the list of source files, optionally specify the machine architecture via ``ARCH``,
+ and then include ``py/dynruntime.mk``.
+
+Minimal example
+---------------
+
+This section provides a fully working example of a simple module named ``factorial``.
+This module provides a single function ``factorial.factorial(x)`` which computes the
+factorial of the input and returns the result.
+
+Directory layout::
+
+ factorial/
+ ├── factorial.c
+ └── Makefile
+
+The file ``factorial.c`` contains:
+
+.. code-block:: c
+
+ // Include the header file to get access to the MicroPython API
+ #include "py/dynruntime.h"
+
+ // Helper function to compute factorial
+ STATIC mp_int_t factorial_helper(mp_int_t x) {
+ if (x == 0) {
+ return 1;
+ }
+ return x * factorial_helper(x - 1);
+ }
+
+ // This is the function which will be called from Python, as factorial(x)
+ STATIC mp_obj_t factorial(mp_obj_t x_obj) {
+ // Extract the integer from the MicroPython input object
+ mp_int_t x = mp_obj_get_int(x_obj);
+ // Calculate the factorial
+ mp_int_t result = factorial_helper(x);
+ // Convert the result to a MicroPython integer object and return it
+ return mp_obj_new_int(result);
+ }
+ // Define a Python reference to the function above
+ STATIC MP_DEFINE_CONST_FUN_OBJ_1(factorial_obj, factorial);
+
+ // This is the entry point and is called when the module is imported
+ mp_obj_t mpy_init(mp_obj_fun_bc_t *self, size_t n_args, size_t n_kw, mp_obj_t *args) {
+ // This must be first, it sets up the globals dict and other things
+ MP_DYNRUNTIME_INIT_ENTRY
+
+ // Make the function available in the module's namespace
+ mp_store_global(MP_QSTR_factorial, MP_OBJ_FROM_PTR(&factorial_obj));
+
+ // This must be last, it restores the globals dict
+ MP_DYNRUNTIME_INIT_EXIT
+ }
+
+The file ``Makefile`` contains:
+
+.. code-block:: make
+
+ # Location of top-level MicroPython directory
+ MPY_DIR = ../../..
+
+ # Name of module
+ MOD = features0
+
+ # Source files (.c or .py)
+ SRC = features0.c
+
+ # Architecture to build for (x86, x64, armv7m, xtensa, xtensawin)
+ ARCH = x64
+
+ # Include to get the rules for compiling and linking the module
+ include $(MPY_DIR)/py/dynruntime.mk
+
+Compiling the module
+--------------------
+
+Be sure to select the correct ``ARCH`` for the target you are going to run on.
+Then build with::
+
+ $ make
+
+Without modifying the Makefile you can specify the target architecture via::
+
+ $ make ARCH=armv7m
+
+Module usage in MicroPython
+---------------------------
+
+Once the module is built there should be a file called ``factorial.mpy``. Copy
+this so it is accessible on the filesystem of your MicroPython system and can be
+found in the import path. The module con now be accessed in Python just like any
+other module, for example::
+
+ import factorial
+ print(factorial.factorial(10))
+ # should display 3628800
+
+Further examples
+----------------
+
+See ``examples/natmod/`` for further examples which show many of the available
+features of native .mpy modules. Such features include:
+
+* using multiple C source files
+* including Python code alongside C code
+* rodata and BSS data
+* memory allocation
+* use of floating point
+* exception handling
+* including external C libraries

docs/esp32/general.rst

@@ -52,6 +52,7 @@ For your convenience, some of technical specifications are provided below:
 * I2S: 2
 * ADC: 12-bit SAR ADC up to 18 channels
 * DAC: 2 8-bit DACs
+* RMT: 8 channels allowing accurate pulse transmit/receive
 * Programming: using BootROM bootloader from UART - due to external FlashROM
  and always-available BootROM bootloader, the ESP32 is not brickable
 

docs/esp32/quickref.rst

@@ -365,6 +365,20 @@ Notes:
 
  p1 = Pin(4, Pin.OUT, None)
 
+RMT
+---
+
+The RMT is ESP32-specific and allows generation of accurate digital pulses with
+12.5ns resolution. See :ref:`esp32.RMT <esp32.RMT>` for details. Usage is::
+
+ import esp32
+ from machine import Pin
+
+ r = esp32.RMT(0, pin=Pin(18), clock_div=8)
+ r # RMT(channel=0, pin=18, source_freq=80000000, clock_div=8)
+ # The channel resolution is 100ns (1/(source_freq/clock_div)).
+ r.write_pulses((1, 20, 2, 40), start=0) # Send 0 for 100ns, 1 for 2000ns, 0 for 200ns, 1 for 4000ns
+
 OneWire driver
 --------------
 

docs/library/esp32.rst

@@ -1,3 +1,5 @@
+.. currentmodule:: esp32
+
 :mod:`esp32` --- functionality specific to the ESP32
 ====================================================
 
@@ -86,6 +88,91 @@ Constants
 
  Used in `Partition.find` to specify the partition type.
 
+
+.. _esp32.RMT:
+
+RMT
+---
+
+The RMT (Remote Control) module, specific to the ESP32, was originally designed
+to send and receive infrared remote control signals. However, due to a flexible
+design and very accurate (as low as 12.5ns) pulse generation, it can also be
+used to transmit or receive many other types of digital signals::
+
+ import esp32
+ from machine import Pin
+
+ r = esp32.RMT(0, pin=Pin(18), clock_div=8)
+ r # RMT(channel=0, pin=18, source_freq=80000000, clock_div=8)
+ # The channel resolution is 100ns (1/(source_freq/clock_div)).
+ r.write_pulses((1, 20, 2, 40), start=0) # Send 0 for 100ns, 1 for 2000ns, 0 for 200ns, 1 for 4000ns
+
+The input to the RMT module is an 80MHz clock (in the future it may be able to
+configure the input clock but, for now, it's fixed). ``clock_div`` *divides*
+the clock input which determines the resolution of the RMT channel. The
+numbers specificed in ``write_pulses`` are multiplied by the resolution to
+define the pulses.
+
+``clock_div`` is an 8-bit divider (0-255) and each pulse can be defined by
+multiplying the resolution by a 15-bit (0-32,768) number. There are eight
+channels (0-7) and each can have a different clock divider.
+
+So, in the example above, the 80MHz clock is divided by 8. Thus the
+resolution is (1/(80Mhz/8)) 100ns. Since the ``start`` level is 0 and toggles
+with each number, the bitstream is ``0101`` with durations of [100ns, 2000ns,
+100ns, 4000ns].
+
+For more details see Espressif's `ESP-IDF RMT documentation.
+<https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/peripherals/rmt.html>`_.
+
+.. Warning::
+ The current MicroPython RMT implementation lacks some features, most notably
+ receiving pulses and carrier transmit. RMT should be considered a
+ *beta feature* and the interface may change in the future.
+
+
+.. class:: RMT(channel, \*, pin=None, clock_div=8)
+
+ This class provides access to one of the eight RMT channels. *channel* is
+ required and identifies which RMT channel (0-7) will be configured. *pin*,
+ also required, configures which Pin is bound to the RMT channel. *clock_div*
+ is an 8-bit clock divider that divides the source clock (80MHz) to the RMT
+ channel allowing the resolution to be specified.
+
+.. method:: RMT.source_freq()
+
+ Returns the source clock frequency. Currently the source clock is not
+ configurable so this will always return 80MHz.
+
+.. method:: RMT.clock_div()
+
+ Return the clock divider. Note that the channel resolution is
+ ``1 / (source_freq / clock_div)``.
+
+.. method:: RMT.wait_done(timeout=0)
+
+ Returns True if `RMT.write_pulses` has completed.
+
+ If *timeout* (defined in ticks of ``source_freq / clock_div``) is specified
+ the method will wait for *timeout* or until `RMT.write_pulses` is complete,
+ returning ``False`` if the channel continues to transmit.
+
+.. Warning::
+ Avoid using ``wait_done()`` if looping is enabled.
+
+.. method:: RMT.loop(enable_loop)
+
+ Configure looping on the channel, allowing a stream of pulses to be
+ indefinitely repeated. *enable_loop* is bool, set to True to enable looping.
+
+.. method:: RMT.write_pulses(pulses, start)
+
+ Begin sending *pulses*, a list or tuple defining the stream of pulses. The
+ length of each pulse is defined by a number to be multiplied by the channel
+ resolution ``(1 / (source_freq / clock_div))``. *start* defines whether the
+ stream starts at 0 or 1.
+
+
 The Ultra-Low-Power co-processor
 --------------------------------
 

docs/reference/index.rst

@@ -21,6 +21,7 @@ implementation and the best practices to use them.
 
  glossary.rst
  repl.rst
+ mpyfiles.rst
  isr_rules.rst
  speed_python.rst
  constrained.rst