fengqi/lv_micropython
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Merge tag 'v1.20.0' into update_micropython_v1.20

Browse Source 
New mip package manager, compressed type structs and Pico W support

This release of MicroPython introduces a new lightweight package manager
called mip, which uses a custom protocol to query and install packages that
is optimised for embedded systems.  It is intended to take over the role of
upip and supports installing packages from micropython-lib as well as any
URL.  Mip can be run directly on a device (with network connectivity) or
via mpremote.  As part of this, all pure-Python drivers have been moved
from the micropython repository to the micropython-lib repository, making
it easier to install the packages needed for a given project.

In the MicroPython runtime, core/built-in types have been compressed by
only including in the C-level type struct as many slots for C function
pointers as is needed for a given type (instead of storing NULL pointers
for unused slots).  This resulted in a reduction of code size of many
kilobytes for all ports (eg around 1200 for bare-arm) with a very minimal
loss in performance.  Any third-party C extensions will need to be updated
to work with this change.  See commits
662b9761b37b054f08fe2f7c00d0fce3a418d0b0 and
3ac8b5851e5f4dade465d52b91ed2ccc17851263 for details.

The MicroPython VM/runtime has also seen many improvements and bug fixes,
including: addition of hex/fromhex methods to bytes/memoryview/bytearray,
dictionary union (PEP 584), support for __float__ and __complex__
functions, support for __dict__ on module objects and UTF-8 validation of
all strings.  Whole number floats are now formatted exactly, and there have
been other accuracy improvements to parsing and formatting of floats.
A sub-version has been introduced for .mpy files which is used only when a
.mpy file includes native code, allowing the native ABI to change while
retaining backwards compatibility with pure bytecode .mpy files.
There is now an option to have the GC heap split across more than one pool
of memory, although this is not yet in use by the ports.  And root pointer
registration has been simplified with the new MP_REGISTER_ROOT_POINTER
macro.

In the network module, the keyword arguments to scan(), connect() and
config() have been renamed to be more consistent across ports and drivers.
The changed argument names are: "essid" changed to "ssid", "auth" or
"authmode" changed to "security", and "password" changed to "key".  The old
keyword arguments are still supported so this change is backwards
compatible.  The functions network.hostname() and network.country() have
also been added and provide a standard interface across ports to set the
global networking configuration for all interfaces and interface types.  In
particular, setting the hostname is now supported for all CYW43xx-based
boards (pyboard-D, Arduino Portenta, Pico W, and others).

The mbedtls (SSL library) settings have also been unified across ports that
use this library and enable elliptic curve DH and DSA cryptography enabled
so that devices can connect to more websites.  The cert_reqs and cadata
arguments have also been implemented.  Sockets now support leaving
multicast groups.  WebREPL will now run the page from the device, allowing
WebREPL resources to load from a HTTPS site.

The bluetooth module has a minor breaking change for
IRQ_GATTC_CHARACTERISTIC_RESULT: def_handle has been replaced with
end_handle.  This is not expected to affect most programs as def_handle is
unlikely to be used.  See commit cacc96d98c2a70dc7e5194331ea70746c39746ec.

The uasyncio module now supports stream read(-1), handles gather with no
awaitables, and adds a clear() method to ThreadSafeFlag.  The framebuf
module adds ellipse and polygon drawing methods, and a fill argument to
rect() for consistency with those new methods.

A new port has been added, the "embed" port, which is a port of MicroPython
that targets the C language and outputs a set of self-contained .c and .h
files for embedding into a wider project.  An example is provided to show
how this works.

The esp8266 port has reverse-special-methods enabled on the GENERIC board,
uart.flush() and uart.txdone() added, real open drain output enabled on
pins driven by PWM, and adds the ability to set TX power for the WLAN
interface.

The esp32 port now uses synchronous BLE events which allows support for BLE
pairing and bonding.  The LAN driver adds support for LAN8710, KSZ8081,
configuration of ETH ref_clk pin, and support for SPI-based Ethernet chips.
UART now supports setting timeout_char and implements uart.flush() and
uart.txdone().  New boards include ESP32S3 with octal SPIRAM, Olimex PoE
boards and a generic board for unicore chips.  There have also been many
bug fixes, in particular for newer MCU versions such as S2, S3 and C3.

The mimxrt port has seen a lot of clean up of the code, support for
MIMXRT1176 MCUs and the MIMXRT1170_EVK board, a soft-timer implementation
of machine.Timer, addition of machine.bootloader(), as well as uart.flush()
and uart.txdone().

On the nrf port, machine.UART and machine.PWM have been improved to match
other ports (the PWM change is a breaking change), and machine.I2C now
supports the freq argument.  New boards include the Arduino Nano 33 BLE
sense board and the Seeed XIAO NRF52840 Sense.

The rp2 port sees the integration of the CYW43xx WiFi driver which is used
in the new Pico W board, a board similar to the Pico but with WiFi support.
Other new boards include W5500_EVB_PICO, WEACTSTUDIO and the nullbits Bit-C
PRO board.  Support has been added for named pins, including Pin.board and
Pin.cpu attributes, consistent with other ports that support this feature.
The machine.lightsleep() function has been implemented, along with SSL
certificate time validation, and more accurate formulas are used to
determine PWM frequency and duty.  The GC heap available to MicroPython
programs has been increased to use the maximum available free RAM, adding
about 20k to the user heap.  There have also been important bug fixes to
threading and concurrency when using both cores.

The samd port has been significantly extended to include: named pins with
a pins.csv file, and Pin.board and Pin.cpu attributes; ADC, PWM, DAC,
SoftSPI, SoftI2C, SPI, I2C and RTC classes added to the machine module;
pin.irq() method and OPEN_DRAIN mode for pins; freq, disable_irq,
enable_irq, idle, lightsleep and time_pulse_us functions added to the
machine module.  Floating point support has been added for SAMD21 devices,
and the math module enabled for SAMD51.  A board definition for Sparkfun
Think Plus has been added.

The stm32 port sees support added for STM32L1xx MCUs, STM32H723, USB on
STM32G0xx and mboot support for STM32G0xx.  The existing CYW43xx WiFi
driver has been replaced with the open-source version of cyw43-driver and
this has been integrated with all existing boards with CYW43xx chips.
Support for the CC3000 WiFi driver has been removed, and the Wiznet driver
integration has been reworked to use the generic one shared with other
ports (and also uses lib/wiznet5k instead of the old drivers/wiznet5k).
Hardware I2C implementation has been added for STM32L1xx and STM32L4xx,
support added for Arduino 1200bps touch to enter the bootloader (only on
Arduino boards), mbedtls (SSL) certificate time validation added, and
link-time-optimisation (LTO) enabled by default on boards with small flash
size.  New board definitions include: LEGO Hub No. 7, NUCLEO-L152RE,
NUCLEO-F756ZG, NUCLEO-H723ZG, Arduino Nicla Vision and Arduino Giga H7.
Arduino boards also now include a range of frozen libraries including
senml.

For the unix and windows ports, build outputs (including executables) are
now kept inside the $(BUILD) directory associated with the build.  As part
of this the variant suffix has been removed from the executable name.  For
example, what was micropython-coverage is now build-coverage/micropython,
and the standard variant is build-standard/micropython.  Furthermore, the
dev variant has been removed and its features enabled instead on the
standard variant, which now enables the same feature set as a typical
bare-metal board, making it more convenient to use for development.  The
remaining variants are: minimal, standard, nanbox, coverage.  The SSL
implementation for this port has switched from axtls to mbedtls, again to
match most bare-metal ports.

The javascript port has been renamed to the webassembly port, and adds
support for VFS and VfsPosix using Emscripten's POSIX filesystem layer.
The way stdout printing works has also changed to dispatch via a custom
event called "micropython-print".

The zephyr port upgraded Zephyr to v3.1.0, added custom configuration for
bbc_microbit_v2, and enabled finalisers.

The change in code size since the previous release for various ports is
(absolute and percentage change in the text section):

       bare-arm:   -1124  -1.934%
    minimal x86:   -4322  -2.967%
       unix x64: +264181 +50.533% standard
          stm32:   -3592  -0.906% PYBV10
         cc3200:   -1832  -0.990%
        esp8266:   -2284  -0.327% GENERIC
          esp32:   +9659  +0.632% GENERIC
            nrf:     -84  -0.045% pca10040
            rp2:  +13096  +4.291% PICO
           samd: +127776 +90.488% ADAFRUIT_ITSYBITSY_M4_EXPRESS

The changes that dominate these numbers are:
- bare-arm, minimal, stm32, cc3200, esp8266: reduced size due to compressed
  type structs
- unix: switching axtls for mbedtls, merging in dev configuration options
  and features
- esp32: new Ethernet drivers and some additional machine module
  functionality
- nrf: compressed type struct and machine module improvements
- rp2: additional mbedtls features and ciphers
- samd: many new features, and machine module classes and functions

Thanks to everyone who contributed to this release:
Alex Riesen, Andrew Leech, Andrew Scheller, Angus Gratton, Antonello
Margottini, Antonin ENFRUN, Ayke van Laethem, Blake Felt, brave ulysses,
Brian Cooke, Brian Pugh, Carlosgg, Chris Overgaauw, Chris Swan, Chris
Waggoner, chrismas9, Christian Clauss, Christian Walther, Clayton Cronk,
cpottle9, Dale Weber, Damiano Mazzella, Damien George, Damien Tournoud, Dan
Ellis, Daniel Jour, David (Pololu), David Grayson, David Lechner, David
Peake, David Yang, Dorukyum, Efi Weiss, enriquezgarc, Felix Dörre, Florian
Weimer, glenn20, hoihu, Howard Lovatt, iabdalkader, Ian Davies,
IcedRooibos, Ihor Nehrutsa, Jacob Siverskog, Jan Hrudka, Jan Willeke, Jared
Hancock, Jatty_, Jay Greco, Jeff Epler, Jeremy Rand, Jim Mussared, Jonas
Scharpf, Jos Verlinde, Juan Francisco Cantero Hurtado, Koen De
Vleeschauwer, Kyuchumimo, Lars Haulin, Laurens Valk, LiaoJingyi_winY7kp,
Luiz Brandao, ma-lalonde, manobendro, Maripo GODA, Mark Grosen, Martin
Milata, Mat Booth, Matt Trentini, Maureen Helm, Michael Bentley, Michael
Mogenson, MrJake222, Nathan Hendler, Ned Konz, Nicholas H.Tollervey, Oliver
Joos, omogenot, Patrick, Patrick Joy, Paul Grayson, Paul Warren, Pepijn de
Vos, Peter Harper, Peter Hinch, PGE, Phil Howard, Philip Peitsch, Philipp
Ebensberger, pmendham, Rayane Chatrieux, Red_M, Rob Knegjens, robert-hh,
Sebastian Romero, Simon Arlott, Sky, Stewart C. Russell, Stig Bjørlykke,
stijn, Stuart Langridge, Takeo Takahashi, Thorsten von Eicken, Tim Gates,
Tobias Thyrrestrup, Tomasz 'CeDeROM' CEDRO, Tomofumi Inoue, TPReal,
Trammell hudson, Wind-stormger, yn386, Yonatan Goldschmidt, 小权一句两句.

The work done in this release was funded in part through GitHub Sponsors,
by George Robotics, and by Planet Innovation.

What follows is a detailed list of changes, generated from the git commit
history, and organised into sections.

Main components
===============

all:
- fix paths to mpy-cross and micropython binaries
- remove MICROPY_PY_IO_FILEIO config option
- update all manifest.py files to use new features
- simplify buffer protocol to just a "get buffer" callback
- standardise mp_obj_type_t initialisation
- make all mp_obj_type_t defs use MP_DEFINE_CONST_OBJ_TYPE
- fix #if inside MP_DEFINE_CONST_OBJ_TYPE for msvc
- remove unnecessary locals_dict cast
- use += rather than = everywhere for CFLAGS/LDFLAGS/LIBS
- keep msvc build output in build/ directories
- fix Python comparison to None and True, and use "not in"
- use micropython-lib unconditionally in manifests
- replace upip with mip everywhere
- update Python formatting to black "2023 stable style"
- update copyright year range to include 2023

py core:
- vm: change comparison for finally handler search from > to >=
- emit: remove logic to detect last-emit-was-return-value
- emit: suppress unreachable bytecode/native code that follows jump
- objcell: make cell get/set funcs static-inline to reduce code size
- parsenum: support parsing complex numbers of the form "a+bj"
- parsenum: fix parsing of complex "j" and also "nanj", "infj"
- parsenum: optimise when building with complex disabled
- objclosure: forward function attributes for closures
- objfun: support function attributes on native functions
- builtin: remove unnecessary module declarations
- builtinhelp: don't show help for an MP_MODULE_ATTR_DELEGATION_ENTRY
- mkrules.cmake: improve printing of git-submodules error
- scheduler: de-inline and fix race with pending exception / scheduler
- vm: document internal SELECTIVE_EXC_IP option
- emitnative: fix STORE_ATTR viper code-gen when value is not a pyobj
- vm: remove check for ip being NULL when handling StopIteration
- vm: in YIELD_FROM opcode, expand helper macros and remove them
- vm: consistently indent #if guards to match the code they surround
- objnamedtuple: fix segfault with empty namedtuple
- misc: add MP_STATIC_ASSERT_NOT_MSC()
- obj: add static safety checks to mp_obj_is_type()
- obj: add debug-only runtime checks to mp_obj_is_type()
- make_root_pointers: add MP_REGISTER_ROOT_POINTER parser/generator
- mpstate: drop MICROPY_PORT_ROOT_POINTERS from mp_state_vm_t
- persistentcode: use MP_REGISTER_ROOT_POINTER()
- modsys: use MP_REGISTER_ROOT_POINTER()
- scheduler: use MP_REGISTER_ROOT_POINTER()
- misc: fix msvc compilation with compressed error messages
- qstr: make mp_decompress_rom_string decl and def the same
- gc: allow the GC heap to be split over multiple memory areas
- gc: reduce code size when MICROPY_GC_SPLIT_HEAP is disabled
- obj: add support for __float__ and __complex__ functions
- obj: make mp_obj_get_complex_maybe call mp_obj_get_float_maybe first
- compile: support large integers in inline-asm data directive
- modio: remove FileIO and TextIOWrapper from io module
- formatfloat: format all whole-number floats exactly
- builtinimport: remove duplicate static function argument
- mkenv.mk: use micropython-lib from submodule by default
- runtime: fix crash in star arg unpacking
- mpprint: fix formatting typo with mp_print_ext_t struct name
- objstr: reformat str access macros to make them readable
- mkrules.mk: keep all build artefacts inside $(BUILD) directory
- dynruntime.mk: allow building assembly source in natmods
- nlrpowerpc: fix generation of ppc64 code on ppc32 build
- qstr: change qstr hash type from mp_uint_t to size_t
- objstr: consolidate methods for str/bytes/bytearray/array
- objstr: add hex/fromhex to bytes/memoryview/bytearray
- objstr: remove str function object declarations from header file
- mkrules: use abspath to find directory for mpy-cross dependency
- parsenum: ensure that trailing zeros lead to identical results
- formatfloat: use pow(10, e) instead of pos/neg_pow lookup tables
- dynruntime: add mp_obj_is_true
- clean up formatting of union definitions
- builtinimport: allow overriding of mp_builtin___import__
- objstr: split mp_obj_str_from_vstr into bytes/str versions
- objstr: always ensure mp_obj_str_from_vstr is unicode-safe
- objstr: optimise mp_obj_new_str_from_vstr for known-safe strings
- objstr: always validate utf-8 for mp_obj_new_str
- persistentcode: clarify ValueError when native emitter disabled
- objpolyiter: add a new polyiter type with finaliser support
- mpconfig: add LFS1/LFS2 options to match FAT/posix
- mpconfig: make feature levels available to mpconfigport.h
- mpconfig: add "everything" features from unix coverage
- objpolyiter: fix comment about finaliser method
- mkrules.mk: add link to build troubleshooting on failure
- obj: add macro to declare ROM mp_obj_type_t instances
- objexcept: make MP_DEFINE_EXCEPTION use MP_DEFINE_CONST_OBJ_TYPE
- obj: add "full" and "empty" non-variable-length mp_obj_type_t
- obj: add accessors for type slots and use everywhere
- obj: add slot-index mp_obj_type_t representation
- obj: remove basic mp_obj_type_t sparse representation
- objtype: optimise slot RAM usage for instance types
- objnamedtuple: optimise slot RAM usage for namedtuple
- obj: merge getiter and iternext mp_obj_type_t slots
- obj: convert make_new into a mp_obj_type_t slot
- obj: optimise code size and performance for make_new as a slot
- persistentcode: introduce .mpy sub-version
- objmodule: add support for __dict__
- runtime: add mp_raise_OSError_with_filename helper function
- include filename in errors from loading/saving files via "open"
- parse: allow const types other than int to optimise as true/false
- objstr: don't treat bytes as unicode in str.count
- mkenv.mk: make CPP definition explicit for consistency
- objstr: add a helper to set mp_obj_str_t data
- modsys: add support for sys.executable
- py.mk: make user-C-module handling self-contained in py.mk
- misc: remove use of bitfield from vstr_t
- obj: verify floating point type is correct for repr C
- persistentcode: only emit sub-version if generated code has native
- obj: add comments explaining the slot index scheme
- makeversionhdr: fall back to py/mpconfig.h instead of docs/conf.py
- builtinimport: fix crash handling "weak link" module names
- objarray: detect bytearray(str) without an encoding
- emitnative: ensure load_subscr does not clobber existing REG_ARG_2
- nlrmips: add native NLR support for MIPS architecture
- makeversionhdr.py: allow running outside of repo
- objdict: implement dictionary union (PEP 584)
- bc: fix checking for duplicate **kwargs
- modmicropython: make module optional
- mpconfig: include micropython module in core features
- remove the word "yet" from exception messages
- pass in address to compiled module instead of returning it
- gc: avoid valgrind false positives
- gc: ensure a gap of one byte after the ATB
- gc: fix debug printing of GC layout
- obj: remove unused MP_DEFINE_CONST_OBJ_FULL_TYPE macro
- emitnative: initialise locals as Python object type for native code
- map: clear value when re-using slot with ordered dictionaries
- gc: increase the address length in gc_dump_alloc_table()
- objarray: raise error on out-of-bound memoryview slice start
- lexer: wrap in parenthesis all f-string arguments passed to format
- add parenthesis to default impl of MP_OBJ_TO_PTR, MP_OBJ_FROM_PTR
- objint_mpz: catch and reject @ and @= operating on big integers
- mkrules: support mpy-tool-flags in cmake frozen code generation
- mkrules.cmake: force build mpversion.h and frozen_content.c
- modmath: fix two-argument math function domain check
- emitnative: explicitly compare comparison ops in binary_op emitter
- makeversionhdr.py: optionally get git tag and git hash from env vars
- compile: fix scope of assignment expression target in comprehensions
- gc: make gc_dump_info/gc_dump_alloc_table take a printer as argument
- mpconfig: provide config option for internal printf printer
- builtinimport: fix unix port build with external imports disabled
- makeversionhdr.py: always add micro to version string even if it's 0
- obj: add MP_NOINLINE to mp_obj_malloc_helper
- mpstate: add mp_thread_is_main_thread() helper macro
- scheduler: implement VM abort flag and mp_sched_vm_abort()
- obj: fix spelling of staticmethod
- makeqstrdefs.py: fix handling GreenHills C/C++ preprocessor output

extmod:
- network_cyw43: rename WLAN keyword args to ssid/security/key
- network_ninaw10: rename WLAN connect argument from essid to ssid
- modlwip: clean up inclusion of modlwip in build process
- extmod.cmake: only include modbtree in build if it's enabled
- extmod.mk: separate out extmod file list from py.mk to extmod.mk
- modbtree: use buffer protocol for keys/values
- uasyncio: attempt to write immediately in Stream.write method
- uasyncio: implement stream read(-1) to read all data up to EOF
- vfs: prevent uninitialized variable warning for path_out
- network_cyw43: support new cyw43-driver
- modnetwork: include cyw43-driver header if it's enabled
- network_cyw43: add "security" config option to get/set auth mode
- btstack: use MP_REGISTER_ROOT_POINTER()
- nimble: use MP_REGISTER_ROOT_POINTER()
- modnetwork: use MP_REGISTER_ROOT_POINTER()
- uos_dupterm: use MP_REGISTER_ROOT_POINTER()
- modlwip: use MP_REGISTER_ROOT_POINTER()
- vfs: use MP_REGISTER_ROOT_POINTER()
- modbluetooth: use MP_REGISTER_ROOT_POINTER()
- always use custom mbedtls error message code
- modussl_mbedtls: implement cert_reqs and cadata arguments
- btstack: fix descriptor discovery handle range and events
- network_ninaw10: move ninaw10 root pointer registrations here
- modbluetooth: add support for running sync irq on system thread
- webrepl: allow the page to run from the device (over HTTP)
- uasyncio: handle gather with no awaitables
- ntptime: factor out ntptime module from esp8266 port
- modussl_mbedtls: set a more sensible default debug log level
- network_cyw43: add hostname config option
- network_wiznet5k: register NIC when the lwIP stack is used
- network_wiznet5k: drop obsolete argument count check
- network_wiznet5k: deinit the NIC before (re-)initialisation
- network_wiznet5k: schedule clearing of interrupt flags
- network_wiznet5k: rearrange the function wiznet5k_poll()
- network_wiznet5k: extract SPI transfer function dynamically
- uasyncio: add clear method to ThreadSafeFlag
- uasyncio: rename internal _flag to state, to save a qstr
- modlwip: add support for leaving multicast groups
- vfs_posix_file: remove unused MICROPY_VFS_POSIX_FILE
- modframebuf: optimise argument handling
- modframebuf: add fill argument to rect()
- modframebuf: add ellipse drawing method
- modframebuf: add polygon drawing methods
- modframebuf: improve poly-fill boundary pixels
- network_wiznet5k: use the configured DNS address if available
- machine_i2c: call MICROPY_PY_EVENT_HOOK during i2c.scan()
- modure: convert byte offsets to unicode indices when necessary
- modbluetooth: fix descriptor registration with empty tuple
- modbluetooth: replace def_handle with end_handle in char IRQ
- vfs: add finaliser to ilistdir to close directory handle
- vfs_posix_file: implement finaliser for files
- modbluetooth: change data_len type from size_t to uint16_t
- modbluetooth: do GATTC reassembly in protected uPy context
- modbluetooth: run BLE IRQ callback in protected NLR context
- extmod.mk: make extmod.mk handle GIT_SUBMODULES
- make extmod.mk self-contained
- utime_mphal: make ticks_add check for overflow of delta
- btstack: update BTstack bindings to work with latest BTstack
- mbedtls: add common configuration file, and use it in all ports
- mbedtls: enable MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE
- mbedtls: enable elliptic curve DH and DSA cryptography
- mbedtls: remove MBEDTLS_ECP_DP_CURVE25519_ENABLED config
- mbedtls: remove brainpool curves from config
- machine_timer: move stm32's implementation of machine.Timer here
- vfs_posix: include errno.h and unistd.h headers
- extmod.cmake: allow overriding the default MBEDTLS_CONFIG_FILE
- modlwip: use actual errno in exception for error in listen
- extmod.mk: set default mbedtls config file in extmod Makefile
- btstack: allow the BTstack config to be overridden by a board
- add and reorganise compilation guards and includes
- extmod.cmake: add MICROPY_PY_BTREE compiler definition
- moduplatform: remove _M_IX86 test for xtensa
- moduplatform: fix MSVC x86_64 check
- modframebuf: fix crash in FrameBuffer scrolling beyond extents
- uasyncio: fix syntax of generator functions
- modnetwork: use a type protocol to implement NIC functions
- modussl_mbedtls: fix support for ioctl(MP_STREAM_POLL)
- network_cyw43: fix handling of networks with open security
- axtls-include: add back needed header files for building axTLS
- utime_mphal: fix comment re delta range check in time_ticks_add
- modbtree: move system includes within MICROPY_PY_BTREE guard
- modnetwork: add network.hostname() and network.country()
- modnetwork: allow more extensive port-specific customisation
- network_cyw43: use CYW43_CHANNEL_NONE for default arg in connect
- vfs_posix: do not filter '..*' in ilistdir when filtering '..'
- network_ninaw10: check socket types when creating new sockets
- network_cyw43: fix setting hostname using config() method
- network_cyw43: add support to get STA RSSI using status() method
- network_ninaw10: add missing raw socket type to socket()
- btstack: switch to use hci_dump_init instead of hci_dump_open
- modbluetooth: merge gatts_notify/indicate implementation
- btstack: fix indicate/notify queuing
- btstack: include value handle in client read/write events
- btstack: fix MTU handling
- btstack: add support for CCCD to allow client subscriptions
- nimble: fix flags for descriptor registration
- modbluetooth: make all HCI transports trace in the same format
- btstack/modbluetooth_btstack: add default services

shared:
- runtime/tinyusb_helpers: add TinyUSB helper functions
- netutils/dhcpserver: match default DNS to server IP
- readline: use MP_REGISTER_ROOT_POINTER()
- runtime/pyexec: use MP_REGISTER_ROOT_POINTER()
- runtime/softtimer: move softtimer.[ch] to shared/runtime
- runtime/softtimer: remove obsolete #include statement
- runtime/sys_stdio_mphal: make func static and remove some TODOs
- runtime/gchelper_native: fix pointer cast on x86_64
- netutils: add "py/obj.h" header include
- tinyusb: create common TinyUSB code for reuse by ports
- tinyusb: further refactor static USB device implementation
- tinyusb: fix CDC bNumInterfaces value
- runtime: use mp_printf consistently, instead of printf
- runtime/gchelper: drop cpu directive from ARM asm helpers
- runtime/softtimer: use consistently the same clock source
- runtime/softtimer: fix ticks range when computing ticks diff
- tinyusb: allow max USB descriptor string to be configured
- runtime/pyexec: don't allow Ctrl+C to interrupt frozen boot code
- tinyusb: revert setting of CFG_TUD_CDC_EP_BUFSIZE to 256

drivers:
- hts221: add HTS221 humidity sensor driver
- lsm9ds1: add LSM9DS1 IMU driver
- lps22h: add LPS22HB/HH pressure sensor driver
- lps22h: use machine.idle for power saving
- ninaw10/nina_wifi_bsp: use MP_REGISTER_ROOT_POINTER()
- fix a few typos in comments
- cyw43: allow configuring the netif/mDNS hostname
- sdcard: add delay in init_card_v1 to make timeout work
- wiznet5k: remove old Wiznet driver
- cc3000: remove CC3000 WiFi driver files
- display: don't include tests by default
- remove drivers that are now in micropython-lib
- ninaw10: connect to WiFi asynchronously
- bus: detect QSPI transfer errors and pass up to spiflash driver
- bus: change QSPI read_cmd signature to return an error code
- ninaw10: implement machine.Pin external pin controls
- cyw43: use board-defined BLE UART secondary baudrate
- cyw43: use a different baudrate for BT firmware download
- ninaw10: fix machine_pin GPIO read
- cyw43: include CYW43 config file
- ninaw10: add missing external pins 34 and 39
- ninaw10: fix ESP32 input-only pins

mpy-cross:
- Makefile: respect existing CFLAGS and LDFLAGS
- remove .gitignore file
- include alloca.h for NetBSD
- mpy_cross: add Python wrapper for mpy-cross
- mpy_cross: fix default path to mpy-cross binary
- mpy_cross: add a way to query the mpy version
- mpy_cross: add list of architectures to `__all__`
- mpy_cross: add docstrings to public methods
- main: don't set a default native architecture
- main: add MSVC-compatible architecture checks
- force forward slashes in paths
- main: fix return type of mp_import_stat

lib:
- cyw43-driver: add new submodule for CYW43xx WiFi driver
- pico-sdk: update to version 1.4.0
- cyw43-driver: update cyw43-driver to fix ap_auth mode setting
- tinyusb: update to the most recent master
- cyw43-driver: update driver to latest version
- micropython-lib: add micropython-lib as a submodule
- lwip: update lwIP to v2.1.3, tag STABLE-2_1_3_RELEASE
- micropython-lib: update to latest version with manifest changes
- micropython-lib: update submodule to latest
- stm32lib: update library to get L1 v1.10.3, and some other fixes
- micropython-lib: update submodule to latest
- btstack: update to v1.5.3
- micropython-lib: update submodule to latest
- libm: use __asm__ instead of asm
- btstack: update to v1.5.4
- cyw43-driver: update driver to latest version
- re1.5: reduce code size when checking for named class char
- re1.5: add support for named classes in class sets
- micropython-lib: update submodule to latest
- cyw43-driver: update driver to latest version
- pico-sdk: update to version 1.5.0
- cyw43-driver: update driver to latest version v0.9.0
- micropython-lib: update submodule to latest
- stm32lib: update library to get H7 v1.11.0
- cyw43-driver: update driver to latest version v1.0.0
- micropython-lib: update submodule to latest

Support components
==================

docs:
- update to use new WLAN argument names for ssid/security/key
- library/pyb.Timer: document `brk` argument and its constants
- library: remove unnecessary "pyb." prefix on class names
- set LaTeX engine to XeLaTeX for PDF generation
- library/machine: add note on interrupts being critical to system
- library/uasyncio: consistently use "uasyncio" instead of "asyncio"
- library/bluetooth: add link to aioble
- library/neopixel: add note that neopixel is included in rp2 builds
- library/time: provide more info about which epoch is used
- library/pyb.Pin: fix out-of-context paragraphs, and AF_PP typo
- library/pyb.Pin: add Pin.ALT constant
- library/pyb.Timer: document how to use BKIN pin with example
- update links for Arm GCC toolchain
- library/rp2: fix pull_thresh docs to use pull instead of push
- esp32: fix string quoting consistency in SDCard mount example
- update CPython differences and improve the look of table layouts
- esp32: update UART quickref on input-only pins
- library/machine.UART: add notes about UART init and deinit
- library: fix nested rst styles not rendering
- library/micropython: fix spelling of compiler
- templates/topindex.html: update forum link
- library/machine.I2C: add a note about I2C pull-up resistors
- library/machine.UART: add docs for uart.flush() and uart.txdone()
- renesas-ra: add pin drive keyword argument description
- Makefile: enable parallel compilation for Sphinx
- templates/layout.html: indicate latest vs release docs
- samd: add documentation for the samd port
- library/machine: add machine.memX to docs with brief example
- samd/pinout: fix the pin numbering for the default assignments
- develop: fix mp_compile snippet to match latest code
- renesas-ra: correct the internal file system size of EK-RA6M2
- library/array: add docs for dunder methods
- library/pyb.CAN: update the recv example to take a 5-tuple
- library/uasyncio: describe restriction on ThreadSafeFlag
- library/framebuf: clarify docs for blit regarding palette
- library/struct: fix buffer argument description
- library/struct: embed format tables
- library/neopixel: update GitHub URL for neopixel.py link
- differences: update Python 3.9 status
- differences: add Python 3.10 page
- rp2: make LED have exactly 50% duty cycle in PIO 1Hz example
- library/rp2.StateMachine: expand put() documentation
- library/socket: use correct sockaddr variable name
- esp32/quickref: add docs for the LAN interface constructor
- library/machine.Timer: add freq argument to machine.Timer
- reference/constrained: add missing heap-dump symbols to mem_info()
- zephyr/quickref: fix zsensor module usage examples
- library/network: update docs for network.country, network.hostname
- update copyright year range to include 2023

examples:
- embedding: remove obsolete axtls build target
- usercmodule: add example of a native C class
- embedding: rework example to use ports/embed
- rp2: add comment that examples using IO25 don't work on Pico W
- bluetooth: fix check for _conn_handle being None
- usercmodule/cexample: use mp_obj_malloc()
- bluetooth/ble_temperature_central.py: remove service tuple

tests:
- extmod: add heap-lock test for stream writing
- basics: add tests for __name__ and __globals__ attrs on closures
- perf_bench: add some configurations for N=32, M=10
- add an explanation of run-perfbench.py
- fix run-perfbench parsing "no matching params" case
- micropython: add test for builtin execfile() function
- extmod/ussl_basic: make test run on axtls and mbedtls
- cpydiff: fix formatting of code snippet to use double quotes
- run-tests.py: provide better default MPYCROSS value for Windows
- extmod/ubinascii: add tests for bytes.hex etc
- update path to unix micropython executable
- unicode: add test for invalid utf-8 file contents
- renesas-ra: update pin test to support all boards
- extmod/uasyncio_heaplock.py: force SKIP on stackless
- frozen: move frozentest.mpy from ports/ to tests/
- run-multitests: extend usage information
- run-multitests: make paths more deterministic
- allow 'special' tests to output "SKIP" on a single line
- extmod: add test for sleep_ms value that overflows ticks
- run-perfbench: support --heapsize argument and pass to executable
- basics: add exp file for builtin_str_hex test
- run-tests.py: use host arch for mpy-cross for target=unix
- misc: add test for cexample module
- misc/cexample_module: test class presence
- misc/cexample_class: fix timing sensitivity
- extmod/framebuf_scroll: add tests for FrameBuffer scrolling
- unix/mod_os: add test for os module
- extmod/ure_namedclass: add tests for named classes in class sets
- float: skip new complex tests if complex unavailable
- extmod: get DecompIO test running on low-memory targets
- extmod: skip vfs tests if target doesn't have enough memory
- micropython: split viper_misc test into two files
- float: add domain checks for log and also -inf
- float: make output of math function tests more readable
- run-multitests.py: add ability to test instance over reboot
- multi_bluetooth: add bluetooth multi-test for deepsleep
- run-multitests.py: support outputting test metrics
- multi_bluetooth: use multitest.output_metric in BLE perf tests
- extmod/vfs_fat_ilistdir_del.py: use 512-byte erase block size
- multi_bluetooth: use time.sleep_ms instead of time.sleep
- multi_bluetooth/ble_mtu: split peripheral/central-initiated
- multi_bluetooth/ble_subscribe: use end_handle in desc discovery
- multi_bluetooth: add test for descriptors
- multi_bluetooth/ble_characteristic.py: add write-no-response
- multi_bluetooth: use multitest.broadcast instead of sleep

tools:
- metrics.py: add mimxrt and renesas-ra to list of available ports
- ci.sh: drop ppa requirement for code formatting CI
- pyboard.py: add verbose option to filesystem_command
- mpremote: don't be verbose when using cat command
- autobuild: add nrf port to autobuild scripts
- ci.sh: initialise submodules for more ports
- ci.sh: force mpy-cross build for samd and teensy
- update path to unix micropython executable
- mpremote: allow + terminator for fs commands
- pyboard.py: add "touch" filesystem command
- mpremote: add "edit" command
- ci.sh: split the stm32 builds for wiznet5k and cc3k
- mpremote: print a nicer error when a filesystem command fails
- pyboard.py: remove implicit fs_put if source starts with ./
- pyboard.py: add fs_cp function for direct device-to-device copy
- mpremote: print nicer errors for unsupported 'cp -r' arguments
- manifestfile.py: add library for working with manifests
- makemanifest.py: update to use mpy_cross module
- manifestfile.py: allow include of directory path
- manifestfile.py: allow require() to specify unix packages
- manifestfile.py: allow manifests to set metadata
- autobuild: use distinct directory for building stm32 variants
- makemanifest.py: force the repo version of the mpy_cross package
- pyboard.py: support Windows pathname separators
- manifestfile.py: add `author` kwarg to metadata()
- manifestfile.py: replace recursive glob with os.walk
- mpremote: simplify dispatch of commands
- mpremote: use argparse for command line parsing
- mpremote: add `mpremote mip install` to install packages
- pyboard.py: handle unsupported fs command
- add note about uncrustify versions
- add pre-commit support
- mpremote: fix argument handling for follow and add help strings
- mpremote: bump version to 0.4.0
- verifygitlog.py: ignore comment lines in commit messages
- verifygitlog.py: add additional help for subject line issues
- mpremote: handle FileNotFound exceptions in listdir
- mpremote: make RemoteFile objects iterable
- makemanifest.py: fix printing of mpy_cross.CrossCompileError
- gen-cpydiff.py: use os.path.join and os.path.isdir
- gendoc.py: remove unused script
- ci.sh: add ARDUINO_NANO_RP2040_CONNECT to rp2 CI build
- ci.sh: remove one build from zephyr CI to speed it up
- ci.sh: don't print python2 version
- mpremote: allow EDITOR environment variable to work on Windows
- mpremote: only auto connect to serial device with USB VID/PID
- autobuild: create .uf2 file for seeed_xiao_nrf52
- pyboard.py: fix Python 2 compatibility
- pyboard.py: add parse kwarg to eval
- pyboard.py: add fs_{listdir,readfile,writefile,stat}
- pyboard.py: set DTR on Windows to avoid ESPxx hard reset
- mpy-tool.py: initialize line_info_top
- ci.sh: install pkg-config for macos builds
- ci.sh: add unix, stm32 and rp2 ports to code size check
- mpremote: use hatch to build mpremote package
- pyboard.py: use '/' exclusively when dealing with paths
- pyboard.py: fix joining of path in filesystem_command
- pyboard.py: fix ESPxx boards hanging in bootloader after reset
- manifestfile.py: add support for publishing packages to PyPI
- mpremote: add ctrl-x as additonal mpremote disconnect shortcut

CI:
- ISSUE_TEMPLATE: make minor improvements to placeholder text
- ISSUE_TEMPLATE: replace forum with Discussions
- workflows: print test failures for webassembly workflow
- workflows: bump actions/checkout to v3
- add dependabot to update GitHub Actions
- workflows: bump codecov/codecov-action from 1 to 3
- workflows: bump actions/setup-python from 1 or 2 to 4
- workflows: run unix port workflow if mpy-cross changes
- workflows: use ubuntu-20.04 when python2 is required
- workflows: run mpy-format CI when tests and examples change
- workflows: comment on code size change instead of failing CI
- workflows: fix code size comment workflow for non-PR
- workflows: cancel when branch is updated
- workflows: update existing comments for code_size_comment
- workflows/code_size: print code size change
- workflows: add "shared/**" to list of paths that trigger CI
- workflows: add workflow to build mpremote wheel
- workflows: bump actions/setup-python from 1 to 4
- workflows: bump actions/checkout from 2 to 3
- workflows: bump actions/upload-artifact from 2 to 3

The ports
=========

all ports:
- adapt mimxrt, nrf and rp2 ports to work with latest TinyUSB
- fix a few typos in comments
- remove unused mp_type_{fileio/textio} macros in mpconfigport.h
- always include debug information in the ELF
- always append to GIT_SUBMODULES
- use micropython-lib version of drivers in manifests
- make generated pin.c handling more consistent across ports
- make all network-capable boards use bundle-networking
- make BOARD default from BOARD_DIR in Makefile's
- rename remaining "Micro Python" to "MicroPython"
- fix MCU tags in Arduino board.json files
- implement simple write polling for stdout

bare-arm port: no changes specific to this component/port

cc3200 port:
- mpconfigport: remove mp_const_user_interrupt
- use MP_REGISTER_ROOT_POINTER()
- fix various array-based compiler warnings
- mods/pybuart: implement uart.flush() and uart.txdone()
- remove unused NIC type customisation

embed port:
- add new "embed" port which builds a simple C package
- fix arguments to mp_raw_code_load_mem

esp8266 port:
- modnetwork: rename WLAN keyword args to ssid/security/key
- mpconfigport: switch to ROM feature level configuration
- mpconfigport: disable MICROPY_PY_UTIMEQ
- rename WLAN dhcp_hostname config to hostname
- boards: enable reverse-special-methods on GENERIC board
- use MP_REGISTER_ROOT_POINTER()
- modnetwork: add support for WLAN.config(protocol=XX) option
- README: update build instructions to match ci.sh
- machine_uart: implement uart.flush() and uart.txdone()
- modmachine: move dht_readinto() to the machine module
- machine_pwm: enable real open drain output on pin driven by PWM
- machine_pin: disable open drain when pin becomes input/output
- modnetwork: add ability to set tx power for WLAN interface
- README: remove notice about port being "experimental"
- use extmod/modnetwork.c instead of port-specific version

esp32 port:
- network_wlan: rename WLAN keyword args to ssid/security/key
- machine_uart: implement the functionality of timeout_char arg
- boards: increase 512 bytes limit on ULP programs to 2040
- modesp32: add wake_on_ulp() so ULP can wake CPU from deepsleep
- network_wlan: don't raise exception when scan returns no results
- rename WLAN dhcp_hostname config to hostname
- modmachine: fix machine.freq to allow maximum 160MHz on ESP32-C3
- use MP_REGISTER_ROOT_POINTER()
- mpconfigport: enable BLE synchronous events and pairing/bonding
- Makefile: force micropython-lib as a required submodule
- network_wlan: use esp_wifi_set/get_channel to config wifi channel
- network_wlan: add support to set/get the wifi protocol
- modnetwork: add network.MODE_LR constant
- machine_uart: change sendbreak time to be at least 15 bit times
- machine_timer: support all init arguments in Timer constructor
- boards: merge manifest_release modules into standard manifest
- machine_sdcard: free SPI bus when deiniting SD card
- machine_uart: implement uart.flush() and uart.txdone()
- mphalport: fix calculation of large sleep by using 64-bit arith
- Makefile: add link to build troubleshooting on failure
- modsocket: use mp_obj_is_integer to test port type
- machine_pwm: don't use LEDC_USE_REF_TICK on ESP32-C3 variants
- machine_i2s: add I2S finaliser which calls deinit()
- machine_hw_spi: use auto DMA channel on S2, S3, C3 chips
- rename machine I2C and SPI types consistently across ports
- machine_i2c: fix clocks and timeouts for ESP32-C3, ESP32-S3
- machine_pin: fix size of machine_pin_irq_handler array
- machine_pwm: verify PWM is active when config methods are called
- add 32MiB partition table templates
- usb: add a timeout to usb_tx_strn()
- modmachine: move dht_readinto() to the machine module
- boards/GENERIC_S3_SPIRAM: enable BLE support
- boards/GENERIC_S3_SPIRAM: enable BLE
- machine_timer: fix ESP32C3 timer period doubling
- machine_touchpad: fix TouchPad for ESP32S2, ESP32S3
- main: don't call usocket_events_deinit if unavailable
- usb: cleanup connection detection
- boards/GENERIC_S3_SPIRAM_OCT: add ESP32S3 board with Octal SPIRAM
- network_lan: add support for LAN8710 PHY
- network_lan: support configuration of ETH ref_clk pin
- network_lan: add support for SPI-based ethernet chips
- network_lan: fix setting MAC address of ethernet devices
- network_lan: fix compilation on IDF lower than v4.4
- machine_sdcard: change dma_channel to SPI_DMA_CH_AUTO for ESP32S3
- boards: add board definition for Olimex ESP32 PoE boards
- boards/GENERIC_UNICORE: add board definition for unicore chips
- network_lan: add support for Ethernet PHY KSZ8081
- add a small delay before leaving wlan.active()
- boards/OLIMEX_ESP32_POE: remove id from and update board.json
- Makefile: allow specifying BOARD_DIR on make command line
- use extmod/modnetwork.c instead of port-specific version
- machine_pin: use const for size of machine_pin_irq_handler array
- esp32_rmt: fix looping behaviour for RMT on ESP32-S3

mimxrt port:
- Makefile: refactor Makefile and divide it into sections
- Makefile: modify handling of SDRAM option
- Makefile: modify handling of SDCARD option
- Makefile: rework board flash type handling
- Makefile: rework floating point config
- Makefile: fix some minor formatting inconsistencies
- boards: remove conditional assignment of flash type/size
- use MP_REGISTER_ROOT_POINTER()
- machine_uart: implement uart.flush() and uart.txdone()
- machine_uart: drop a few commented lines about TX ring buffer
- format the firmware image to match the new teensy loader
- machine_spi: allow a setting of -1 for cs in the constructor
- machine_uart: set the UART ioctl write poll flag properly
- machine_uart: fix a bug in UART.write()
- Makefile: split up SRC_C variables
- machine_pin: add the Pin.toggle() method
- fix CPU freeze when calling __WFE() in MICROPY_EVENT_POLL_HOOK
- machine_timer: use soft-timer implementation for machine.Timer
- machine_timer: use extmod version of machine.Timer
- mphalport: add a timeout to mp_hal_stdout_tx_strn()
- modmachine: move dht_readinto() to the machine module
- add support for MIMXRT1176 MCUs, and MIMXRT1170_EVK board
- README: add build and flashing instructions
- usb: change macro name MICROPY_HW_USB_STR_MANUF
- network: rename the argument clock_mode to ref_clk_mode
- Makefile: set MPY_CROSS_FLAGS
- mpconfigport: remove config options that are set by default
- machine_rtc: set the microsecond value to 0
- sdcard: fix an error when writing large blocks
- sdcard: remove obsolete code already excluded by preprocessor
- set MICROPY_GC_STACK_ENTRY_TYPE to uint32_t for large RAM
- Makefile: move the FROZEN_MANIFEST setting after board config
- enable ROM text compression
- pendsv: add MICROPY_BOARD_PENDSV_ENTRIES for board customisation
- pendsv: clean up PendSV code
- Makefile: fix internal flash configuration and build
- boards/MIMXRT1064_EVK: fix board config to use internal flash
- mpconfigport: allow configuring different network interfaces
- modmachine: implement machine.bootloader()
- fix the build for boards without ROM API

minimal port:
- Makefile: avoid terminal reset, use BUILD variable
- Makefile: set linker to $(CC)
- increase heap size for Linux builds

nrf port:
- main: add startup and early-init board hook macros
- modmachine: add machine.bootloader() and make it customisable
- enable optional support for Arduino 1200bps touch
- Makefile: drop unused MPY_CROSS and MPY_TOOL variables
- boards/arduino_nano_33_ble: add Arduino Nano 33 BLE sense board
- modmachine: add machine.idle() function
- mpconfigport: remove obsolete module declarations
- drivers/bluetooth: handle PHY_UPDATE messages, used in Bluetooth 5
- drivers/usb: probe for interrupt char in USB CDC task
- drivers/usb: add a tud_cdc_rx_cb() callback to check interrupt char
- mpconfigport: call tud_task() in MICROPY_EVENT_POLL_HOOK
- drivers/usb: fix reading of a single USB CDC character
- use MP_REGISTER_ROOT_POINTER()
- boards/arduino_nano_33_ble_sense: update deploy instructions
- main: call usb_cdc_init() before executing boot.py and main.py
- modules/ubluepy: use mp_obj_str_get_data to extract str data
- don't enable debug info by default if LTO is on
- modules/machine/uart: implement uart.flush() and uart.txdone()
- Makefile: split up SRC_C variables
- rename machine I2C, PWM, SPI, UART types consistently across ports
- rename MICROPY_PY_MACHINE_TIMER to MICROPY_PY_MACHINE_TIMER_NRF
- boards/seeed_xiao_nrf52: add defn for Seeed XIAO NRF52840 Sense
- mpconfigport: enable seeding of the PRNG by the hardware RNG
- Makefile: add support for BOSSAC flasher
- boards/arduino_nano_33_ble_sense: add support for REV-2 chipset
- modules/machine/pwm: add paramter checks and error messages
- modules/machine/pwm: use extmod/machine_pwm.c for PWM module
- modules/machine/soft_pwm: add PWM for nrf51x boards using soft PWM
- modules/machine/pwm: support using all 4 channels of a PWM module
- modules/machine/uart: add timeout keyword options and "any" method
- nrfx_config: use the UARTE definitions and drivers for the NRF52xx
- modules/machine: use a dedicated function for machine.idle()
- modules/machine: support the freq=n argument for machine.I2C
- modules/machine/pwm: fix resource conflict, and change id to device
- nrfx_config: use UARTE for nrf52xxx devices
- modules/machine/uart: prevent UART lock-up after a receive error

pic16bit port:
- pic16bit_mphal: use MP_REGISTER_ROOT_POINTER()

powerpc port: no changes specific to this component/port

qemu-arm port: no changes specific to this component/port

renesas-ra port:
- modmachine: allow boards to provide custom bootloader code
- machine_i2c: remove unnecessary start/stop dummy functions
- mpconfigport: drop pyb_hid_report_desc root pointer
- use MP_REGISTER_ROOT_POINTER()
- softtimer: switch to use softtimer code from shared/runtime
- machine_pin: support drive keyword and fix GPIO setting
- rename machine SPI type consistently across ports
- machine_timer: use extmod version of machine.Timer
- boards: update linker script to detect code flash overflow
- disable debugging option for RA4 to reduce code size
- change file system size to 64KB for RA6M1
- add the UART methods uart.txdone() and uart.flush()

rp2 port:
- modmachine: allow boards to provide custom bootloader code
- boards/ARDUINO_NANO_RP2040_CONNECT: enable Arduino 1200bps touch
- modmachine: implement lightsleep() with optional sleep period
- mpthreadport: ensure core1 doesn't hold gc lock in deinit
- mbedtls: enable some more mbedtls options
- lwip_inc: enable lwIP status callback
- rp2_flash: add asserts for size of flash filesystem partition
- mpnetworkport: convert network task scheduling to use PendSV IRQ
- integrate CYW43xx WiFi driver
- boards/PICO_W: add new Pico W board, an RP2040 with WiFi
- boards/GARATRONIC_PYBSTICK26_RP2040: change pico-sdk board name
- main: set default AP auth mode to WPA2_AES_PSK
- mpconfigport: factor core event handling to EVENT_POLL_HOOK_FAST
- Makefile: regenerate cmake if generated Makefile missing
- CMakeLists: give error if required submodules are missing
- CMakeLists: don't override cyw43-driver unless necessary
- boards/ARDUINO_NANO_RP2040_CONNECT: add urequests module
- run USB stack task exclusively from core 0
- make atomic sections suspend the other core (if active)
- mpconfigport: make networking options consistent across boards
- mphalport: fix missing storage_read_blocks symbol in debug build
- CMakeLists: use armv6m mpy-cross arch for rp2
- use MP_REGISTER_ROOT_POINTER()
- mpbthciport: remove mp_bthci_uart from set of root pointers
- cyw43_configport: set CYW43_EVENT_POLL_HOOK value
- cyw43_configport: set CYW43_WIFI_NVRAM_INCLUDE_FILE value
- rp2_pio: fix StateMachine.restart when PIO program is shared
- cyw43_configport: add event hook into cyw43_delay_ms
- Makefile: always use cmake to discover submodules
- mbedtls: enable certificate validity time validation
- machine_spi: add mp_hal_get_spi_obj helper function
- boards/W5500_EVB_PICO: add new board definition for W5500_EVB_PICO
- mark gc_heap NOLOAD for faster boot
- correctly determine path to arm-none-eabi-size
- machine_wdt: check for the maximum timeout value of watchdog
- machine_uart: implement uart.flush() and uart.txdone()
- mbedtls: fix missing time.h include
- rp2_flash: add start/len support to rp2.Flash() constructor
- boards: set PICO_BOARD correctly for each board
- machine_spi: use pico-sdk's default pins for SPI
- machine_i2c: use pico-sdk's default pins for I2C
- boards: remove all I2C,SPI pin defs that already match pico-sdk
- Makefile: add link to build troubleshooting on failure
- Makefile: add support for BOARD_VARIANTS
- boards/WEACTSTUDIO: add WEACTSTUDIO with multiple variants
- fatfs_port: fix the modification date of files
- rename machine I2C type consistently across ports
- mphalport: add a timeout to mp_hal_stdout_tx_strn()
- cyw43_configport: make sure only core0 executes a __WFI()
- modmachine: move dht_readinto() to the machine module
- allow enabling USB device without enabling USB-CDC
- boards/ARDUINO_NANO_RP2040: add more modules and enable MD5 hash
- fix lightsleep to work with interrupts and cyw43 driver
- machine_pwm: use more accurate formulas for freq and duty_u16
- machine_pwm: fix overflows with freq > 268 MHz
- mphalport: change order of pin operations to prevent glitches
- rp2_flash: call MICROPY_EVENT_POLL_HOOK_FAST after reading flash
- machine_pin: refactor the machine.Pin class for external GPIO
- machine_pin: add support for named pins and alternate functions
- boards: add pin CSV files to board definitions
- fix crash in a pin.irq handler
- main: use mp_printf in nlr_jump_fail
- machine_pin: fix configuring OPEN_DRAIN with initial value
- boards/NULLBITS_BIT_C_PRO: add Bit-C PRO board
- rp2_pio: track use of PIO resources and free them on soft reset
- boards/ARDUINO_NANO_RP2040_CONNECT: use default aioble
- mpconfigport: enable os.dupterm and hashlib.sha1 on all boards
- cyw43_configport: specify the chipset firmware include file
- Makefile: allow specifying BOARD_DIR on make command line
- pendsv: add MICROPY_BOARD_PENDSV_ENTRIES for board customisation
- boards/ARDUINO_NANO_RP2040_CONNECT: include "time" in manifest
- boards/ARDUINO_NANO_RP2040_CONNECT: add more external pins
- boards/ARDUINO_NANO_RP2040_CONNECT: include "senml" in manifest
- modrp2: support reading the BOOTSEL button on the Pico board
- modrp2: disable other core, shorten delay to 8us in bootsel_button
- allocate GC heap from unused RAM
- allow disabling USB via MICROPY_HW_ENABLE_USBDEV config
- main: keep UART REPL with DEBUG=1 and MICROPY_HW_ENABLE_UART_REPL=1
- machine_uart: fix setting of UART LCR parameters
- machine_i2c: add timeout parameter for machine.I2C()
- memmap_mp.ld: allow a board to reserve memory for the C heap

samd port:
- mpconfigport: enable MICROPY_ENABLE_FINALISER when VFS is used
- remove the existing provisional support for REPL on UART
- boards: replace pins.c and pins.h by pins.csv
- boards: move mcu-specific settings into a mpconfig_samdXX.h file
- Makefile: alphabetically sort the source code files in Makefile
- boards: add ADAFRUIT_FEATHER_M4_EXPRESS and _ITSYBITSY_M0_EXPRESS
- clock_config: set up the clock configuration
- modmachine: allow changing the CPU freq with machine.freq(f)
- mphalport: add pin open-drain funcs, and improve delay and ticks
- samd_isr: extend systick_ms to 64 bit
- machine_pin: add OPEN_DRAIN mode for pins
- machine_pin: allow specifying a pin or LED by its name as a string
- modmachine: enable SoftSPI and SoftI2C
- boards: create pin_af_table.c from pin_af_table_SAMDxx.csv files
- pin_af: add the pin af table and its helper functions
- machine_adc: add the machine.ADC class
- machine_pwm: add the machine.PWM class
- samd_isr: rework the interrupt tables
- machine_pin: add pin.irq() to the machine.Pin class
- modmachine: add disable_irq(), enable_irq() and idle() to machine
- machine_uart: add the machine.UART class
- machine_spi: add the machine.SPI class
- machine_i2c: add the machine.I2C class
- moduos: add uos.dupterm()
- moduos: add uos.urandom() for SAMD51
- main: use the common execution mode of boot.py and main.py
- mpconfigport: enable a few more MicroPython features
- samd_isr: change the way a Sercom ISR is registered and called
- machine_timer: add machine.Timer based on the shared soft-timer
- machine_wdt: add the machine.WDT class
- modsamd: add pininfo() function to the samd module
- machine_led: optimise size of the machine.LED class
- machine_dac: add the machine.DAC class
- modmachine: add machine.time_pulse_us
- mcu: factor out MCU policy for SAMD21 and SAMD51
- mphalport: add a mp_hal_ticks_ms_64() function
- modutime: enable time.time() based on systick_ms()
- machine_uart: support buffered TX for UART
- boards: add missing/lost board config and pin definitions
- mphalport: use CYCCNT for SAMD51's mp_hal_ticks_cpu()
- machine_bitstream: add the machine.bitstream() function
- mpconfigport: restructure to use ROM feature levels
- clock_config: split clock_config.c to separate SAMD21/SAMD51 files
- clock_config: add HW_DFLL_USB_SYNC and HW_MCU_OSC32KULP extensions
- pin_af: simplify the pin-af-table handling
- samd_flash: remove obsolete printf's and return values instead
- Makefile: fix a dependency problem with "make -j"
- mphalport: fix USB endpoint handling ignoring Ctrl-C
- change the symbol names for the peripheral clocks
- mcu: add floating point suport for SAMD21 devices
- mcu: enable the math module on SAMD51
- boards: move the flash filesystem definitions to the linker files
- boards: use the same linker file for all SAMD51x19 variants
- main: initialize readline on start up
- mcu: use lf2s for SAMD51 and lfs1 for SAMD21
- machine_pin: change the printing of Pin and LED objects
- Makefile: split up SRC_C variables
- rename machine I2C type consistently across ports
- clock_config: extend the range of machine.freq()
- clock_config: support changing machine.freq() for SAMD21
- modmachine: add machine.reset_cause()
- boards/SPARKFUN_SAMD51_THING_PLUS: add board files for Thing Plus
- modmachine: add machine.dht_readinto and enable on SAMD51
- mcu/samd51: enable onewire support for SAMD51
- mcu/samd51: enable FAT support for SAMD51
- modmachine: implement machine.lightsleep()
- modmachine: get the bootloader magic address from the lib
- clock_config: document the #defines use in init_clocks()
- machine_uart: implement uart.txdone() and uart.flush()
- mcu: make some settings in mpconfigmcu.h conditional
- machine_rtc: add the machine.RTC class
- clock_config: extend the SAMD51 us-counter to 60 bit
- boards/SEEED_WIO_TERMINAL: declare more pins for SEEED WIO board
- machine_pin: change the pin handling and naming/numbering
- make ADC, DAC, PWM, SPI objects consistent in how they print out
- modmachine: replace the LED class by the Signal class
- boards: rework the pins.csv files
- machine_pwm: serialize fast update of PWM settings
- machine_uart: use a finaliser to tidy up UART on soft reset
- machine_spi: implement spi.deinit() and simplify sercom_deinit_all
- machine_spi: register SerCom objects as root pointers
- modmachine: add machine.softreset()
- machine_timer: use extmod version of machine.Timer
- mcu/samd51: use an additional manifest.py for SAMD51 boards
- README: update README to reflect recent changes to the port
- boards/SEEED_WIO_TERMINAL: enable using the 32kHz crystal
- mphalport: add a timeout to mp_hal_stdout_tx_strn()
- move MCU-specific CFLAGS to mpconfigmcu.mk
- Makefile: set MPY_CROSS_FLAGS
- mpconfigport: support MICROPY_HW_SOFTSPI_MIN_DELAY
- mpconfigport: use __WFE() in MICROPY_EVENT_POLL_HOOK
- avoid under-/overflow in I2C and SPI baudrate calculations
- machine_uart: fix IRQ flag setting and clearing
- machine_uart: simplify machine_uart_any() and machine_uart_read()
- machine_uart: check the UART TX pin assignment
- machine_uart: fix uart.deinit() and save some RAM
- add a vref=num option to the ADC and DAC constructor
- support entering bootloader via USB CDC 1200bps touch
- boards/SEEED_XIAO: rename to SEEED_XIAO_SAMD21
- add Pin.board and Pin.cpu classes to Pin
- boards: clean up comments and some pins in pins.csv files
- mcu: rework the comments in clock_config.c
- mcu: use the FDPLL96M clock for the SAMD21 CPU
- mcu: implement a hardware seed for the SAMD21 random module
- mcu: set the SAMD21 us-counter to 2 MHz for better resolution
- moduos: add uos.urandom() using the phase-jitter rng
- pendsv: add MICROPY_BOARD_PENDSV_ENTRIES for board customisation
- always provide the machine.RTC class

stm32 port:
- modmachine: allow boards to provide custom bootloader code
- modmachine: factor out mboot enter code to a function
- boards/stm32f091xc.ld: allocate space for a small filesystem
- boards/NUCLEO_F091RC: enable LFS1 filesystem
- Makefile: set CSUPEROPT to -Os for F0 and G0 MCUs to save space
- usbd_cdc_interface: add support for Arduino 1200bps touch
- usb: expose USB HID device instance via usbd_hid_get()
- use a separate symbol name for the bootloader state pointer
- Makefile: enable link-time-optimisation via LTO=1 make option
- boards: enable LTO by default on boards with smaller flash size
- Makefile: fix setting of define that enables WIZNET5K driver
- mboot: remove redundant code in mboot_state_change function
- boardctrl: allow boards to override fatal-error handler
- sdram: include boardctrl.h for fatal-error handler
- use MP_REGISTER_ROOT_POINTER()
- Makefile: workaround LTO linker order bug in binutils <2.35
- softtimer: switch to use softtimer code from shared/runtime
- boards/LEGO_HUB_NO6: fix typo in README
- boards/LEGO_HUB_NO6: use named pins
- boards/LEGO_HUB_NO6/appupdate: detect filesystem size at runtime
- boards/LEGO_HUB_NO6/spiflash: pick command type at runtime
- boards/LEGO_HUB_NO6/cc2564: make timer configurable
- boards/LEGO_HUB_NO7: add LEGO Hub No. 7 board definition
- boards/NUCLEO_WB55: add error handling to firmware update scripts
- don't enable debug info by default if LTO is on
- switch Wiznet to use lib/wiznet5k and extmod/network_wiznet5k
- add definitions required for lwIP version of Wiznet NIC
- mphalport: add mp_hal_get_spi_obj() helper function
- sdram: enable MPU for unaligned access on H7 MCUs
- boards: increase mboot region to 32k for WB55 boards
- move board variant config to mpconfigboard.mk
- boardctrl: use HAL_Delay instead of mp_hal_delay_ms
- remove support for CC3000 WiFi driver
- machine_uart: implement uart.flush() and uart.txdone()
- boards/LEGO_HUB_NO6: update manifest to new format
- boards: only freeze LCD160CR driver in PYB board firmware
- adc: make ADCAll.read_channel reject invalid channels
- pyb_i2c: fix pyb.I2C to work with dma=True on F4 MCUs
- timer: fix use of timer channel callback() method on L4 MCUs
- boards: add alternate function list for STM32F446RE
- boards/PYB: fix handling of BOARD_VARIANT selection
- make-stmconst.py: support TypeDef's with a single char prefix
- add support for STM32L1 MCUs
- boards/NUCLEO_L152RE: add NUCLEO-L152RE board support
- rename machine I2C and SPI types consistently across ports
- boards/ARDUINO_PORTENTA_H7: revert to single-precision float
- mbedtls: enable mbedtls certificate time validation
- Makefile: allow overriding the default MBEDTLS_CONFIG_FILE
- boards/ARDUINO_PORTENTA_H7: add custom mbedtls config
- modmachine: move dht_readinto() to the machine module
- spi: downgrade SPIHandle definitions to static
- boards/ARDUINO_PORTENTA_H7: add more modules, I2C1 and SE pin
- usbd_desc: support USB strings on CDC interface descriptors
- Makefile: set MPY_CROSS_FLAGS based on MCU type
- pyb_i2c: fix failing pyb.I2C(dma=True) after receiving 1 byte
- i2c: fix I2C frequency calc so it doesn't exceed requested rate
- adc: fix reading internal ADC channels on L4 MCUs
- adc: fix ADCAll.read_core_temp() on L4 MCUs
- i2c: add hardware I2C implementation for STM32L1
- i2c: add hardware I2C implementation for STM32L4
- mboot: make all mboot sectors erase/write protected
- boards: add missing LPUART macros for H7 HAL
- boards/NUCLEO_F429ZI: enable I2C1 and I2C2 with default pins
- powerctrl: improve standby mode entry code for H7 MCUs
- boards/NUCLEO_F756ZG: add board definition for NUCLEO-F756ZG
- powerctrl: fix build on STM32G0xx and STM32H7Bx MCUs
- boards: consolidate linker snippets to reduce duplication
- Makefile: leave DFU mode after download when using dfu-util
- boards/NUCLEO_H743ZI2: refer to NUCLEO_H743ZI for frozen manifest
- boards/STM32F769DISC: fix building with USE_QSPI_XIP=1
- boards/ARDUINO_PORTENTA_H7: fix macro value check for QSPI
- boards/ARDUINO_PORTENTA_H7: use default aioble
- Makefile: clean up nested if-else to chained if-else-if
- update to use the open-source lib version of cyw43-driver
- boards: update linker scripts now that big_const is gone
- add a default implementation of pyb.country
- cyw43_configport: fix build for boards without an RF switch
- boards/PYBD_SF2: set CYW43 Bluetooth fimrware download baudrate
- cyw43_configport: allow boards to override default resource files
- boards/ARDUINO_PORTENTA_H7: update board config files
- Makefile: include HAL HSEM driver on H747 MCUs
- boards/ARDUINO_NICLA_VISION: add support for Arduino Nicla Vision
- boards/ARDUINO_GIGA: add support for Arduino Giga H7 board
- cyw43_configport: add cyw43_sdio_enable_high_speed_4bit function
- powerctrl: add sleep RCC semaphore management for WB55 MCUs
- powerctrl: disable WB55 BLE before entering deepsleep
- powerctrlboot: provide custom SystemInit for WB55
- powerctrl: don't compile WB helpers on WL MCUs
- boards: include "senml" in manifest for ARDUINO boards
- remove commented-out printf's and debugging code
- main: use mp_printf instead of printf for MPY start-up messages
- i2c: return error code and raise exception if I2C init fails
- spi: return error code and raise exception if SPI init fails
- modmachine: make machine.info print using mp_printf
- extint: make ExtInt.regs print using mp_printf
- pin: make pin_find debug output use mp_printf
- pybthread: make pyb_thread_dump take a printer as its argument
- boards/NUCLEO_H743ZI2: fix MCU tag in board.json file
- mphalport: update HAL version to 1.11.0 to match stm32lib
- add support for STM32H723 MCUs
- boards: add ld and af.csv for H723
- boards/NUCLEO_H723ZG: add new H723 board
- add support for USB on G0 MCUs
- mboot: add support for G0 MCUs
- boards/NUCLEO_G0B1RE: add config for USB and mboot
- boards/ARDUINO_NICLA_VISION: fix incorrect bootloader PID
- flash: fix get_bank function for STM32H750
- cyw43_configport: provide cyw43_hal_pin_config_irq_falling func

teensy port:
- mpconfigport: drop unused root pointers
- teensy_hal: use MP_REGISTER_ROOT_POINTER()

unix port:
- variants: move setting of MICROPY_PY_USELECT to port config file
- variants: enable remaining options on dev,coverage from ROM extra
- variants/coverage: change config to use ROM level everything
- variants/dev: allow all config options to be overridden
- moduos: include errno.h
- main: restore tty settings on nlr_jump_fail()
- alloc: use MP_REGISTER_ROOT_POINTER() for mmap_region_head
- mpconfigport: make MICROPY_EVENT_POLL_HOOK call usleep directly
- mbedtls: add custom config for mbedtls
- mpconfigport: switch ussl from axtls to mbedtls
- Makefile: only include axtls in GIT_SUBMODULES list when enabled
- Makefile: only checkout libffi submodule when used
- mpconfigport: allow overriding MICROPY_EVENT_POLL_HOOK
- enable MICROPY_GC_SPLIT_HEAP on coverage build
- unix_mphal: allow overriding hal time functions
- variants: remove variant suffix from executable filename
- modjni: add missing const qualifier
- remove .gitignore file
- modusocket: support proto and flags arguments to getaddrinfo
- include alloca.h for NetBSD
- mpconfigport: enable MICROPY_ENABLE_FINALISER when VFS is used
- variants: remove freedos and fast variants
- refactor mpconfigport.h and mpconfigvariant.h
- refactor mpconfigvariant.mk
- variants/coverage: add test for manifest freeze_mpy()
- enable sys.executable
- Makefile: don't use _MOD variable names
- modffi: move header includes inside MICROPY_PY_FFI guard
- variants: change mip package to mip-cmdline
- coverage: add extra GC coverage test for ATB gap byte
- moduos: implement 2-arg version of os.getenv()
- Makefile: disable building the shared library of libffi
- main: free pathbuf when there's an error opening a file

webassembly port:
- Makefile: remove obsolete disable of array-bounds warning
- rename this port from 'javascript' to 'webassembly'
- mpconfigport: use MICROPY_CONFIG_ROM_LEVEL_EXTRA_FEATURES
- add support for VFS and enable VFS_POSIX
- use Date's now() instead of getTime()
- change "stack" argument to "heapsize"
- support piping in a program on stdin
- dispatch micropython-print via document not mp_js_stdout
- README: update README to describe new stdout behaviour
- Makefile: change compiler optimisation from O3 to Os
- library: make use of CustomEvent detail property
- library: extract and send data to print as UInt8Array

windows port:
- provide a definition for MP_ALWAYSINLINE
- msvc: support compressed ROM text for error messages
- Makefile: update test dependency on $(PROG)
- make project file read-only for IDE
- .gitignore: simplify by removing build artefacts
- msvc: remove variant suffix from executable filename
- msvc: make mpy-cross independent of micropython variant
- msvc: fix qstr generation dependency
- msvc: fix module freezing

zephyr port:
- update include paths to use the zephyr namespace
- upgrade to Zephyr v3.1.0
- use MP_REGISTER_ROOT_POINTER()
- machine_uart: use mp_obj_str_get_str to get device name
- boards: add config for bbc_microbit_v2
- mpconfigport: enable MICROPY_ENABLE_FINALISER when VFS is used
- rename machine I2C and SPI types consistently across ports
This commit is contained in:
Amir Gonnen 2023-06-02 11:53:07 +03:00
commit 5af201dc35
1583 changed files with 43537 additions and 40827 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.git-blame-ignore-revs
View File

@ -1,4 +1,7 @@
#all: Reformat remaining C code that doesn't have a space after a comma.
# top: Update Python formatting to black "2023 stable style".
8b2748269244304854b3462cb8902952b4dcb892
# all: Reformat remaining C code that doesn't have a space after a comma.
5b700b0af90591d6b1a2c087bb8de6b7f1bfdd2d
# ports: Reformat more C and Python source code.

6
.github/ISSUE_TEMPLATE/bug_report.md vendored
View File

@ -7,9 +7,7 @@ assignees: ''
---
* Remove all placeholder text below before submitting.
* Please search existing issues before raising a new issue. For questions about MicroPython or for help using MicroPython, please see the MicroPython Forum -- https://forum.micropython.org/
* Please search existing issues before raising a new issue. For questions about MicroPython or for help using MicroPython, or any sort of "how do I?" requests, please use the Discussions tab or raise a documentation request instead.
* In your issue, please include a clear and concise description of what the bug is, the expected output, and how to replicate it.
@ -23,3 +21,5 @@ assignees: ''
- firmware file name
- git commit hash and port/board
- version information shown in the REPL (hit Ctrl-B to see the startup message)
* Remove all placeholder text above before submitting.

4
.github/ISSUE_TEMPLATE/config.yml vendored
View File

@ -1,7 +1,7 @@
blank_issues_enabled: false
contact_links:
- name: MicroPython Forum
url: https://forum.micropython.org/
- name: MicroPython GitHub Discussions
url: https://github.com/orgs/micropython/discussions
about: Community discussion about all things MicroPython. This is the best place to start if you have questions about using MicroPython or getting started with MicroPython development.
- name: MicroPython Documentation
url: https://docs.micropython.org/

6
.github/ISSUE_TEMPLATE/documentation.md vendored
View File

@ -7,10 +7,10 @@ assignees: ''
---
* Remove all placeholder text below before submitting.
* Please search existing issues before raising a new issue. For questions about MicroPython or for help using MicroPython, please see the MicroPython Forum -- https://forum.micropython.org/
* Please search existing issues before raising a new issue. For questions about MicroPython or for help using MicroPython, or any sort of "how do I?" requests, please use the Discussions tab instead.
* Describe what was missing from the documentation and/or what was incorrect/incomplete.
* If possible, please link to the relevant page on https://docs.micropython.org/
* Remove all placeholder text above before submitting.

6
.github/ISSUE_TEMPLATE/feature_request.md vendored
View File

@ -7,9 +7,7 @@ assignees: ''
---
* Remove all placeholder text below before submitting.
* Please search existing issues before raising a new issue. For questions about MicroPython or for help using MicroPython, please see the MicroPython Forum -- https://forum.micropython.org/
* Please search existing issues before raising a new issue. For questions about MicroPython or for help using MicroPython, or any sort of "how do I?" requests, please use the Discussions tab or raise a documentation request instead.
* Describe the feature you'd like to see added to MicroPython. In particular, what does this feature enable and why is it useful. MicroPython aims to strike a balance between functionality and code size, so please consider whether this feature can be optionally enabled and whether it can be provided in other ways (e.g. pure-Python library).
@ -22,3 +20,5 @@ assignees: ''
* For drivers (e.g. for external hardware), please link to datasheets and/or existing drivers from other sources.
* Who do you expect will implement the feature you are requesting? Would you be willing to sponsor this work?
* Remove all placeholder text above before submitting.

4
.github/ISSUE_TEMPLATE/security.md vendored
View File

@ -7,10 +7,10 @@ assignees: ''
---
* Remove all placeholder text before submitting the new issue.
* If you need to raise this issue privately with the MicroPython team, please email contact@micropython.org instead.
* Include a clear and concise description of what the security issue is.
* What does this issue allow an attacker to do?
* Remove all placeholder text above before submitting.

7
.github/dependabot.yml vendored Normal file
View File

@ -0,0 +1,7 @@
version: 2
updates:
# Maintain dependencies for GitHub Actions
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "daily"

105
.github/workflows/code_size_comment.yml vendored Normal file
View File

@ -0,0 +1,105 @@
name: Code size comment
on:
workflow_run:
workflows: [Check code size]
types: [completed]
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
comment:
runs-on: ubuntu-20.04
steps:
- name: 'Download artifact'
id: download-artifact
uses: actions/github-script@v6
with:
result-encoding: string
script: |
const fs = require('fs');
const allArtifacts = await github.rest.actions.listWorkflowRunArtifacts({
owner: context.repo.owner,
repo: context.repo.repo,
run_id: context.payload.workflow_run.id,
});
const matchArtifact = allArtifacts.data.artifacts.filter((artifact) => {
return artifact.name == "code-size-report"
});
if (matchArtifact.length === 0) {
console.log('no matching artifact found');
console.log('result: "skip"');
return 'skip';
}
const download = await github.rest.actions.downloadArtifact({
owner: context.repo.owner,
repo: context.repo.repo,
artifact_id: matchArtifact[0].id,
archive_format: 'zip',
});
fs.writeFileSync(`${process.env.GITHUB_WORKSPACE}/code-size-report.zip`, Buffer.from(download.data));
console.log('artifact downloaded to `code-size-report.zip`');
console.log('result: "ok"');
return 'ok';
- name: 'Unzip artifact'
if: steps.download-artifact.outputs.result == 'ok'
run: unzip code-size-report.zip
- name: Post comment to pull request
if: steps.download-artifact.outputs.result == 'ok'
uses: actions/github-script@v6
with:
github-token: ${{secrets.GITHUB_TOKEN}}
script: |
const fs = require('fs');
const prNumber = Number(fs.readFileSync('pr_number'));
const codeSizeReport = `Code size report:
\`\`\`
${fs.readFileSync('diff')}
\`\`\`
`;
const comments = await github.paginate(
github.rest.issues.listComments,
{
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: prNumber,
}
);
comments.reverse();
const previousComment = comments.find(comment =>
comment.user.login === 'github-actions[bot]'
)
// if github-actions[bot] already made a comment, update it,
// otherwise create a new comment.
if (previousComment) {
await github.rest.issues.updateComment({
owner: context.repo.owner,
repo: context.repo.repo,
comment_id: previousComment.id,
body: codeSizeReport,
});
} else {
await github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: prNumber,
body: codeSizeReport,
});
}

9
.github/workflows/ports_esp32.yml vendored
View File

@ -8,15 +8,20 @@ on:
- 'tools/**'
- 'py/**'
- 'extmod/**'
- 'shared/**'
- 'lib/**'
- 'drivers/**'
- 'ports/esp32/**'
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
jobs:
build_idf402:
runs-on: ubuntu-20.04
steps:
- uses: actions/checkout@v2
- uses: actions/checkout@v3
- name: Initialize lv_bindings submodule
run: git submodule update --init --recursive lib/lv_bindings
- name: Install packages
@ -27,7 +32,7 @@ jobs:
build_idf44:
runs-on: ubuntu-20.04
steps:
- uses: actions/checkout@v2
- uses: actions/checkout@v3
- name: Initialize lv_bindings submodule
run: git submodule update --init --recursive lib/lv_bindings
- name: Install packages

20
.gitignore vendored
View File

@ -39,31 +39,31 @@ Session.vim
tags
TAGS
# Build directories
######################
# This .gitignore file is intended to be minimal.
#
# If you find that you need additional rules, such as IDE temporary
# files, please do so either via a global .gitignore file (registered
# with core.excludesFile), or by adding private repository-specific
# rules to .git/info/exclude. See https://git-scm.com/docs/gitignore
# for more information.
# Build directories
build/
build-*/
docs/genrst/
# Test failure outputs
######################
tests/results/*
# Python cache files
######################
__pycache__/
*.pyc
# Customized Makefile/project overrides
######################
GNUmakefile
user.props
ports/javascript/node_modules
.vscode/
# Generated rst files
######################
genrst/
# MacOS desktop metadata files
######################
.DS_Store

8
.gitmodules vendored
View File

@ -13,7 +13,7 @@
[submodule "lib/stm32lib"]
path = lib/stm32lib
url = https://github.com/micropython/stm32lib
branch = work-F0-1.9.0+F4-1.16.0+F7-1.7.0+G4-1.3.0+H7-1.6.0+L0-1.11.2+L4-1.17.0+WB-1.10.0+WL-1.1.0
branch = work-F0-1.9.0+F4-1.16.0+F7-1.7.0+G0-1.5.1+G4-1.3.0+H7-1.6.0+L0-1.11.2+L1-1.10.3+L4-1.17.0+WB-1.10.0+WL-1.1.0
[submodule "lib/nrfx"]
path = lib/nrfx
url = https://github.com/NordicSemiconductor/nrfx.git
@ -53,3 +53,9 @@
url = https://github.com/andrewleech/wiznet_ioLibrary_Driver.git
# Requires https://github.com/Wiznet/ioLibrary_Driver/pull/120
# url = https://github.com/Wiznet/ioLibrary_Driver.git
[submodule "lib/cyw43-driver"]
path = lib/cyw43-driver
url = https://github.com/georgerobotics/cyw43-driver.git
[submodule "lib/micropython-lib"]
path = lib/micropython-lib
url = https://github.com/micropython/micropython-lib.git

13
.pre-commit-config.yaml Normal file
View File

@ -0,0 +1,13 @@
repos:
- repo: local
hooks:
- id: codeformat
name: MicroPython codeformat.py for changed files
entry: tools/codeformat.py -v -f
language: python
- id: verifygitlog
name: MicroPython git commit message format checker
entry: tools/verifygitlog.py --check-file --ignore-rebase
language: python
verbose: true
stages: [commit-msg]

90
CODECONVENTIONS.md
View File

@ -65,6 +65,96 @@ changes to the correct style. Without arguments this tool will reformat all
source code (and may take some time to run). Otherwise pass as arguments to
the tool the files that changed and it will only reformat those.
uncrustify
==========
Only [uncrustify](https://github.com/uncrustify/uncrustify) v0.71 or v0.72 can
be used for MicroPython. Different uncrustify versions produce slightly
different formatting, and the configuration file formats are often
incompatible. v0.73 or newer *will not work*.
Depending on your operating system version, it may be possible to install a pre-compiled
uncrustify version:
Ubuntu, Debian
--------------
Ubuntu versions 21.10 or 22.04LTS, and Debian versions bullseye or bookworm all
include v0.72 so can be installed directly:
```
$ apt install uncrustify
```
Arch Linux
----------
The current Arch uncrustify version is too new. There is an [old Arch package
for v0.72](https://archive.archlinux.org/packages/u/uncrustify/) that can be
installed from the Arch Linux archive ([more
information](https://wiki.archlinux.org/title/Downgrading_packages#Arch_Linux_Archive)). Use
the [IgnorePkg feature](https://wiki.archlinux.org/title/Pacman#Skip_package_from_being_upgraded)
to prevent it re-updating.
Brew
----
This command may work, please raise a new Issue if it doesn't:
```
curl -L https://github.com/Homebrew/homebrew-core/raw/2b07d8192623365078a8b855a164ebcdf81494a6/Formula/uncrustify.rb > uncrustify.rb && brew install uncrustify.rb && rm uncrustify.rb
```
Automatic Pre-Commit Hooks
==========================
To have code formatting and commit message conventions automatically checked,
a configuration file is provided for the [pre-commit](https://pre-commit.com/)
tool.
First install `pre-commit`, either from your system package manager or via
`pip`. When installing `pre-commit` via pip, it is recommended to use a
virtual environment. Other sources, such as Brew are also available, see
[the docs](https://pre-commit.com/index.html#install) for details.
```
$ apt install pre-commit # Ubuntu, Debian
$ pacman -Sy python-precommit # Arch Linux
$ brew install pre-commit # Brew
$ pip install pre-commit # PyPI
```
Next, install [uncrustify (see above)](#uncrustify). Other dependencies are managed by
pre-commit automatically, but uncrustify needs to be installed and available on
the PATH.
Then, inside the MicroPython repository, register the git hooks for pre-commit
by running:
```
$ pre-commit install --hook-type pre-commit --hook-type commit-msg
```
pre-commit will now automatically run during `git commit` for both code and
commit message formatting.
The same formatting checks will be run by CI for any Pull Request submitted to
MicroPython. Pre-commit allows you to see any failure more quickly, and in many
cases will automatically correct it in your local working copy.
To unregister `pre-commit` from your MicroPython repository, run:
```
$ pre-commit uninstall --hook-type pre-commit --hook-type commit-msg
```
Tips:
* To skip pre-commit checks on a single commit, use `git commit -n` (for
`--no-verify`).
* To ignore the pre-commit message format check temporarily, start the commit
message subject line with "WIP" (for "Work In Progress").
Python code conventions
=======================

3
LICENSE
View File

@ -1,6 +1,6 @@
The MIT License (MIT)
Copyright (c) 2013-2022 Damien P. George
Copyright (c) 2013-2023 Damien P. George
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
@ -35,7 +35,6 @@ used during the build process and is not part of the compiled source code.
/ (MIT)
/drivers
/cc3000 (BSD-3-clause)
/cc3100 (BSD-3-clause)
/wiznet5k (BSD-3-clause)
/lib

268
README.md
View File

@ -211,167 +211,43 @@ 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). The following core datatypes are provided: `str` (including
basic Unicode support), `bytes`, `bytearray`, `tuple`, `list`, `dict`, `set`,
`frozenset`, `array.array`, `collections.namedtuple`, classes and instances.
Builtin modules include `sys`, `time`, and `struct`, etc. Select ports have
support for `_thread` module (multithreading). Note that only a subset of
Python 3 functionality is implemented for the data types and modules.
Python 3.5 and some select features from later versions). The following core
datatypes are provided: `str`(including basic Unicode support), `bytes`,
`bytearray`, `tuple`, `list`, `dict`, `set`, `frozenset`, `array.array`,
`collections.namedtuple`, classes and instances. Builtin modules include
`os`, `sys`, `time`, `re`, and `struct`, etc. Select ports have support for
`_thread` module (multithreading), `socket` and `ssl` for networking, and
`asyncio`. Note that only a subset of Python 3 functionality is implemented
for the data types and modules.
MicroPython can execute scripts in textual source form or from precompiled
bytecode, in both cases either from an on-device filesystem or "frozen" into
the MicroPython executable.
MicroPython can execute scripts in textual source form (.py files) or from
precompiled bytecode (.mpy files), in both cases either from an on-device
filesystem or "frozen" into the MicroPython executable.
See the repository http://github.com/micropython/pyboard for the MicroPython
board (PyBoard), the officially supported reference electronic circuit board.
MicroPython also provides a set of MicroPython-specific modules to access
hardware-specific functionality and peripherals such as GPIO, Timers, ADC,
DAC, PWM, SPI, I2C, CAN, Bluetooth, and USB.
Major components in this repository:
- py/ -- the core Python implementation, including compiler, runtime, and
core library.
- mpy-cross/ -- the MicroPython cross-compiler which is used to turn scripts
into precompiled bytecode.
- ports/unix/ -- a version of MicroPython that runs on Unix.
- ports/stm32/ -- a version of MicroPython that runs on the PyBoard and similar
STM32 boards (using ST's Cube HAL drivers).
- ports/minimal/ -- a minimal MicroPython port. Start with this if you want
to port MicroPython to another microcontroller.
- tests/ -- test framework and test scripts.
- docs/ -- user documentation in Sphinx reStructuredText format. Rendered
HTML documentation is available at http://docs.micropython.org.
Getting started
---------------
Additional components:
- ports/bare-arm/ -- a bare minimum version of MicroPython for ARM MCUs. Used
mostly to control code size.
- ports/teensy/ -- a version of MicroPython that runs on the Teensy 3.1
(preliminary but functional).
- ports/pic16bit/ -- a version of MicroPython for 16-bit PIC microcontrollers.
- ports/cc3200/ -- a version of MicroPython that runs on the CC3200 from TI.
- ports/esp8266/ -- a version of MicroPython that runs on Espressif's ESP8266 SoC.
- ports/esp32/ -- a version of MicroPython that runs on Espressif's ESP32 SoC.
- ports/nrf/ -- a version of MicroPython that runs on Nordic's nRF51 and nRF52 MCUs.
- extmod/ -- additional (non-core) modules implemented in C.
- tools/ -- various tools, including the pyboard.py module.
- examples/ -- a few example Python scripts.
See the [online documentation](https://docs.micropython.org/) for API
references and information about using MicroPython and information about how
it is implemented.
The subdirectories above may include READMEs with additional info.
We use [GitHub Discussions](https://github.com/micropython/micropython/discussions)
as our forum, and [Discord](https://discord.gg/RB8HZSAExQ) for chat. These
are great places to ask questions and advice from the community or to discuss your
MicroPython-based projects.
"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`).
For bugs and feature requests, please [raise an issue](https://github.com/micropython/micropython/issues/new/choose)
and follow the templates there.
The MicroPython cross-compiler, mpy-cross
-----------------------------------------
Most ports require the MicroPython cross-compiler to be built first. This
program, called mpy-cross, is used to pre-compile Python scripts to .mpy
files which can then be included (frozen) into the firmware/executable for
a port. To build mpy-cross use:
$ cd mpy-cross
$ make
The Unix version
----------------
The "unix" port requires a standard Unix environment with gcc and GNU make.
x86 and x64 architectures are supported (i.e. x86 32- and 64-bit), as well
as ARM and MIPS. Making full-featured port to another architecture requires
writing some assembly code for the exception handling and garbage collection.
Alternatively, fallback implementation based on setjmp/longjmp can be used.
To build (see section below for required dependencies):
$ cd ports/unix
$ make submodules
$ make
Then to give it a try:
$ ./micropython
>>> list(5 * x + y for x in range(10) for y in [4, 2, 1])
Use `CTRL-D` (i.e. EOF) to exit the shell.
Learn about command-line options (in particular, how to increase heap size
which may be needed for larger applications):
$ ./micropython -h
Run complete testsuite:
$ make test
Unix version comes with a builtin package manager called upip, e.g.:
$ ./micropython -m upip install micropython-pystone
$ ./micropython -m pystone
Browse available modules on
[PyPI](https://pypi.python.org/pypi?%3Aaction=search&term=micropython).
Standard library modules come from
[micropython-lib](https://github.com/micropython/micropython-lib) project.
External dependencies
---------------------
Building MicroPython ports may require some dependencies installed.
For Unix port, `libffi` library and `pkg-config` tool are required. On
Debian/Ubuntu/Mint derivative Linux distros, install `build-essential`
(includes toolchain and make), `libffi-dev`, and `pkg-config` packages.
Other dependencies can be built together with MicroPython. This may
be required to enable extra features or capabilities, and in recent
versions of MicroPython, these may be enabled by default. To build
these additional dependencies, in the port directory you're
interested in (e.g. `ports/unix/`) first execute:
$ make submodules
This will fetch all the relevant git submodules (sub repositories) that
the port needs. Use the same command to get the latest versions of
submodules as they are updated from time to time. After that execute:
$ make deplibs
This will build all available dependencies (regardless whether they
are used or not). If you intend to build MicroPython with additional
options (like cross-compiling), the same set of options should be passed
to `make deplibs`. To actually enable/disable use of dependencies, edit
`ports/unix/mpconfigport.mk` file, which has inline descriptions of the options.
For example, to build SSL module (required for `upip` tool described above,
and so enabled by default), `MICROPY_PY_USSL` should be set to 1.
For some ports, building required dependences is transparent, and happens
automatically. But they still need to be fetched with the `make submodules`
command.
The STM32 version
-----------------
The "stm32" port requires an ARM compiler, arm-none-eabi-gcc, and associated
bin-utils. For those using Arch Linux, you need arm-none-eabi-binutils,
arm-none-eabi-gcc and arm-none-eabi-newlib packages. Otherwise, try here:
https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm
To build:
$ cd ports/stm32
$ make submodules
$ make
You then need to get your board into DFU mode. On the pyboard, connect the
3V3 pin to the P1/DFU pin with a wire (on PYBv1.0 they are next to each other
on the bottom left of the board, second row from the bottom).
Then to flash the code via USB DFU to your device:
$ make deploy
This will use the included `tools/pydfu.py` script. If flashing the firmware
does not work it may be because you don't have the correct permissions, and
need to use `sudo make deploy`.
See the README.md file in the ports/stm32/ directory for further details.
For information about the [MicroPython pyboard](https://store.micropython.org/pyb-features),
the officially supported board from the
[original Kickstarter campaign](https://www.kickstarter.com/projects/214379695/micro-python-python-for-microcontrollers),
see the [schematics and pinouts](http://github.com/micropython/pyboard) and
[documentation](https://docs.micropython.org/en/latest/pyboard/quickref.html).
Contributing
------------
@ -382,3 +258,87 @@ productive, please be sure to follow the
and the [Code Conventions](https://github.com/micropython/micropython/blob/master/CODECONVENTIONS.md).
Note that MicroPython is licenced under the MIT license, and all contributions
should follow this license.
About this repository
---------------------
This repository contains the following components:
- [py/](py/) -- the core Python implementation, including compiler, runtime, and
core library.
- [mpy-cross/](mpy-cross/) -- the MicroPython cross-compiler which is used to turn scripts
into precompiled bytecode.
- [ports/](ports/) -- platform-specific code for the various ports and architectures that MicroPython runs on.
- [lib/](lib/) -- submodules for external dependencies.
- [tests/](tests/) -- test framework and test scripts.
- [docs/](docs/) -- user documentation in Sphinx reStructuredText format. This is used to generate the [online documentation](http://docs.micropython.org).
- [extmod/](extmod/) -- additional (non-core) modules implemented in C.
- [tools/](tools/) -- various tools, including the pyboard.py module.
- [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.
Supported platforms & architectures
-----------------------------------
MicroPython runs on a wide range of microcontrollers, as well as on Unix-like
(including Linux, BSD, macOS, WSL) and Windows systems.
Microcontroller targets can be as small as 256kiB flash + 16kiB RAM, although
devices with at least 512kiB flash + 128kiB RAM allow a much more
full-featured experience.
The [Unix](ports/unix) and [Windows](ports/windows) ports allow both
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).
- [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-arm](ports/qemu-arm) -- 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)
- [teensy](ports/teensy) -- Teensy 3.x.
- [webassembly](ports/webassembly) -- Emscripten port targeting browsers and NodeJS.
- [zephyr](ports/zephyr) -- Zephyr RTOS.
The MicroPython cross-compiler, mpy-cross
-----------------------------------------
Most ports require the [MicroPython cross-compiler](mpy-cross) to be built
first. This program, called mpy-cross, is used to pre-compile Python scripts
to .mpy files which can then be included (frozen) into the
firmware/executable for a port. To build mpy-cross use:
$ cd mpy-cross
$ make
External dependencies
---------------------
The core MicroPython VM and runtime has no external dependencies, but a given
port might depend on third-party drivers or vendor HALs. This repository
includes [several submodules](lib/) linking to these external dependencies.
Before compiling a given port, use
$ cd ports/name
$ make submodules
to ensure that all required submodules are initialised.

2
docs/Makefile
View File

@ -3,7 +3,7 @@
# You can set these variables from the command line.
PYTHON = python3
SPHINXOPTS = -W --keep-going
SPHINXOPTS = -W --keep-going -j auto
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build/$(MICROPY_PORT)

6
docs/README.md
View File

@ -47,7 +47,7 @@ This can be achieved with:
make latexpdf
but require rather complete install of LaTeX with various extensions. On
Debian/Ubuntu, try (500MB+ download):
but requires a rather complete install of LaTeX with various extensions. On
Debian/Ubuntu, try (1GB+ download):
apt-get install texlive-latex-recommended texlive-latex-extra
apt install texlive-latex-recommended texlive-latex-extra texlive-xetex texlive-fonts-extra cm-super xindy

11
docs/conf.py
View File

@ -33,6 +33,7 @@ html_context = {
'downloads':[
('PDF', url_pattern % micropy_version + '/micropython-docs.pdf'),
],
'is_release': micropy_version != 'latest',
}
@ -66,7 +67,7 @@ master_doc = 'index'
# General information about the project.
project = 'MicroPython'
copyright = '- The MicroPython Documentation is Copyright © 2014-2022, Damien P. George, Paul Sokolovsky, and contributors'
copyright = '- The MicroPython Documentation is Copyright © 2014-2023, Damien P. George, Paul Sokolovsky, and contributors'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@ -74,7 +75,7 @@ copyright = '- The MicroPython Documentation is Copyright © 2014-2022, Damien P
#
# 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.19.1'
version = release = micropy_version
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@ -166,6 +167,10 @@ html_favicon = 'static/favicon.ico'
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['static']
# Add a custom CSS file for HTML generation
html_css_files = [
'custom.css',
]
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
@ -259,6 +264,8 @@ latex_documents = [
# If false, no module index is generated.
#latex_domain_indices = True
# Enable better Unicode support so that `make latexpdf` doesn't fail
latex_engine = "xelatex"
# -- Options for manual page output ---------------------------------------

33
docs/develop/cmodules.rst
View File

@ -49,9 +49,17 @@ A MicroPython user C module is a directory with the following files:
in your ``micropython.mk`` to a local make variable,
eg ``EXAMPLE_MOD_DIR := $(USERMOD_DIR)``
Your ``micropython.mk`` must add your modules source files relative to your
expanded copy of ``$(USERMOD_DIR)`` to ``SRC_USERMOD``, eg
``SRC_USERMOD += $(EXAMPLE_MOD_DIR)/example.c``
Your ``micropython.mk`` must add your modules source files to the
``SRC_USERMOD_C`` or ``SRC_USERMOD_LIB_C`` variables. The former will be
processed for ``MP_QSTR_`` and ``MP_REGISTER_MODULE`` definitions, the latter
will not (e.g. helpers and library code that isn't MicroPython-specific).
These paths should include your expaned copy of ``$(USERMOD_DIR)``, e.g.::
SRC_USERMOD_C += $(EXAMPLE_MOD_DIR)/modexample.c
SRC_USERMOD_LIB_C += $(EXAMPLE_MOD_DIR)/utils/algorithm.c
Similarly, use ``SRC_USERMOD_CXX`` and ``SRC_USERMOD_LIB_CXX`` for C++
source files.
If you have custom compiler options (like ``-I`` to add directories to search
for header files), these should be added to ``CFLAGS_USERMOD`` for C code
@ -87,9 +95,12 @@ A MicroPython user C module is a directory with the following files:
Basic example
-------------
This simple module named ``cexample`` provides a single function
``cexample.add_ints(a, b)`` which adds the two integer args together and returns
the result. It can be found in the MicroPython source tree
The ``cexample`` module provides examples for a function and a class. The
``cexample.add_ints(a, b)`` function adds two integer args together and returns
the result. The ``cexample.Timer()`` type creates timers that can be used to
measure the elapsed time since the object is instantiated.
The module can be found in the MicroPython source tree
`in the examples directory <https://github.com/micropython/micropython/tree/master/examples/usercmodule/cexample>`_
and has a source file and a Makefile fragment with content as described above::
@ -264,3 +275,13 @@ can now be accessed in Python just like any other builtin module, e.g.
import cexample
print(cexample.add_ints(1, 3))
# should display 4
.. code-block:: python
from cexample import Timer
from time import sleep_ms
watch = Timer()
sleep_ms(1000)
print(watch.time())
# should display approximately 1000

11
docs/develop/compiler.rst
View File

@ -147,10 +147,17 @@ The most relevant method you should know about is this:
.. code-block:: c
mp_obj_t mp_compile(mp_parse_tree_t *parse_tree, qstr source_file, bool is_repl) {
// Create a context for this module, and set its globals dict.
mp_module_context_t *context = m_new_obj(mp_module_context_t);
context->module.globals = mp_globals_get();
// Compile the input parse_tree to a raw-code structure.
mp_raw_code_t *rc = mp_compile_to_raw_code(parse_tree, source_file, is_repl);
mp_compiled_module_t cm;
cm.context = context;
mp_compile_to_raw_code(parse_tree, source_file, is_repl, &cm);
// Create and return a function object that executes the outer module.
return mp_make_function_from_raw_code(rc, MP_OBJ_NULL, MP_OBJ_NULL);
return mp_make_function_from_raw_code(cm.rc, cm.context, NULL);
}
The compiler compiles the code in four passes: scope, stack size, code size and emit.

5
docs/develop/gettingstarted.rst
View File

@ -103,7 +103,7 @@ For the stm32 port, the ARM cross-compiler is required:
$ sudo apt-get install arm-none-eabi-gcc arm-none-eabi-binutils arm-none-eabi-newlib
See the `ARM GCC
toolchain <https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm>`_
toolchain <https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads>`_
for the latest details.
Python is also required. Python 2 is supported for now, but we recommend using Python 3.
@ -322,7 +322,8 @@ tests
tools
Contains helper tools including the ``upip`` and the ``pyboard.py`` module.
Contains scripts used by the build and CI process, as well as user tools such
as ``pyboard.py`` and ``mpremote``.
examples

2
docs/develop/optimizations.rst
View File

@ -25,6 +25,8 @@ into the firmware image as part of the main firmware compilation process, which
the bytecode will be executed from ROM. This can lead to a significant memory saving, and
reduce heap fragmentation.
See :ref:`manifest` for more information.
Variables
---------

8
docs/develop/porting.rst
View File

@ -95,10 +95,11 @@ We also need a Makefile at this point for the port:
# Include py core make definitions.
include $(TOP)/py/py.mk
include $(TOP)/extmod/extmod.mk
# Set CFLAGS and libraries.
CFLAGS = -I. -I$(BUILD) -I$(TOP)
LIBS = -lm
CFLAGS += -I. -I$(BUILD) -I$(TOP)
LIBS += -lm
# Define the required source files.
SRC_C = \
@ -173,9 +174,6 @@ The following is an example of an ``mpconfigport.h`` file:
#define MP_STATE_PORT MP_STATE_VM
#define MICROPY_PORT_ROOT_POINTERS \
const char *readline_hist[8];
This configuration file contains machine-specific configurations including aspects like if different
MicroPython features should be enabled e.g. ``#define MICROPY_ENABLE_GC (1)``. Making this Setting
``(0)`` disables the feature.

1
docs/differences/index_template.txt
View File

@ -13,6 +13,7 @@ above. The sections below describe the current status of these features.
../differences/python_37.rst
../differences/python_38.rst
../differences/python_39.rst
../differences/python_310.rst
For the features of Python that are implemented by MicroPython, there are
sometimes differences in their behaviour compared to standard Python. The

238
docs/differences/python_310.rst Normal file
View File

@ -0,0 +1,238 @@
.. _python_310:
Python 3.10
===========
Python 3.10.0 (final) was released on the 4 October 2021. The Features for 3.10 are
defined in `PEP 619 <https://www.python.org/dev/peps/pep-0619/#features-for-3-10>`_
and a detailed description of the changes can be found in
`What's New in Python 3.10 <https://docs.python.org/3/whatsnew/3.10.html>`_.
.. table::
:widths: 20 60 20
+--------------------------------------------------------+----------------------------------------------------+--------------+
| **New syntax features** | **Status** |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 634 <https://www.python.org/dev/peps/pep-0634/>`_ | Structural Pattern Matching: Specification | [#spm]_ |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 635 <https://www.python.org/dev/peps/pep-0635/>`_ | Structural Pattern Matching: Motivation and | [#spm]_ |
| | Rationale | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 636 <https://www.python.org/dev/peps/pep-0636/>`_ | Structural Pattern Matching: Tutorial | [#spm]_ |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `bpo-12782 | Parenthesized context managers are now officially | |
| <https://github.com/python/cpython/issues/56991>`_ | allowed | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| **New features in the standard library** |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 618 <https://www.python.org/dev/peps/pep-0618/>`_ | Add Optional Length-Checking To zip | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| **Interpreter improvements** |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 626 <https://www.python.org/dev/peps/pep-0626/>`_ | Precise line numbers for debugging and other tools | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| **New typing features** |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 604 <https://www.python.org/dev/peps/pep-0604/>`_ | Allow writing union types as X | Y | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 613 <https://www.python.org/dev/peps/pep-0613/>`_ | Explicit Type Aliases | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 612 <https://www.python.org/dev/peps/pep-0612/>`_ | Parameter Specification Variables | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| **Important deprecations, removals or restrictions** |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 644 <https://www.python.org/dev/peps/pep-0644/>`_ | Require OpenSSL 1.1.1 or newer | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 632 <https://www.python.org/dev/peps/pep-0632/>`_ | Deprecate distutils module. | Not relevant |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 623 <https://www.python.org/dev/peps/pep-0623/>`_ | Deprecate and prepare for the removal of the wstr | Not relevant |
| | member in PyUnicodeObject. | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 624 <https://www.python.org/dev/peps/pep-0624/>`_ | Remove Py_UNICODE encoder APIs | Not relevant |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 597 <https://www.python.org/dev/peps/pep-0597/>`_ | Add optional EncodingWarning | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
Other Language Changes:
.. table::
:widths: 90 10
+-------------------------------------------------------------------------------------------------------------+---------------+
| The :class:`int` type has a new method :meth:`int.bit_count`, returning the | |
| number of ones in the binary expansion of a given integer, also known | |
| as the population count. | |
+-------------------------------------------------------------------------------------------------------------+---------------+
| The views returned by :meth:`dict.keys`, :meth:`dict.values` and | |
| :meth:`dict.items` now all have a ``mapping`` attribute that gives a | |
| :class:`types.MappingProxyType` object wrapping the original | |
| dictionary. | |
+-------------------------------------------------------------------------------------------------------------+---------------+
| :pep:`618`: The :func:`zip` function now has an optional ``strict`` flag, used | |
| to require that all the iterables have an equal length. | |
+-------------------------------------------------------------------------------------------------------------+---------------+
| Builtin and extension functions that take integer arguments no longer accept | |
| :class:`~decimal.Decimal`\ s, :class:`~fractions.Fraction`\ s and other | |
| objects that can be converted to integers only with a loss (e.g. that have | |
| the :meth:`~object.__int__` method but do not have the | |
| :meth:`~object.__index__` method). | |
+-------------------------------------------------------------------------------------------------------------+---------------+
| If :func:`object.__ipow__` returns :const:`NotImplemented`, the operator will | |
| correctly fall back to :func:`object.__pow__` and :func:`object.__rpow__` as expected. | |
+-------------------------------------------------------------------------------------------------------------+---------------+
| Assignment expressions can now be used unparenthesized within set literals | |
| and set comprehensions, as well as in sequence indexes (but not slices). | |
+-------------------------------------------------------------------------------------------------------------+---------------+
| Functions have a new ``__builtins__`` attribute which is used to look for | |
| builtin symbols when a function is executed, instead of looking into | |
| ``__globals__['__builtins__']``. The attribute is initialized from | |
| ``__globals__["__builtins__"]`` if it exists, else from the current builtins. | |
+-------------------------------------------------------------------------------------------------------------+---------------+
| Two new builtin functions -- :func:`aiter` and :func:`anext` have been added | |
| to provide asynchronous counterparts to :func:`iter` and :func:`next`, | |
| respectively. | |
+-------------------------------------------------------------------------------------------------------------+---------------+
| Static methods (:func:`@staticmethod <staticmethod>`) and class methods | |
| (:func:`@classmethod <classmethod>`) now inherit the method attributes | |
| (``__module__``, ``__name__``, ``__qualname__``, ``__doc__``, | |
| ``__annotations__``) and have a new ``__wrapped__`` attribute. | |
| Moreover, static methods are now callable as regular functions. | |
+-------------------------------------------------------------------------------------------------------------+---------------+
| Annotations for complex targets (everything beside ``simple name`` targets | |
| defined by :pep:`526`) no longer cause any runtime effects with ``from __future__ import annotations``. | |
+-------------------------------------------------------------------------------------------------------------+---------------+
| Class and module objects now lazy-create empty annotations dicts on demand. | |
| The annotations dicts are stored in the object’s ``__dict__`` for | |
| backwards compatibility. This improves the best practices for working | |
| with ``__annotations__``. | |
+-------------------------------------------------------------------------------------------------------------+---------------+
| Annotations consist of ``yield``, ``yield from``, ``await`` or named expressions | |
| are now forbidden under ``from __future__ import annotations`` due to their side | |
| effects. | |
+-------------------------------------------------------------------------------------------------------------+---------------+
| Usage of unbound variables, ``super()`` and other expressions that might | |
| alter the processing of symbol table as annotations are now rendered | |
| effectless under ``from __future__ import annotations``. | |
+-------------------------------------------------------------------------------------------------------------+---------------+
| Hashes of NaN values of both :class:`float` type and | |
| :class:`decimal.Decimal` type now depend on object identity. Formerly, they | |
| always hashed to ``0`` even though NaN values are not equal to one another. | |
| This caused potentially quadratic runtime behavior due to excessive hash | |
| collisions when creating dictionaries and sets containing multiple NaNs. | |
+-------------------------------------------------------------------------------------------------------------+---------------+
| A :exc:`SyntaxError` (instead of a :exc:`NameError`) will be raised when deleting | |
| the :const:`__debug__` constant. | |
+-------------------------------------------------------------------------------------------------------------+---------------+
| :exc:`SyntaxError` exceptions now have ``end_lineno`` and | |
| ``end_offset`` attributes. They will be ``None`` if not determined. | |
+-------------------------------------------------------------------------------------------------------------+---------------+
Changes to built-in modules:
.. table::
:widths: 90 10
+---------------------------------------------------------------------------------------------------------------+---------------+
| `asyncio <https://docs.python.org/3/whatsnew/3.10.html#asyncio>`_ |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Add missing :meth:`~asyncio.events.AbstractEventLoop.connect_accepted_socket` | |
| method. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| `array <https://docs.python.org/3/whatsnew/3.10.html#array>`_ |
+---------------------------------------------------------------------------------------------------------------+---------------+
| The :meth:`~array.array.index` method of :class:`array.array` now has | |
| optional *start* and *stop* parameters. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| `gc <https://docs.python.org/3/whatsnew/3.10.html#gc>`_ |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Add audit hooks for :func:`gc.get_objects`, :func:`gc.get_referrers` and | |
| :func:`gc.get_referents`. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| `hashlib <https://docs.python.org/3/whatsnew/3.10.html#hashlib>`_ |
+---------------------------------------------------------------------------------------------------------------+---------------+
| The hashlib module requires OpenSSL 1.1.1 or newer. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| The hashlib module has preliminary support for OpenSSL 3.0.0. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| The pure-Python fallback of :func:`~hashlib.pbkdf2_hmac` is deprecated. In | |
| the future PBKDF2-HMAC will only be available when Python has been built with | |
| OpenSSL support. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| `os <https://docs.python.org/3/whatsnew/3.10.html#os>`_ |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Add :func:`os.cpu_count()` support for VxWorks RTOS. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Add a new function :func:`os.eventfd` and related helpers to wrap the | |
| ``eventfd2`` syscall on Linux. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Add :func:`os.splice()` that allows to move data between two file | |
| descriptors without copying between kernel address space and user | |
| address space, where one of the file descriptors must refer to a | |
| pipe. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Add :data:`~os.O_EVTONLY`, :data:`~os.O_FSYNC`, :data:`~os.O_SYMLINK` | |
| and :data:`~os.O_NOFOLLOW_ANY` for macOS. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| `platform <https://docs.python.org/3/whatsnew/3.10.html#platform>`_ |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Add :func:`platform.freedesktop_os_release()` to retrieve operation system | |
| identification from `freedesktop.org os-release | |
| <https://www.freedesktop.org/software/systemd/man/os-release.html>`_ standard file. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| `socket <https://docs.python.org/3/whatsnew/3.10.html#socket>`_ |
+---------------------------------------------------------------------------------------------------------------+---------------+
| The exception :exc:`socket.timeout` is now an alias of :exc:`TimeoutError`. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Add option to create MPTCP sockets with ``IPPROTO_MPTCP``. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Add ``IP_RECVTOS`` option to receive the type of service (ToS) or DSCP/ECN fields. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| `ssl <https://docs.python.org/3/whatsnew/3.10.html#ssl>`_ |
+---------------------------------------------------------------------------------------------------------------+---------------+
| The ssl module requires OpenSSL 1.1.1 or newer. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| The ssl module has preliminary support for OpenSSL 3.0.0 and new option | |
| :data:`~ssl.OP_IGNORE_UNEXPECTED_EOF`. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Deprecated function and use of deprecated constants now result in | |
| a :exc:`DeprecationWarning`. :attr:`ssl.SSLContext.options` has | |
| :data:`~ssl.OP_NO_SSLv2` and :data:`~ssl.OP_NO_SSLv3` set by default and | |
| therefore cannot warn about setting the flag again. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| The ssl module now has more secure default settings. Ciphers without forward | |
| secrecy or SHA-1 MAC are disabled by default. Security level 2 prohibits | |
| weak RSA, DH, and ECC keys with less than 112 bits of security. | |
| :class:`~ssl.SSLContext` defaults to minimum protocol version TLS 1.2. | |
| Settings are based on Hynek Schlawack's research. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| The deprecated protocols SSL 3.0, TLS 1.0, and TLS 1.1 are no longer | |
| officially supported. Python does not block them actively. However | |
| OpenSSL build options, distro configurations, vendor patches, and cipher | |
| suites may prevent a successful handshake. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Add a *timeout* parameter to the :func:`ssl.get_server_certificate` function. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| The ssl module uses heap-types and multi-phase initialization. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| A new verify flag :data:`~ssl.VERIFY_X509_PARTIAL_CHAIN` has been added. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| `sys <https://docs.python.org/3/whatsnew/3.10.html#sys>`_ |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Add :data:`sys.orig_argv` attribute: the list of the original command line | |
| arguments passed to the Python executable. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Add :data:`sys.stdlib_module_names`, containing the list of the standard library | |
| module names. | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| `_thread <https://docs.python.org/3/whatsnew/3.10.html#_thread>`_ |
+---------------------------------------------------------------------------------------------------------------+---------------+
| :func:`_thread.interrupt_main` now takes an optional signal number to | |
| simulate (the default is still :data:`signal.SIGINT`). | |
+---------------------------------------------------------------------------------------------------------------+---------------+
.. rubric:: Notes
.. [#spm] The structural pattern matching feature is discussed in `issue #7847 <https://github.com/micropython/micropython/issues/7847>`_.

330
docs/differences/python_35.rst
View File

@ -5,55 +5,60 @@ Python 3.5
Below is a list of finalised/accepted PEPs for Python 3.5 grouped into their impact to MicroPython.
+----------------------------------------------------------------------------------------------------------+---------------+
| **Extensions to the syntax:** | **Status** |
+--------------------------------------------------------+-------------------------------------------------+---------------+
| `PEP 448 <https://www.python.org/dev/peps/pep-0448/>`_ | additional unpacking generalizations | Partial |
+--------------------------------------------------------+-------------------------------------------------+---------------+
| `PEP 465 <https://www.python.org/dev/peps/pep-0465/>`_ | a new matrix multiplication operator | Completed |
+--------------------------------------------------------+-------------------------------------------------+---------------+
| `PEP 492 <https://www.python.org/dev/peps/pep-0492/>`_ | coroutines with async and await syntax | Completed |
+--------------------------------------------------------+-------------------------------------------------+---------------+
| **Extensions and changes to runtime:** |
+--------------------------------------------------------+-------------------------------------------------+---------------+
| `PEP 461 <https://www.python.org/dev/peps/pep-0461/>`_ | % formatting for binary strings | Completed |
+--------------------------------------------------------+-------------------------------------------------+---------------+
| `PEP 475 <https://www.python.org/dev/peps/pep-0475/>`_ | retrying system calls that fail with EINTR | Completed |
+--------------------------------------------------------+-------------------------------------------------+---------------+
| `PEP 479 <https://www.python.org/dev/peps/pep-0479/>`_ | change StopIteration handling inside generators | Completed |
+--------------------------------------------------------+-------------------------------------------------+---------------+
| **Standard library changes:** |
+--------------------------------------------------------+-------------------------------------------------+---------------+
| `PEP 471 <https://www.python.org/dev/peps/pep-0471/>`_ | os.scandir() | |
+--------------------------------------------------------+-------------------------------------------------+---------------+
| `PEP 485 <https://www.python.org/dev/peps/pep-0485/>`_ | math.isclose(), a function for testing | Completed |
| | approximate equality | |
+--------------------------------------------------------+-------------------------------------------------+---------------+
| **Miscellaneous changes:** |
+--------------------------------------------------------+-------------------------------------------------+---------------+
| `PEP 441 <https://www.python.org/dev/peps/pep-0441/>`_ | improved Python zip application support | |
+--------------------------------------------------------+-------------------------------------------------+---------------+
| `PEP 486 <https://www.python.org/dev/peps/pep-0486/>`_ | make the Python Launcher aware of virtual | Not relevant |
| | environments | |
+--------------------------------------------------------+-------------------------------------------------+---------------+
| `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ | type hints (advisory only) | In Progress |
+--------------------------------------------------------+-------------------------------------------------+---------------+
| `PEP 488 <https://www.python.org/dev/peps/pep-0488/>`_ | elimination of PYO files | Not relevant |
+--------------------------------------------------------+-------------------------------------------------+---------------+
| `PEP 489 <https://www.python.org/dev/peps/pep-0489/>`_ | redesigning extension module loading | |
+--------------------------------------------------------+-------------------------------------------------+---------------+
.. table::
:widths: 30 50 20
+--------------------------------------------------------------------------------------------------------------+--------------------+
| **Extensions to the syntax** | **Status** |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
| `PEP 448 <https://www.python.org/dev/peps/pep-0448/>`_ | Additional unpacking generalizations | Partial |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
| `PEP 465 <https://www.python.org/dev/peps/pep-0465/>`_ | A new matrix multiplication operator | Complete |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
| `PEP 492 <https://www.python.org/dev/peps/pep-0492/>`_ | Coroutines with ``async`` and ``await`` syntax | Complete |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
| **Extensions and changes to runtime** |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
| `PEP 461 <https://www.python.org/dev/peps/pep-0461/>`_ | % formatting for binary strings | Complete |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
| `PEP 475 <https://www.python.org/dev/peps/pep-0475/>`_ | Retrying system calls that fail with ``EINTR`` | Complete |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
| `PEP 479 <https://www.python.org/dev/peps/pep-0479/>`_ | Change ``StopIteration`` handling inside generators | Complete |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
| **Standard library changes** |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
| `PEP 471 <https://www.python.org/dev/peps/pep-0471/>`_ | ``os.scandir()`` | |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
| `PEP 485 <https://www.python.org/dev/peps/pep-0485/>`_ | ``math.isclose()``, a function for testing | Complete |
| | approximate equality | |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
| **Miscellaneous changes** |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
| `PEP 441 <https://www.python.org/dev/peps/pep-0441/>`_ | Improved Python zip application support | |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
| `PEP 486 <https://www.python.org/dev/peps/pep-0486/>`_ | Make the Python Launcher aware of virtual | Not relevant |
| | environments | |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
| `PEP 484 <https://www.python.org/dev/peps/pep-0484/>`_ | Type hints (advisory only) | Complete [#fth]_ |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
| `PEP 488 <https://www.python.org/dev/peps/pep-0488/>`_ | Elimination of PYO files | Not relevant |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
| `PEP 489 <https://www.python.org/dev/peps/pep-0489/>`_ | Redesigning extension module loading | |
+--------------------------------------------------------+-----------------------------------------------------+--------------------+
Other Language Changes:
+-----------------------------------------------------------------------------------------------------------+---------------+
| Added the *namereplace* error handlers. The *backslashreplace* error handlers now work with decoding and | |
| translating. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| Property docstrings are now writable. This is especially useful for collections.namedtuple() docstrings | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| Circular imports involving relative imports are now supported. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
.. table::
:widths: 90 10
+-----------------------------------------------------------------------------------------------------------+---------------+
| Added the *namereplace* error handlers. The *backslashreplace* error handlers now work with decoding and | |
| translating. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| Property docstrings are now writable. This is especially useful for collections.namedtuple() docstrings | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| Circular imports involving relative imports are now supported. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
New Modules:
@ -65,117 +70,124 @@ New Modules:
Changes to built-in modules:
+-----------------------------------------------------------------------------------------------------------+---------------+
| `collections <https://docs.python.org/3/whatsnew/3.5.html#collections>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *OrderedDict* class is now implemented in C, which makes it 4 to 100 times faster. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| *OrderedDict.items()* , *OrderedDict.keys()* , *OrderedDict.values()* views now support reversed() | |
| iteration. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The deque class now defines *index()*, *insert()*, and *copy()*, and supports the + and * operators. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| Docstrings produced by namedtuple() can now be updated. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The UserString class now implements the *__getnewargs__()*, *__rmod__()*, *casefold()*, *format_map()*, | |
| *isprintable()*, and *maketrans()* methods to match the corresponding methods of str. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `heapq <https://docs.python.org/3/whatsnew/3.5.html#heapq>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| Element comparison in *merge()* can now be customized by passing a key function in a new optional key | |
| keyword argument, and a new optional *reverse* keyword argument can be used to reverse element comparison | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `io <https://docs.python.org/3/whatsnew/3.5.html#io>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| A new *BufferedIOBase.readinto1()* method, that uses at most one call to the underlying raw stream's | |
| *RawIOBase.read()* or *RawIOBase.readinto()* methods | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `json <https://docs.python.org/3/whatsnew/3.5.html#json>`_ | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| JSON decoder now raises JSONDecodeError instead of ValueError to provide better context information about | |
| the error. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `math <https://docs.python.org/3/whatsnew/3.5.html#math>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| Two new constants have been added to the math module: *inf* and *nan*. | Completed |
+-----------------------------------------------------------------------------------------------------------+---------------+
| A new function *isclose()* provides a way to test for approximate equality. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| A new *gcd()* function has been added. The *fractions.gcd()* function is now deprecated. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `os <https://docs.python.org/3/whatsnew/3.5.html#os>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The new *scandir()* function returning an iterator of DirEntry objects has been added. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *urandom()* function now uses the *getrandom()* syscall on Linux 3.17 or newer, and *getentropy()* on | |
| OpenBSD 5.6 and newer, removing the need to use /dev/urandom and avoiding failures due to potential file | |
| descriptor exhaustion. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| New *get_blocking()* and *set_blocking()* functions allow getting and setting a file descriptor's blocking| |
| mode (O_NONBLOCK.) | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| There is a new *os.path.commonpath()* function returning the longest common sub-path of each passed | |
| pathname | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `re <https://docs.python.org/3/whatsnew/3.5.html#re>`_ | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| References and conditional references to groups with fixed length are now allowed in lookbehind assertions| |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The number of capturing groups in regular expressions is no longer limited to 100. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *sub()* and *subn()* functions now replace unmatched groups with empty strings instead of raising an | |
| exception. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *re.error* exceptions have new attributes, msg, pattern, pos, lineno, and colno, that provide better | |
| context information about the error | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `socket <https://docs.python.org/3/whatsnew/3.5.html#socket>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| Functions with timeouts now use a monotonic clock, instead of a system clock. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| A new *socket.sendfile()* method allows sending a file over a socket by using the high-performance | |
| *os.sendfile()* function on UNIX, resulting in uploads being from 2 to 3 times faster than when using | |
| plain *socket.send()* | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *socket.sendall()* method no longer resets the socket timeout every time bytes are received or sent. | |
| The socket timeout is now the maximum total duration to send all data. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The backlog argument of the *socket.listen()* method is now optional. By default it is set to SOMAXCONN or| Completed |
| to 128, whichever is less. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `ssl <https://docs.python.org/3/whatsnew/3.5.html#ssl>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| Memory BIO Support | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| Application-Layer Protocol Negotiation Support | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| There is a new *SSLSocket.version()* method to query the actual protocol version in use. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The SSLSocket class now implements a *SSLSocket.sendfile()* method. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *SSLSocket.send()* method now raises either the *ssl.SSLWantReadError* or *ssl.SSLWantWriteError* | |
| exception on a non-blocking socket if the operation would block. Previously, it would return 0. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *cert_time_to_seconds()* function now interprets the input time as UTC and not as local time, per RFC | |
| 5280. Additionally, the return value is always an int. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| New *SSLObject.shared_ciphers()* and *SSLSocket.shared_ciphers()* methods return the list of ciphers sent | |
| by the client during the handshake. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *SSLSocket.do_handshake()*, *SSLSocket.read()*, *SSLSocket.shutdown()*, and *SSLSocket.write()* | |
| methods of the SSLSocket class no longer reset the socket timeout every time bytes are received or sent. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *match_hostname()* function now supports matching of IP addresses. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `sys <https://docs.python.org/3/whatsnew/3.5.html#sys>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| A new *set_coroutine_wrapper()* function allows setting a global hook that will be called whenever a | |
| coroutine object is created by an async def function. A corresponding *get_coroutine_wrapper()* can be | |
| used to obtain a currently set wrapper. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| A new *is_finalizing()* function can be used to check if the Python interpreter is shutting down. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `time <https://docs.python.org/3/whatsnew/3.5.html#time>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *monotonic()* function is now always available | |
+-----------------------------------------------------------------------------------------------------------+---------------+
.. table::
:widths: 90 10
+-----------------------------------------------------------------------------------------------------------+---------------+
| `collections <https://docs.python.org/3/whatsnew/3.5.html#collections>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *OrderedDict* class is now implemented in C, which makes it 4 to 100 times faster. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| *OrderedDict.items()* , *OrderedDict.keys()* , *OrderedDict.values()* views now support reversed() | |
| iteration. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The deque class now defines *index()*, *insert()*, and *copy()*, and supports the + and * operators. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| Docstrings produced by namedtuple() can now be updated. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The UserString class now implements the *__getnewargs__()*, *__rmod__()*, *casefold()*, *format_map()*, | |
| *isprintable()*, and *maketrans()* methods to match the corresponding methods of str. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `heapq <https://docs.python.org/3/whatsnew/3.5.html#heapq>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| Element comparison in *merge()* can now be customized by passing a key function in a new optional key | |
| keyword argument, and a new optional *reverse* keyword argument can be used to reverse element comparison | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `io <https://docs.python.org/3/whatsnew/3.5.html#io>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| A new *BufferedIOBase.readinto1()* method, that uses at most one call to the underlying raw stream's | |
| *RawIOBase.read()* or *RawIOBase.readinto()* methods | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `json <https://docs.python.org/3/whatsnew/3.5.html#json>`_ | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| JSON decoder now raises JSONDecodeError instead of ValueError to provide better context information about | |
| the error. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `math <https://docs.python.org/3/whatsnew/3.5.html#math>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| Two new constants have been added to the math module: *inf* and *nan*. | Complete |
+-----------------------------------------------------------------------------------------------------------+---------------+
| A new function *isclose()* provides a way to test for approximate equality. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| A new *gcd()* function has been added. The *fractions.gcd()* function is now deprecated. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `os <https://docs.python.org/3/whatsnew/3.5.html#os>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The new *scandir()* function returning an iterator of DirEntry objects has been added. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *urandom()* function now uses the *getrandom()* syscall on Linux 3.17 or newer, and *getentropy()* on | |
| OpenBSD 5.6 and newer, removing the need to use /dev/urandom and avoiding failures due to potential file | |
| descriptor exhaustion. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| New *get_blocking()* and *set_blocking()* functions allow getting and setting a file descriptor's blocking| |
| mode (O_NONBLOCK.) | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| There is a new *os.path.commonpath()* function returning the longest common sub-path of each passed | |
| pathname | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `re <https://docs.python.org/3/whatsnew/3.5.html#re>`_ | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| References and conditional references to groups with fixed length are now allowed in lookbehind assertions| |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The number of capturing groups in regular expressions is no longer limited to 100. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *sub()* and *subn()* functions now replace unmatched groups with empty strings instead of raising an | |
| exception. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *re.error* exceptions have new attributes, msg, pattern, pos, lineno, and colno, that provide better | |
| context information about the error | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `socket <https://docs.python.org/3/whatsnew/3.5.html#socket>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| Functions with timeouts now use a monotonic clock, instead of a system clock. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| A new *socket.sendfile()* method allows sending a file over a socket by using the high-performance | |
| *os.sendfile()* function on UNIX, resulting in uploads being from 2 to 3 times faster than when using | |
| plain *socket.send()* | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *socket.sendall()* method no longer resets the socket timeout every time bytes are received or sent. | |
| The socket timeout is now the maximum total duration to send all data. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The backlog argument of the *socket.listen()* method is now optional. By default it is set to SOMAXCONN or| Complete |
| to 128, whichever is less. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `ssl <https://docs.python.org/3/whatsnew/3.5.html#ssl>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| Memory BIO Support | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| Application-Layer Protocol Negotiation Support | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| There is a new *SSLSocket.version()* method to query the actual protocol version in use. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The SSLSocket class now implements a *SSLSocket.sendfile()* method. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *SSLSocket.send()* method now raises either the *ssl.SSLWantReadError* or *ssl.SSLWantWriteError* | |
| exception on a non-blocking socket if the operation would block. Previously, it would return 0. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *cert_time_to_seconds()* function now interprets the input time as UTC and not as local time, per RFC | |
| 5280. Additionally, the return value is always an int. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| New *SSLObject.shared_ciphers()* and *SSLSocket.shared_ciphers()* methods return the list of ciphers sent | |
| by the client during the handshake. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *SSLSocket.do_handshake()*, *SSLSocket.read()*, *SSLSocket.shutdown()*, and *SSLSocket.write()* | |
| methods of the SSLSocket class no longer reset the socket timeout every time bytes are received or sent. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *match_hostname()* function now supports matching of IP addresses. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `sys <https://docs.python.org/3/whatsnew/3.5.html#sys>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| A new *set_coroutine_wrapper()* function allows setting a global hook that will be called whenever a | |
| coroutine object is created by an async def function. A corresponding *get_coroutine_wrapper()* can be | |
| used to obtain a currently set wrapper. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| A new *is_finalizing()* function can be used to check if the Python interpreter is shutting down. | |
+-----------------------------------------------------------------------------------------------------------+---------------+
| `time <https://docs.python.org/3/whatsnew/3.5.html#time>`_ |
+-----------------------------------------------------------------------------------------------------------+---------------+
| The *monotonic()* function is now always available | |
+-----------------------------------------------------------------------------------------------------------+---------------+
.. rubric:: Notes
.. [#fth] The MicroPython parser correct ignores all type hints. However, the ``typing`` module is not built-in.

103
docs/differences/python_36.rst
View File

@ -5,53 +5,59 @@ Python 3.6
Python 3.6 beta 1 was released on 12 Sep 2016, and a summary of the new features can be found here:
+-----------------------------------------------------------------------------------------------------------+--------------+
| **New Syntax Features:** | **Status** |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| `PEP 498 <https://www.python.org/dev/peps/pep-0498/>`_ | Literal String Formatting | |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| `PEP 515 <https://www.python.org/dev/peps/pep-0515/>`_ | Underscores in Numeric Literals | |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| `PEP 525 <https://www.python.org/dev/peps/pep-0525/>`_ | Asynchronous Generators | |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_ | Syntax for Variable Annotations (provisional) | |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| `PEP 530 <https://www.python.org/dev/peps/pep-0530/>`_ | Asynchronous Comprehensions | |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| **New Built-in Features:** |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| `PEP 468 <https://www.python.org/dev/peps/pep-0468/>`_ | Preserving the order of *kwargs* in a function | |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| `PEP 487 <https://www.python.org/dev/peps/pep-0487/>`_ | Simpler customization of class creation | |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| `PEP 520 <https://www.python.org/dev/peps/pep-0520/>`_ | Preserving Class Attribute Definition Order | |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| **Standard Library Changes:** |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| `PEP 495 <https://www.python.org/dev/peps/pep-0495/>`_ | Local Time Disambiguation | |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| `PEP 506 <https://www.python.org/dev/peps/pep-0506/>`_ | Adding A Secrets Module To The Standard Library | |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| `PEP 519 <https://www.python.org/dev/peps/pep-0519/>`_ | Adding a file system path protocol | |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| **CPython internals:** |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| `PEP 509 <https://www.python.org/dev/peps/pep-0509/>`_ | Add a private version to dict | |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| `PEP 523 <https://www.python.org/dev/peps/pep-0523/>`_ | Adding a frame evaluation API to CPython | |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| **Linux/Window Changes** |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| `PEP 524 <https://www.python.org/dev/peps/pep-0524/>`_ | Make os.urandom() blocking on Linux | |
| | (during system startup) | |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| `PEP 528 <https://www.python.org/dev/peps/pep-0528/>`_ | Change Windows console encoding to UTF-8 | |
+--------------------------------------------------------+--------------------------------------------------+--------------+
| `PEP 529 <https://www.python.org/dev/peps/pep-0529/>`_ | Change Windows filesystem encoding to UTF-8 | |
+--------------------------------------------------------+--------------------------------------------------+--------------+
.. table::
:widths: 30 50 20
+-----------------------------------------------------------------------------------------------------------+-----------------+
| **New Syntax Features** | **Status** |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 498 <https://www.python.org/dev/peps/pep-0498/>`_ | Literal String Formatting | Complete |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 515 <https://www.python.org/dev/peps/pep-0515/>`_ | Underscores in Numeric Literals | Complete |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 525 <https://www.python.org/dev/peps/pep-0525/>`_ | Asynchronous Generators | |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 526 <https://www.python.org/dev/peps/pep-0526/>`_ | Syntax for Variable Annotations (provisional) | Complete |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 530 <https://www.python.org/dev/peps/pep-0530/>`_ | Asynchronous Comprehensions | |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| **New Built-in Features** |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 468 <https://www.python.org/dev/peps/pep-0468/>`_ | Preserving the order of *kwargs* in a function | |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 487 <https://www.python.org/dev/peps/pep-0487/>`_ | Simpler customization of class creation | |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 520 <https://www.python.org/dev/peps/pep-0520/>`_ | Preserving Class Attribute Definition Order | |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| **Standard Library Changes** |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 495 <https://www.python.org/dev/peps/pep-0495/>`_ | Local Time Disambiguation | |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 506 <https://www.python.org/dev/peps/pep-0506/>`_ | Adding A Secrets Module To The Standard Library | |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 519 <https://www.python.org/dev/peps/pep-0519/>`_ | Adding a file system path protocol | |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| **CPython Internals** |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 509 <https://www.python.org/dev/peps/pep-0509/>`_ | Add a private version to dict | Won't do |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 523 <https://www.python.org/dev/peps/pep-0523/>`_ | Adding a frame evaluation API to CPython | |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| **Linux/Window Changes** |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 524 <https://www.python.org/dev/peps/pep-0524/>`_ | Make ``os.urandom()`` blocking on Linux | |
| | (during system startup) | |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 528 <https://www.python.org/dev/peps/pep-0528/>`_ | Change Windows console encoding to UTF-8 | |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
| `PEP 529 <https://www.python.org/dev/peps/pep-0529/>`_ | Change Windows filesystem encoding to UTF-8 | |
+--------------------------------------------------------+--------------------------------------------------+-----------------+
Other Language Changes:
.. table::
:widths: 90 10
+-------------------------------------------------------------------------------------------------------------+---------------+
| A *global* or *nonlocal* statement must now textually appear before the first use of the affected name in | |
| the same scope. Previously this was a SyntaxWarning. | |
@ -71,6 +77,9 @@ Other Language Changes:
Changes to built-in modules:
.. table::
:widths: 90 10
+--------------------------------------------------------------------------------------------------------------+----------------+
| `array <https://docs.python.org/3.6/whatsnew/3.6.html#array>`_ | |
+--------------------------------------------------------------------------------------------------------------+----------------+
@ -78,7 +87,7 @@ Changes to built-in modules:
+--------------------------------------------------------------------------------------------------------------+----------------+
| `binascii <https://docs.python.org/3.6/whatsnew/3.6.html#binascii>`_ | |
+--------------------------------------------------------------------------------------------------------------+----------------+
| The b2a_base64() function now accepts an optional newline keyword argument to control whether the newline | Completed |
| The b2a_base64() function now accepts an optional newline keyword argument to control whether the newline | Complete |
| character is appended to the return value | |
+--------------------------------------------------------------------------------------------------------------+----------------+
| `cmath <https://docs.python.org/3.6/whatsnew/3.6.html#cmath>`_ | |
@ -121,7 +130,7 @@ Changes to built-in modules:
+--------------------------------------------------------------------------------------------------------------+----------------+
| `math <https://docs.python.org/3.6/whatsnew/3.6.html#math>`_ |
+--------------------------------------------------------------------------------------------------------------+----------------+
| The new math.tau (τ) constant has been added | Completed |
| The new math.tau (τ) constant has been added | Complete |
+--------------------------------------------------------------------------------------------------------------+----------------+
| `os <https://docs.python.org/3.6/whatsnew/3.6.html#os>`_ |
+--------------------------------------------------------------------------------------------------------------+----------------+
@ -136,7 +145,7 @@ Changes to built-in modules:
| `re <https://docs.python.org/3.6/whatsnew/3.6.html#re>`_ |
+--------------------------------------------------------------------------------------------------------------+----------------+
| Added support of modifier spans in regular expressions. Examples: *'(?i:p)ython'* matches 'python' and | |
| 'Python', but not 'PYTHON'; *'(?i)g(?-i:v)r'* matches *'GvR'* and *'gvr'*, but not *'GVR'* . | |
| 'Python', but not 'PYTHON'; *'(?i)g(?-i:v)r'* matches *'GvR'* and *'gvr'*, but not *'GVR'*. | |
+--------------------------------------------------------------------------------------------------------------+----------------+
| Match object groups can be accessed by *__getitem__*, which is equivalent to *group()*. So *mo['name']* is | |
| now equivalent to *mo.group('name')*. | |

127
docs/differences/python_37.rst
View File

@ -5,72 +5,81 @@ Python 3.7
New Features:
+--------------------------------------------------------+--------------------------------------------------+----------------+
| **Features:** | **Status** |
+--------------------------------------------------------+--------------------------------------------------+----------------+
| `PEP 538 <https://www.python.org/dev/peps/pep-0538/>`_ | Coercing the legacy C locale to a UTF-8 based | |
| | locale | |
+--------------------------------------------------------+--------------------------------------------------+----------------+
| `PEP 539 <https://www.python.org/dev/peps/pep-0539/>`_ | A New C-API for Thread-Local Storage in CPython | |
+--------------------------------------------------------+--------------------------------------------------+----------------+
| `PEP 540 <https://www.python.org/dev/peps/pep-0540/>`_ | UTF-8 mode | |
+--------------------------------------------------------+--------------------------------------------------+----------------+
| `PEP 552 <https://www.python.org/dev/peps/pep-0552/>`_ | Deterministic pyc | |
+--------------------------------------------------------+--------------------------------------------------+----------------+
| `PEP 553 <https://www.python.org/dev/peps/pep-0553/>`_ | Built-in breakpoint() | |
+--------------------------------------------------------+--------------------------------------------------+----------------+
| `PEP 557 <https://www.python.org/dev/peps/pep-0557/>`_ | Data Classes | |
+--------------------------------------------------------+--------------------------------------------------+----------------+
| `PEP 560 <https://www.python.org/dev/peps/pep-0560/>`_ | Core support for typing module and generic types | |
+--------------------------------------------------------+--------------------------------------------------+----------------+
| `PEP 562 <https://www.python.org/dev/peps/pep-0562/>`_ | Module __getattr__ and __dir__ | Partially done |
+--------------------------------------------------------+--------------------------------------------------+----------------+
| `PEP 563 <https://www.python.org/dev/peps/pep-0563/>`_ | Postponed Evaluation of Annotations | |
+--------------------------------------------------------+--------------------------------------------------+----------------+
| `PEP 564 <https://www.python.org/dev/peps/pep-0564/>`_ | Time functions with nanosecond resolution | |
+--------------------------------------------------------+--------------------------------------------------+----------------+
| `PEP 565 <https://www.python.org/dev/peps/pep-0565/>`_ | Show DeprecationWarning in __main__ | |
+--------------------------------------------------------+--------------------------------------------------+----------------+
| `PEP 567 <https://www.python.org/dev/peps/pep-0567/>`_ | Context Variables | |
+--------------------------------------------------------+--------------------------------------------------+----------------+
.. table::
:widths: 20 60 20
+--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
| **Feature** | **Status** |
+--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
| `PEP 538 <https://www.python.org/dev/peps/pep-0538/>`_ | Coercing the legacy C locale to a UTF-8 based | |
| | locale | |
+--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
| `PEP 539 <https://www.python.org/dev/peps/pep-0539/>`_ | A New C-API for Thread-Local Storage in CPython | |
+--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
| `PEP 540 <https://www.python.org/dev/peps/pep-0540/>`_ | UTF-8 mode | |
+--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
| `PEP 552 <https://www.python.org/dev/peps/pep-0552/>`_ | Deterministic pyc | |
+--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
| `PEP 553 <https://www.python.org/dev/peps/pep-0553/>`_ | Built-in ``breakpoint()`` | |
+--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
| `PEP 557 <https://www.python.org/dev/peps/pep-0557/>`_ | Data Classes | |
+--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
| `PEP 560 <https://www.python.org/dev/peps/pep-0560/>`_ | Core support for typing module and generic types | |
+--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
| `PEP 562 <https://www.python.org/dev/peps/pep-0562/>`_ | Module ``__getattr__`` and ``__dir__`` | Partial |
+--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
| `PEP 563 <https://www.python.org/dev/peps/pep-0563/>`_ | Postponed Evaluation of Annotations | |
+--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
| `PEP 564 <https://www.python.org/dev/peps/pep-0564/>`_ | Time functions with nanosecond resolution | Partial [#ftimenanosec]_ |
+--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
| `PEP 565 <https://www.python.org/dev/peps/pep-0565/>`_ | Show DeprecationWarning in ``__main__`` | |
+--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
| `PEP 567 <https://www.python.org/dev/peps/pep-0567/>`_ | Context Variables | |
+--------------------------------------------------------+--------------------------------------------------+--------------------------------------+
Other Language Changes:
+----------------------------------------------------------------------------------------------------------+----------------+
| async and await are now reserved keywords | Completed |
+----------------------------------------------------------------------------------------------------------+----------------+
| dict objects must preserve insertion-order | |
+----------------------------------------------------------------------------------------------------------+----------------+
| More than 255 arguments can now be passed to a function; a function can now have more than 255 parameters| |
+----------------------------------------------------------------------------------------------------------+----------------+
| bytes.fromhex() and bytearray.fromhex() now ignore all ASCII whitespace, not only spaces | |
+----------------------------------------------------------------------------------------------------------+----------------+
| str, bytes, and bytearray gained support for the new isascii() method, which can be used to test if a | |
| string or bytes contain only the ASCII characters | |
+----------------------------------------------------------------------------------------------------------+----------------+
| ImportError now displays module name and module __file__ path whenfrom ... import ... fails | |
+----------------------------------------------------------------------------------------------------------+----------------+
| Circular imports involving absolute imports with binding a submodule to a name are now supported | |
+----------------------------------------------------------------------------------------------------------+----------------+
| object.__format__(x, '') is now equivalent to str(x) rather than format(str(self), '') | |
+----------------------------------------------------------------------------------------------------------+----------------+
| In order to better support dynamic creation of stack traces, types.TracebackType can now be instantiated | |
| from Python code, and the tb_next attribute on tracebacks is now writable | |
+----------------------------------------------------------------------------------------------------------+----------------+
| When using the -m switch, sys.path[0] is now eagerly expanded to the full starting directory path, rather| |
| than being left as the empty directory (which allows imports from the current working directory at the | |
| time when an import occurs) | |
+----------------------------------------------------------------------------------------------------------+----------------+
| The new -X importtime option or the PYTHONPROFILEIMPORTTIME environment variable can be used to show the | |
| timing of each module import | |
+----------------------------------------------------------------------------------------------------------+----------------+
.. table::
:widths: 90 10
+-----------------------------------------------------------------------------------------------------------------+----------------+
| ``async`` and ``await`` are now reserved keywords | Complete |
+-----------------------------------------------------------------------------------------------------------------+----------------+
| ``dict`` objects must preserve insertion-order | |
+-----------------------------------------------------------------------------------------------------------------+----------------+
| More than 255 arguments can now be passed to a function; a function can now have more than 255 parameters | |
+-----------------------------------------------------------------------------------------------------------------+----------------+
| ``bytes.fromhex()`` and ``bytearray.fromhex()`` now ignore all ASCII whitespace, not only spaces | |
+-----------------------------------------------------------------------------------------------------------------+----------------+
| ``str``, ``bytes``, and ``bytearray`` gained support for the new ``isascii()`` method, which can be used to | |
| test if a string or bytes contain only the ASCII characters | |
+-----------------------------------------------------------------------------------------------------------------+----------------+
| ``ImportError`` now displays module name and module ``__file__`` path when ``from ... import ...`` fails | |
+-----------------------------------------------------------------------------------------------------------------+----------------+
| Circular imports involving absolute imports with binding a submodule to a name are now supported | |
+-----------------------------------------------------------------------------------------------------------------+----------------+
| ``object.__format__(x, '')`` is now equivalent to ``str(x)`` rather than ``format(str(self), '')`` | |
+-----------------------------------------------------------------------------------------------------------------+----------------+
| In order to better support dynamic creation of stack traces, ``types.TracebackType`` can now be | |
| instantiated from Python code, and the ``tb_next`` attribute on tracebacks is now writable | |
+-----------------------------------------------------------------------------------------------------------------+----------------+
| When using the ``-m`` switch, ``sys.path[0]`` is now eagerly expanded to the full starting directory path, | |
| rather than being left as the empty directory (which allows imports from the current working directory | |
| at the time when an import occurs) | |
+-----------------------------------------------------------------------------------------------------------------+----------------+
| The new ``-X importtime`` option or the ``PYTHONPROFILEIMPORTTIME`` environment variable can be used to | |
| show the timing of each module import | |
+-----------------------------------------------------------------------------------------------------------------+----------------+
Changes to built-in modules:
.. table::
:widths: 90 10
+------------------------------------------------------------------------------------------------------------+----------------+
| `asyncio <https://docs.python.org/3/whatsnew/3.7.html#asyncio>`_ | |
+------------------------------------------------------------------------------------------------------------+----------------+
| asyncio (many, may need a separate ticket) | |
| Too many to list | |
+------------------------------------------------------------------------------------------------------------+----------------+
| `gc <https://docs.python.org/3/whatsnew/3.7.html#gc>`_ | |
+------------------------------------------------------------------------------------------------------------+----------------+
@ -93,3 +102,7 @@ Changes to built-in modules:
+------------------------------------------------------------------------------------------------------------+----------------+
| Mostly updates to support nanosecond resolution in PEP564, see above | |
+------------------------------------------------------------------------------------------------------------+----------------+
.. rubric:: Notes
.. [#ftimenanosec] Only :func:`time.time_ns` is implemented.

33
docs/differences/python_38.rst
View File

@ -5,15 +5,18 @@ Python 3.8
Python 3.8.0 (final) was released on the 14 October 2019. The Features for 3.8
are defined in `PEP 569 <https://www.python.org/dev/peps/pep-0569/#id9>`_ and
a detailed description of the changes can be found in What's New in `Python
a detailed description of the changes can be found in `What's New in Python
3.8. <https://docs.python.org/3/whatsnew/3.8.html>`_
.. table::
:widths: 20 60 20
+--------------------------------------------------------+---------------------------------------------------+---------------+
| **Features:** | Status |
| **Features** | **Status** |
+--------------------------------------------------------+---------------------------------------------------+---------------+
| `PEP 570 <https://www.python.org/dev/peps/pep-0570/>`_ | Positional-only arguments | |
+--------------------------------------------------------+---------------------------------------------------+---------------+
| `PEP 572 <https://www.python.org/dev/peps/pep-0572/>`_ | Assignment Expressions | |
| `PEP 572 <https://www.python.org/dev/peps/pep-0572/>`_ | Assignment Expressions | Complete |
+--------------------------------------------------------+---------------------------------------------------+---------------+
| `PEP 574 <https://www.python.org/dev/peps/pep-0574/>`_ | Pickle protocol 5 with out-of-band data | |
+--------------------------------------------------------+---------------------------------------------------+---------------+
@ -25,13 +28,16 @@ a detailed description of the changes can be found in What's New in `Python
+--------------------------------------------------------+---------------------------------------------------+---------------+
| **Miscellaneous** |
+------------------------------------------------------------------------------------------------------------+---------------+
| f-strings support = for self-documenting expressions and debugging | Completed |
| f-strings support = for self-documenting expressions and debugging | Complete |
+------------------------------------------------------------------------------------------------------------+---------------+
Other Language Changes:
.. table::
:widths: 90 10
+------------------------------------------------------------------------------------------------------------+-------------+
| A *continue* statement was illegal in the *finally* clause due to a problem with the implementation. In | Completed |
| A *continue* statement was illegal in the *finally* clause due to a problem with the implementation. In | Complete |
| Python 3.8 this restriction was lifted | |
+------------------------------------------------------------------------------------------------------------+-------------+
| The *bool*, *int* , and *fractions.Fraction* types now have an *as_integer_ratio()* method like that found | |
@ -72,14 +78,17 @@ Other Language Changes:
Changes to built-in modules:
.. table::
:widths: 90 10
+------------------------------------------------------------------------------------------------------------+-------------+
| `asyncio` |
| `asyncio <https://docs.python.org/3/whatsnew/3.8.html#asyncio>`_ |
+------------------------------------------------------------------------------------------------------------+-------------+
| *asyncio.run()* has graduated from the provisional to stable API | Completed |
| *asyncio.run()* has graduated from the provisional to stable API | Complete |
+------------------------------------------------------------------------------------------------------------+-------------+
| Running *python -m asyncio* launches a natively async REPL | |
+------------------------------------------------------------------------------------------------------------+-------------+
| The exception *asyncio.CancelledError* now inherits from *BaseException* rather than *Exception* and no | Completed |
| The exception *asyncio.CancelledError* now inherits from *BaseException* rather than *Exception* and no | Complete |
| longer inherits from *concurrent.futures.CancelledError* | |
+------------------------------------------------------------------------------------------------------------+-------------+
| Added *asyncio.Task.get_coro()* for getting the wrapped coroutine within an *asyncio.Task* | |
@ -90,12 +99,12 @@ Changes to built-in modules:
| Added support for Happy Eyeballs to *asyncio.loop.create_connection()*. To specify the behavior, two new | |
| parameters have been added: *happy_eyeballs_delay* and interleave. | |
+------------------------------------------------------------------------------------------------------------+-------------+
| `gc` |
| `gc <https://docs.python.org/3/whatsnew/3.8.html#gc>`_ |
+------------------------------------------------------------------------------------------------------------+-------------+
| *get_objects()* can now receive an optional generation parameter indicating a generation to get objects | |
| from. (Note, though, that while *gc* is a built-in, *get_objects()* is not implemented for MicroPython) | |
+------------------------------------------------------------------------------------------------------------+-------------+
| `math` |
| `math <https://docs.python.org/3/whatsnew/3.8.html#math>`_ |
+------------------------------------------------------------------------------------------------------------+-------------+
| Added new function *math.dist()* for computing Euclidean distance between two points | |
+------------------------------------------------------------------------------------------------------------+-------------+
@ -109,9 +118,9 @@ Changes to built-in modules:
| Added a new function *math.isqrt()* for computing accurate integer square roots without conversion to | |
| floating point | |
+------------------------------------------------------------------------------------------------------------+-------------+
| The function *math.factorial()* no longer accepts arguments that are not int-like | Completed |
| The function *math.factorial()* no longer accepts arguments that are not int-like | Complete |
+------------------------------------------------------------------------------------------------------------+-------------+
| `sys` |
| `sys <https://docs.python.org/3/whatsnew/3.8.html#sys>`_ |
+------------------------------------------------------------------------------------------------------------+-------------+
| Add new *sys.unraisablehook()* function which can be overridden to control how "unraisable exceptions" | |
| are handled | |

79
docs/differences/python_39.rst
View File

@ -8,35 +8,41 @@ defined in `PEP 596 <https://www.python.org/dev/peps/pep-0596/#features-for-3-9>
and a detailed description of the changes can be found in
`What's New in Python 3.9 <https://docs.python.org/3/whatsnew/3.9.html>`_
+--------------------------------------------------------+----------------------------------------------------+--------------+
| **Features:** | | **Status** |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 573 <https://www.python.org/dev/peps/pep-0573/>`_ | fast access to module state from methods of C | |
| | extension types | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 584 <https://www.python.org/dev/peps/pep-0584/>`_ | union operators added to dict | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 585 <https://www.python.org/dev/peps/pep-0584/>`_ | type hinting generics in standard collections | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 593 <https://www.python.org/dev/peps/pep-0593/>`_ | flexible function and variable annotations | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 602 <https://www.python.org/dev/peps/pep-0602/>`_ | CPython adopts an annual release cycle. Instead of | |
| | annual, aiming for two month release cycle | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 614 <https://www.python.org/dev/peps/pep-0614/>`_ | relaxed grammar restrictions on decorators | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 615 <https://www.python.org/dev/peps/pep-0615/>`_ | the IANA Time Zone Database is now present in the | |
| | standard library in the zoneinfo module | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 616 <https://www.python.org/dev/peps/pep-0616/>`_ | string methods to remove prefixes and suffixes | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
| `PEP 617 <https://www.python.org/dev/peps/pep-0617/>`_ | CPython now uses a new parser based on PEG | |
+--------------------------------------------------------+----------------------------------------------------+--------------+
.. table::
:widths: 20 60 20
+--------------------------------------------------------+----------------------------------------------------+----------------------+
| **Features** | | **Status** |
+--------------------------------------------------------+----------------------------------------------------+----------------------+
| `PEP 573 <https://www.python.org/dev/peps/pep-0573/>`_ | Fast access to module state from methods of C | Not relevant |
| | extension types | |
+--------------------------------------------------------+----------------------------------------------------+----------------------+
| `PEP 584 <https://www.python.org/dev/peps/pep-0584/>`_ | Union operators added to dict | Complete [#pep584]_ |
+--------------------------------------------------------+----------------------------------------------------+----------------------+
| `PEP 585 <https://www.python.org/dev/peps/pep-0584/>`_ | Type hinting generics in standard collections | |
+--------------------------------------------------------+----------------------------------------------------+----------------------+
| `PEP 593 <https://www.python.org/dev/peps/pep-0593/>`_ | Flexible function and variable annotations | |
+--------------------------------------------------------+----------------------------------------------------+----------------------+
| `PEP 602 <https://www.python.org/dev/peps/pep-0602/>`_ | CPython adopts an annual release cycle. Instead of | Not relevant |
| | annual, aiming for two month release cycle | |
+--------------------------------------------------------+----------------------------------------------------+----------------------+
| `PEP 614 <https://www.python.org/dev/peps/pep-0614/>`_ | Relaxed grammar restrictions on decorators | |
+--------------------------------------------------------+----------------------------------------------------+----------------------+
| `PEP 615 <https://www.python.org/dev/peps/pep-0615/>`_ | The IANA Time Zone Database is now present in the | |
| | standard library in the zoneinfo module | |
+--------------------------------------------------------+----------------------------------------------------+----------------------+
| `PEP 616 <https://www.python.org/dev/peps/pep-0616/>`_ | String methods to remove prefixes and suffixes | |
+--------------------------------------------------------+----------------------------------------------------+----------------------+
| `PEP 617 <https://www.python.org/dev/peps/pep-0617/>`_ | CPython now uses a new parser based on PEG | Not relevant |
+--------------------------------------------------------+----------------------------------------------------+----------------------+
Other Language Changes:
.. table::
:widths: 90 10
+-------------------------------------------------------------------------------------------------------------+---------------+
| *__import__()* now raises *ImportError* instead of *ValueError* | Completed |
| *__import__()* now raises *ImportError* instead of *ValueError* | Complete |
+-------------------------------------------------------------------------------------------------------------+---------------+
| Python now gets the absolute path of the script filename specified on the command line (ex: *python3* | |
| *script.py*): the *__file__* attribute of the *__main__* module became an absolute path, rather than a | |
@ -62,8 +68,11 @@ Other Language Changes:
Changes to built-in modules:
.. table::
:widths: 90 10
+---------------------------------------------------------------------------------------------------------------+---------------+
| `asyncio` |
| `asyncio <https://docs.python.org/3/whatsnew/3.9.html#asyncio>`_ |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Due to significant security concerns, the reuse_address parameter of *asyncio.loop.create_datagram_endpoint()*| |
| is no longer supported | |
@ -82,13 +91,13 @@ Changes to built-in modules:
+---------------------------------------------------------------------------------------------------------------+---------------+
| *asyncio* now raises *TyperError* when calling incompatible methods with an *ssl.SSLSocket* socket | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| `gc` |
| `gc <https://docs.python.org/3/whatsnew/3.9.html#gc>`_ |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Garbage collection does not block on resurrected objects | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Added a new function *gc.is_finalized()* to check if an object has been finalized by the garbage collector | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| `math` |
| `math <https://docs.python.org/3/whatsnew/3.9.html#math>`_ |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Expanded the *math.gcd()* function to handle multiple arguments. Formerly, it only supported two arguments | |
+---------------------------------------------------------------------------------------------------------------+---------------+
@ -98,24 +107,28 @@ Changes to built-in modules:
+---------------------------------------------------------------------------------------------------------------+---------------+
| Added *math.ulp()*: return the value of the least significant bit of a float | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| `os` |
| `os <https://docs.python.org/3/whatsnew/3.9.html#os>`_ |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Exposed the Linux-specific *os.pidfd_open()* and *os.P_PIDFD* | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| The *os.unsetenv()* function is now also available on Windows | Completed |
| The *os.unsetenv()* function is now also available on Windows | Complete |
+---------------------------------------------------------------------------------------------------------------+---------------+
| The *os.putenv()* and *os.unsetenv()* functions are now always available | Completed |
| The *os.putenv()* and *os.unsetenv()* functions are now always available | Complete |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Added *os.waitstatus_to_exitcode()* function: convert a wait status to an exit code | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| `random` |
| `random <https://docs.python.org/3/whatsnew/3.9.html#random>`_ |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Added a new *random.Random.randbytes* method: generate random bytes | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| `sys` |
| `sys <https://docs.python.org/3/whatsnew/3.9.html#sys>`_ |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Added a new *sys.platlibdir* attribute: name of the platform-specific library directory | |
+---------------------------------------------------------------------------------------------------------------+---------------+
| Previously, *sys.stderr* was block-buffered when non-interactive. Now stderr defaults to always being | |
| line-buffered | |
+---------------------------------------------------------------------------------------------------------------+---------------+
.. rubric:: Notes
.. [#pep584] PEP 584 ``dict`` union operator is only available on MicroPython builds with ``MICROPY_CPYTHON_COMPAT`` enabled.

79
docs/esp32/quickref.rst
View File

@ -68,6 +68,9 @@ by reading the temperature sensor immediately after waking up from sleep.
Networking
----------
WLAN
^^^^
The :mod:`network` module::
import network
@ -76,12 +79,12 @@ The :mod:`network` module::
wlan.active(True) # activate the interface
wlan.scan() # scan for access points
wlan.isconnected() # check if the station is connected to an AP
wlan.connect('essid', 'password') # connect to an AP
wlan.connect('ssid', 'key') # connect to an AP
wlan.config('mac') # get the interface's MAC address
wlan.ifconfig() # get the interface's IP/netmask/gw/DNS addresses
ap = network.WLAN(network.AP_IF) # create access-point interface
ap.config(essid='ESP-AP') # set the ESSID of the access point
ap.config(ssid='ESP-AP') # set the SSID of the access point
ap.config(max_clients=10) # set how many clients can connect to the network
ap.active(True) # activate the interface
@ -93,7 +96,7 @@ A useful function for connecting to your local WiFi network is::
wlan.active(True)
if not wlan.isconnected():
print('connecting to network...')
wlan.connect('essid', 'password')
wlan.connect('ssid', 'key')
while not wlan.isconnected():
pass
print('network config:', wlan.ifconfig())
@ -110,6 +113,67 @@ calling ``wlan.config(reconnects=n)``, where n are the number of desired reconne
attempts (0 means it won't retry, -1 will restore the default behaviour of trying
to reconnect forever).
LAN
^^^
To use the wired interfaces one has to specify the pins and mode ::
import network
lan = network.LAN(mdc=PIN_MDC, ...) # Set the pin and mode configuration
lan.active(True) # activate the interface
lan.ifconfig() # get the interface's IP/netmask/gw/DNS addresses
The keyword arguments for the constructor defining the PHY type and interface are:
- mdc=pin-object # set the mdc and mdio pins.
- mdio=pin-object
- power=pin-object # set the pin which switches the power of the PHY device.
- phy_type=<type> # Select the PHY device type. Supported devices are PHY_LAN8710,
PHY_LAN8720, PH_IP101, PHY_RTL8201, PHY_DP83848 and PHY_KSZ8041
- phy_addr=number # The address number of the PHY device.
- ref_clk_mode=mode # Defines, whether the ref_clk at the ESP32 is an input
or output. Suitable values are Pin.IN and Pin.OUT.
- ref_clk=pin-object # defines the Pin used for ref_clk.
The options ref_clk_mode and ref_clk require at least esp-idf version 4.4. For
earlier esp-idf versions, these parameters must be defined by kconfig board options.
These are working configurations for LAN interfaces of popular boards::
# Olimex ESP32-GATEWAY: power controlled by Pin(5)
# Olimex ESP32 PoE and ESP32-PoE ISO: power controlled by Pin(12)
lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18), power=machine.Pin(5),
phy_type=network.PHY_LAN8720, phy_addr=0)
# or with dynamic ref_clk pin configuration
lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18), power=machine.Pin(5),
phy_type=network.PHY_LAN8720, phy_addr=0,
ref_clk=machine.Pin(17), ref_clk_mode=machine.Pin.OUT)
# Wireless-Tag's WT32-ETH01
lan = network.LAN(mdc=machine.Pin(23), mdio=machine.Pin(18),
phy_type=network.PHY_LAN8720, phy_addr=1, power=None)
# Espressif ESP32-Ethernet-Kit_A_V1.2
lan = network.LAN(id=0, mdc=Pin(23), mdio=Pin(18), power=Pin(5),
phy_type=network.PHY_IP101, phy_addr=1)
A suitable definition of the PHY interface in a sdkconfig.board file is::
CONFIG_ETH_PHY_INTERFACE_RMII=y
CONFIG_ETH_RMII_CLK_OUTPUT=y
CONFIG_ETH_RMII_CLK_OUT_GPIO=17
CONFIG_LWIP_LOCAL_HOSTNAME="ESP32_POE"
The value assigned to CONFIG_ETH_RMII_CLK_OUT_GPIO may vary depending on the
board's wiring.
Delay and timing
----------------
@ -216,9 +280,10 @@ They each have default GPIO assigned to them, however depending on your
ESP32 variant and board, these pins may conflict with embedded flash,
onboard PSRAM or peripherals.
Any GPIO can be used for hardware UARTs using the GPIO matrix, so to avoid
conflicts simply provide ``tx`` and ``rx`` pins when constructing. The default
pins listed below.
Any GPIO can be used for hardware UARTs using the GPIO matrix, except for
input-only pins 34-39 that can be used as ``rx``. To avoid conflicts simply
provide ``tx`` and ``rx`` pins when constructing. The default pins listed
below.
===== ===== ===== =====
\ UART0 UART1 UART2
@ -589,7 +654,7 @@ See :ref:`machine.SDCard <machine.SDCard>`. ::
# Slot 2 uses pins sck=18, cs=5, miso=19, mosi=23
sd = machine.SDCard(slot=2)
os.mount(sd, "/sd") # mount
os.mount(sd, '/sd') # mount
os.listdir('/sd') # list directory contents

6
docs/esp8266/quickref.rst
View File

@ -57,13 +57,13 @@ The :mod:`network` module::
wlan.active(True) # activate the interface
wlan.scan() # scan for access points
wlan.isconnected() # check if the station is connected to an AP
wlan.connect('essid', 'password') # connect to an AP
wlan.connect('ssid', 'key') # connect to an AP
wlan.config('mac') # get the interface's MAC address
wlan.ifconfig() # get the interface's IP/netmask/gw/DNS addresses
ap = network.WLAN(network.AP_IF) # create access-point interface
ap.active(True) # activate the interface
ap.config(essid='ESP-AP') # set the ESSID of the access point
ap.config(ssid='ESP-AP') # set the SSID of the access point
A useful function for connecting to your local WiFi network is::
@ -73,7 +73,7 @@ A useful function for connecting to your local WiFi network is::
wlan.active(True)
if not wlan.isconnected():
print('connecting to network...')
wlan.connect('essid', 'password')
wlan.connect('ssid', 'key')
while not wlan.isconnected():
pass
print('network config:', wlan.ifconfig())

2
docs/esp8266/tutorial/intro.rst
View File

@ -23,7 +23,7 @@ convertor to make the UART available to your PC.
The minimum requirement for flash size is 1Mbyte. There is also a special
build for boards with 512KB, but it is highly limited comparing to the
normal build: there is no support for filesystem, and thus features which
depend on it won't work (WebREPL, upip, etc.). As such, 512KB build will
depend on it won't work (WebREPL, mip, etc.). As such, 512KB build will
be more interesting for users who build from source and fine-tune parameters
for their particular application.

4
docs/esp8266/tutorial/network_basics.rst
View File

@ -37,7 +37,7 @@ First activate the station interface::
Then connect to your WiFi network::
>>> sta_if.connect('<your ESSID>', '<your password>')
>>> sta_if.connect('<your SSID>', '<your key>')
To check if the connection is established use::
@ -61,7 +61,7 @@ connect to your WiFi network::
if not sta_if.isconnected():
print('connecting to network...')
sta_if.active(True)
sta_if.connect('<essid>', '<password>')
sta_if.connect('<ssid>', '<key>')
while not sta_if.isconnected():
pass
print('network config:', sta_if.ifconfig())

1
docs/index.rst
View File

@ -17,3 +17,4 @@ MicroPython documentation and references
unix/quickref.rst
zephyr/quickref.rst
renesas-ra/quickref.rst
samd/quickref.rst

52
docs/library/array.rst
View File

@ -27,3 +27,55 @@ Classes
Append new elements as contained in *iterable* to the end of
array, growing it.
.. method:: __getitem__(index)
Indexed read of the array, called as ``a[index]`` (where ``a`` is an ``array``).
Returns a value if *index* is an ``int`` and an ``array`` if *index* is a slice.
Negative indices count from the end and ``IndexError`` is thrown if the index is
out of range.
**Note:** ``__getitem__`` cannot be called directly (``a.__getitem__(index)`` fails) and
is not present in ``__dict__``, however ``a[index]`` does work.
.. method:: __setitem__(index, value)
Indexed write into the array, called as ``a[index] = value`` (where ``a`` is an ``array``).
``value`` is a single value if *index* is an ``int`` and an ``array`` if *index* is a slice.
Negative indices count from the end and ``IndexError`` is thrown if the index is out of range.
**Note:** ``__setitem__`` cannot be called directly (``a.__setitem__(index, value)`` fails) and
is not present in ``__dict__``, however ``a[index] = value`` does work.
.. method:: __len__()
Returns the number of items in the array, called as ``len(a)`` (where ``a`` is an ``array``).
**Note:** ``__len__`` cannot be called directly (``a.__len__()`` fails) and the
method is not present in ``__dict__``, however ``len(a)`` does work.
.. method:: __add__(other)
Return a new ``array`` that is the concatenation of the array with *other*, called as
``a + other`` (where ``a`` and *other* are both ``arrays``).
**Note:** ``__add__`` cannot be called directly (``a.__add__(other)`` fails) and
is not present in ``__dict__``, however ``a + other`` does work.
.. method:: __iadd__(other)
Concatenates the array with *other* in-place, called as ``a += other`` (where ``a`` and *other*
are both ``arrays``). Equivalent to ``extend(other)``.
**Note:** ``__iadd__`` cannot be called directly (``a.__iadd__(other)`` fails) and
is not present in ``__dict__``, however ``a += other`` does work.
.. method:: __repr__()
Returns the string representation of the array, called as ``str(a)`` or ``repr(a)```
(where ``a`` is an ``array``). Returns the string ``"array(<type>, [<elements>])"``,
where ``<type>`` is the type code letter for the array and ``<elements>`` is a comma
seperated list of the elements of the array.
**Note:** ``__repr__`` cannot be called directly (``a.__repr__()`` fails) and
is not present in ``__dict__``, however ``str(a)`` and ``repr(a)`` both work.

26
docs/library/bluetooth.rst
View File

@ -13,6 +13,9 @@ concurrently. Pairing (and bonding) is supported on some ports.
This API is intended to match the low-level Bluetooth protocol and provide
building-blocks for higher-level abstractions such as specific device types.
.. note:: For most applications, we recommend using the higher-level
`aioble library <https://github.com/micropython/micropython-lib/tree/master/micropython/bluetooth/aioble>`_.
.. note:: This module is still under development and its classes, functions,
methods and constants are subject to change.
@ -163,7 +166,7 @@ Event Handling
conn_handle, status = data
elif event == _IRQ_GATTC_CHARACTERISTIC_RESULT:
# Called for each characteristic found by gattc_discover_services().
conn_handle, def_handle, value_handle, properties, uuid = data
conn_handle, end_handle, value_handle, properties, uuid = data
elif event == _IRQ_GATTC_CHARACTERISTIC_DONE:
# Called once service discovery is complete.
# Note: Status will be zero on success, implementation-specific value otherwise.
@ -180,12 +183,10 @@ Event Handling
conn_handle, value_handle, char_data = data
elif event == _IRQ_GATTC_READ_DONE:
# A gattc_read() has completed.
# Note: The value_handle will be zero on btstack (but present on NimBLE).
# Note: Status will be zero on success, implementation-specific value otherwise.
conn_handle, value_handle, status = data
elif event == _IRQ_GATTC_WRITE_DONE:
# A gattc_write() has completed.
# Note: The value_handle will be zero on btstack (but present on NimBLE).
# Note: Status will be zero on success, implementation-specific value otherwise.
conn_handle, value_handle, status = data
elif event == _IRQ_GATTC_NOTIFY:
@ -511,19 +512,24 @@ writes from a client to a given characteristic, use
Sends a notification request to a connected client.
If *data* is not ``None``, then that value is sent to the client as part of
the notification. The local value will not be modified.
If *data* is ``None`` (the default), then the current local value (as set
with :meth:`gatts_write <BLE.gatts_write>`) will be sent.
Otherwise, if *data* is ``None``, then the current local value (as
set with :meth:`gatts_write <BLE.gatts_write>`) will be sent.
Otherwise, if *data* is not ``None``, then that value is sent to the client
as part of the notification. The local value will not be modified.
**Note:** The notification will be sent regardless of the subscription
status of the client to this characteristic.
.. method:: BLE.gatts_indicate(conn_handle, value_handle, /)
.. method:: BLE.gatts_indicate(conn_handle, value_handle, data=None, /)
Sends an indication request containing the characteristic's current value to
a connected client.
Sends a indication request to a connected client.
If *data* is ``None`` (the default), then the current local value (as set
with :meth:`gatts_write <BLE.gatts_write>`) will be sent.
Otherwise, if *data* is not ``None``, then that value is sent to the client
as part of the indication. The local value will not be modified.
On acknowledgment (or failure, e.g. timeout), the
``_IRQ_GATTS_INDICATE_DONE`` event will be raised.

5
docs/library/btree.rst
View File

@ -11,8 +11,9 @@ value, a database also supports efficient ordered range scans (retrieval
of values with the keys in a given range). On the application interface
side, BTree database work as close a possible to a way standard `dict`
type works, one notable difference is that both keys and values must
be `bytes` objects (so, if you want to store objects of other types, you
need to serialize them to `bytes` first).
be `bytes`-like objects (so, if you want to store objects of other types, you
need to first serialize them to `str` or `bytes` or another type that supports
the buffer protocol).
The module is based on the well-known BerkelyDB library, version 1.xx.

5
docs/library/esp32.rst
View File

@ -18,6 +18,11 @@ Functions
Configure whether or not a touch will wake the device from sleep.
*wake* should be a boolean value.
.. function:: wake_on_ulp(wake)
Configure whether or not the Ultra-Low-Power co-processor can wake the
device from sleep. *wake* should be a boolean value.
.. function:: wake_on_ext0(pin, level)
Configure how EXT0 wakes the device from sleep. *pin* can be ``None``

43
docs/library/framebuf.rst
View File

@ -11,8 +11,8 @@ class FrameBuffer
-----------------
The FrameBuffer class provides a pixel buffer which can be drawn upon with
pixels, lines, rectangles, text and even other FrameBuffer's. It is useful
when generating output for displays.
pixels, lines, rectangles, ellipses, polygons, text and even other
FrameBuffers. It is useful when generating output for displays.
For example::
@ -77,12 +77,37 @@ The following methods draw shapes onto the FrameBuffer.
methods draw horizontal and vertical lines respectively up to
a given length.
.. method:: FrameBuffer.rect(x, y, w, h, c)
.. method:: FrameBuffer.fill_rect(x, y, w, h, c)
.. method:: FrameBuffer.rect(x, y, w, h, c[, f])
Draw a rectangle at the given location, size and color. The `rect`
method draws only a 1 pixel outline whereas the `fill_rect` method
draws both the outline and interior.
Draw a rectangle at the given location, size and color.
The optional *f* parameter can be set to ``True`` to fill the rectangle.
Otherwise just a one pixel outline is drawn.
.. method:: FrameBuffer.ellipse(x, y, xr, yr, c[, f, m])
Draw an ellipse at the given location. Radii *xr* and *yr* define the
geometry; equal values cause a circle to be drawn. The *c* parameter
defines the color.
The optional *f* parameter can be set to ``True`` to fill the ellipse.
Otherwise just a one pixel outline is drawn.
The optional *m* parameter enables drawing to be restricted to certain
quadrants of the ellipse. The LS four bits determine which quadrants are
to be drawn, with bit 0 specifying Q1, b1 Q2, b2 Q3 and b3 Q4. Quadrants
are numbered counterclockwise with Q1 being top right.
.. method:: FrameBuffer.poly(x, y, coords, c[, f])
Given a list of coordinates, draw an arbitrary (convex or concave) closed
polygon at the given x, y location using the given color.
The *coords* must be specified as a :mod:`array` of integers, e.g.
``array('h', [x0, y0, x1, y1, ... xn, yn])``.
The optional *f* parameter can be set to ``True`` to fill the polygon.
Otherwise just a one pixel outline is drawn.
Drawing text
------------
@ -108,7 +133,9 @@ Other methods
Draw another FrameBuffer on top of the current one at the given coordinates.
If *key* is specified then it should be a color integer and the
corresponding color will be considered transparent: all pixels with that
color value will not be drawn.
color value will not be drawn. (If the *palette* is specified then the *key*
is compared to the value from *palette*, not to the value directly from
*fbuf*.)
The *palette* argument enables blitting between FrameBuffers with differing
formats. Typical usage is to render a monochrome or grayscale glyph/icon to

2
docs/library/index.rst
View File

@ -195,4 +195,4 @@ but also the MicroPython libraries too (e.g. ``machine``, ``bluetooth``, etc).
The main exception is the port-specific libraries (``pyb``, ``esp``, etc).
*Other than when you specifically want to force the use of the built-in module,
we recommend always using ``import module`` rather than ``import umodule``.*
we recommend always using* ``import module`` *rather than* ``import umodule``.

19
docs/library/machine.I2C.rst
View File

@ -20,6 +20,17 @@ Software I2C is implemented by bit-banging and can be used on any pin but is not
as efficient. These classes have the same methods available and differ primarily
in the way they are constructed.
.. Note::
The I2C bus requires pull-up circuitry on both SDA and SCL for it's operation.
Usually these are resistors in the range of 1 - 10 kOhm, connected from each SDA/SCL
to Vcc. Without these, the behaviour is undefined and may range from blocking,
unexpected watchdog reset to just wrong values. Often, this pull-up circuitry
is built-in already to the MCU board or sensor breakout boards, but there is
no rule for that. So please check in case of trouble. See also this excellent
`learning guide <https://learn.adafruit.com/working-with-i2c-devices/pull-up-resistors>`_
by Adafruit about I2C wiring.
Example usage::
from machine import I2C
@ -41,7 +52,7 @@ Example usage::
Constructors
------------
.. class:: I2C(id, *, scl, sda, freq=400000)
.. class:: I2C(id, *, scl, sda, freq=400000, timeout=50000)
Construct and return a new I2C object using the following parameters:
@ -51,6 +62,8 @@ Constructors
- *sda* should be a pin object specifying the pin to use for SDA.
- *freq* should be an integer which sets the maximum frequency
for SCL.
- *timeout* is the maximum time in microseconds to allow for I2C
transactions. This parameter is not allowed on some ports.
Note that some ports/boards will have default values of *scl* and *sda*
that can be changed in this constructor. Others will have fixed values
@ -80,6 +93,10 @@ General Methods
- *sda* is a pin object for the SDA line
- *freq* is the SCL clock rate
In the case of hardware I2C the actual clock frequency may be lower than the
requested frequency. This is dependant on the platform hardware. The actual
rate may be determined by printing the I2C object.
.. method:: I2C.deinit()
Turn off the I2C bus.

10
docs/library/machine.Timer.rst
View File

@ -38,13 +38,16 @@ Constructors
Methods
-------
.. method:: Timer.init(*, mode=Timer.PERIODIC, period=-1, callback=None)
.. method:: Timer.init(*, mode=Timer.PERIODIC, freq=-1, period=-1, callback=None)
Initialise the timer. Example::
def mycallback(t):
pass
# periodic at 1kHz
tim.init(mode=Timer.PERIODIC, freq=1000, callback=mycallback)
# periodic with 100ms period
tim.init(period=100, callback=mycallback)
@ -60,6 +63,11 @@ Methods
- ``Timer.PERIODIC`` - The timer runs periodically at the configured
frequency of the channel.
- ``freq`` - The timer frequency, in units of Hz. The upper bound of
the frequency is dependent on the port. When both the ``freq`` and
``period`` arguments are given, ``freq`` has a higher priority and
``period`` is ignored.
- ``period`` - The timer period, in milliseconds.
- ``callback`` - The callable to call upon expiration of the timer period.

38
docs/library/machine.UART.rst
View File

@ -87,10 +87,22 @@ Methods
When no pins are given, then the default set of TX and RX pins is taken, and hardware
flow control will be disabled. If *pins* is ``None``, no pin assignment will be made.
.. note::
It is possible to call ``init()`` multiple times on the same object in
order to reconfigure UART on the fly. That allows using single UART
peripheral to serve different devices attached to different GPIO pins.
Only one device can be served at a time in that case.
Also do not call ``deinit()`` as it will prevent calling ``init()``
again.
.. method:: UART.deinit()
Turn off the UART bus.
.. note::
You will not be able to call ``init()`` on the object after ``deinit()``.
A new instance needs to be created in that case.
.. method:: UART.any()
Returns an integer counting the number of characters that can be read without
@ -165,6 +177,32 @@ Methods
Availability: WiPy.
.. method:: UART.flush()
Waits until all data has been sent. In case of a timeout, an exception is raised. The timeout
duration depends on the tx buffer size and the baud rate. Unless flow control is enabled, a timeout
should not occur.
.. note::
For the rp2, esp8266 and nrf ports the call returns while the last byte is sent.
If required, a one character wait time has to be added in the calling script.
Availability: rp2, esp32, esp8266, mimxrt, cc3200, stm32, nrf ports, renesas-ra
.. method:: UART.txdone()
Tells whether all data has been sent or no data transfer is happening. In this case,
it returns ``True``. If a data transmission is ongoing it returns ``False``.
.. note::
For the rp2, esp8266 and nrf ports the call may return ``True`` even if the last byte
of a transfer is still being sent. If required, a one character wait time has to be
added in the calling script.
Availability: rp2, esp32, esp8266, mimxrt, cc3200, stm32, nrf ports, renesas-ra
Constants
---------

5
docs/library/machine.WDT.rst
View File

@ -15,7 +15,7 @@ Example usage::
wdt = WDT(timeout=2000) # enable it with a timeout of 2s
wdt.feed()
Availability of this class: pyboard, WiPy, esp8266, esp32.
Availability of this class: pyboard, WiPy, esp8266, esp32, rp2040, mimxrt.
Constructors
------------
@ -26,7 +26,8 @@ Constructors
Once it is running the timeout cannot be changed and the WDT cannot be stopped either.
Notes: On the esp32 the minimum timeout is 1 second. On the esp8266 a timeout
cannot be specified, it is determined by the underlying system.
cannot be specified, it is determined by the underlying system. On rp2040 devices,
the maximum timeout is 8388 ms.
Methods
-------

55
docs/library/machine.rst
View File

@ -19,6 +19,44 @@ This is true for both physical devices with IDs >= 0 and "virtual" devices
with negative IDs like -1 (these "virtual" devices are still thin shims on
top of real hardware and real hardware interrupts). See :ref:`isr_rules`.
Memory access
-------------
The module exposes three objects used for raw memory access.
.. data:: mem8
Read/write 8 bits of memory.
.. data:: mem16
Read/write 16 bits of memory.
.. data:: mem32
Read/write 32 bits of memory.
Use subscript notation ``[...]`` to index these objects with the address of
interest. Note that the address is the byte address, regardless of the size of
memory being accessed.
Example use (registers are specific to an stm32 microcontroller):
.. code-block:: python3
import machine
from micropython import const
GPIOA = const(0x48000000)
GPIO_BSRR = const(0x18)
GPIO_IDR = const(0x10)
# set PA2 high
machine.mem32[GPIOA + GPIO_BSRR] = 1 << 2
# read PA3
value = (machine.mem32[GPIOA + GPIO_IDR] >> 3) & 1
Reset related functions
-----------------------
@ -48,6 +86,23 @@ Reset related functions
Interrupt related functions
---------------------------
The following functions allow control over interrupts. Some systems require
interrupts to operate correctly so disabling them for long periods may
compromise core functionality, for example watchdog timers may trigger
unexpectedly. Interrupts should only be disabled for a minimum amount of time
and then re-enabled to their previous state. For example::
import machine
# Disable interrupts
state = machine.disable_irq()
# Do a small amount of time-critical work here
# Enable interrupts
machine.enable_irq(state)
.. function:: disable_irq()
Disable interrupt requests.

2
docs/library/micropython.rst
View File

@ -9,7 +9,7 @@ Functions
.. function:: const(expr)
Used to declare that the expression is a constant so that the compile can
Used to declare that the expression is a constant so that the compiler can
optimise it. The use of this function should be as follows::
from micropython import const

8
docs/library/neopixel.rst
View File

@ -6,9 +6,11 @@
This module provides a driver for WS2818 / NeoPixel LEDs.
.. note:: This module is only included by default on the ESP8266 and ESP32
ports. On STM32 / Pyboard, you can `download the module
<https://github.com/micropython/micropython/blob/master/drivers/neopixel/neopixel.py>`_
.. note:: This module is only included by default on the ESP8266, ESP32 and RP2
ports. On STM32 / Pyboard and others, you can either install the
``neopixel`` package using :term:`mip`, or you can download the module
directly from
<https://raw.githubusercontent.com/micropython/micropython-lib/master/micropython/drivers/led/neopixel/neopixel.py>`_
and copy it to the filesystem.
class NeoPixel

89
docs/library/network.CC3K.rst
View File

@ -1,89 +0,0 @@
.. currentmodule:: network
.. _network.CC3K:
class CC3K -- control CC3000 WiFi modules
=========================================
This class provides a driver for CC3000 WiFi modules. Example usage::
import network
nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3)
nic.connect('your-ssid', 'your-password')
while not nic.isconnected():
pyb.delay(50)
print(nic.ifconfig())
# now use socket as usual
...
For this example to work the CC3000 module must have the following connections:
- MOSI connected to Y8
- MISO connected to Y7
- CLK connected to Y6
- CS connected to Y5
- VBEN connected to Y4
- IRQ connected to Y3
It is possible to use other SPI buses and other pins for CS, VBEN and IRQ.
Constructors
------------
.. class:: CC3K(spi, pin_cs, pin_en, pin_irq)
Create a CC3K driver object, initialise the CC3000 module using the given SPI bus
and pins, and return the CC3K object.
Arguments are:
- *spi* is an :ref:`SPI object <pyb.SPI>` which is the SPI bus that the CC3000 is
connected to (the MOSI, MISO and CLK pins).
- *pin_cs* is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 CS pin.
- *pin_en* is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 VBEN pin.
- *pin_irq* is a :ref:`Pin object <pyb.Pin>` which is connected to the CC3000 IRQ pin.
All of these objects will be initialised by the driver, so there is no need to
initialise them yourself. For example, you can use::
nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3)
Methods
-------
.. method:: CC3K.connect(ssid, key=None, *, security=WPA2, bssid=None)
Connect to a WiFi access point using the given SSID, and other security
parameters.
.. method:: CC3K.disconnect()
Disconnect from the WiFi access point.
.. method:: CC3K.isconnected()
Returns True if connected to a WiFi access point and has a valid IP address,
False otherwise.
.. method:: CC3K.ifconfig()
Returns a 7-tuple with (ip, subnet mask, gateway, DNS server, DHCP server,
MAC address, SSID).
.. method:: CC3K.patch_version()
Return the version of the patch program (firmware) on the CC3000.
.. method:: CC3K.patch_program('pgm')
Upload the current firmware to the CC3000. You must pass 'pgm' as the first
argument in order for the upload to proceed.
Constants
---------
.. data:: CC3K.WEP
.. data:: CC3K.WPA
.. data:: CC3K.WPA2
security type to use

12
docs/library/network.LAN.rst
View File

@ -19,7 +19,7 @@ Example usage::
Constructors
------------
.. class:: LAN(id, *, phy_type=<board_default>, phy_addr=<board_default>, phy_clock=<board_default>)
.. class:: LAN(id, *, phy_type=<board_default>, phy_addr=<board_default>, ref_clk_mode=<board_default>)
Create a LAN driver object, initialise the LAN module using the given
PHY driver name, and return the LAN object.
@ -31,13 +31,15 @@ Constructors
is the default. Suitable values are port specific.
- *phy_addr* specifies the address of the PHY interface. As with *phy_type*, the hardwired value has
to be used for most boards and that value is the default.
- *phy_clock* specifies, whether the data clock is provided by the Ethernet controller or the PYH interface.
The default value is the one that matches the board. If set to ``True``, the clock is driven by the
Ethernet controller, otherwise by the PHY interface.
- *ref_clk_mode* specifies, whether the data clock is provided by the Ethernet controller or
the PYH interface.
The default value is the one that matches the board. If set to ``LAN.OUT`` or ``Pin.OUT``
or ``True``, the clock is driven by the Ethernet controller, if set to ``LAN.IN``
or ``Pin.IN`` or ``False``, the clock is driven by the PHY interface.
For example, with the Seeed Arch Mix board you can use::
nic = LAN(0, phy_type=LAN.PHY_LAN8720, phy_addr=2, phy_clock=False)
nic = LAN(0, phy_type=LAN.PHY_LAN8720, phy_addr=1, ref_clk_mode=Pin.IN)
Methods
-------

26
docs/library/network.WLAN.rst
View File

@ -10,7 +10,7 @@ This class provides a driver for WiFi network processors. Example usage::
# enable station interface and connect to WiFi access point
nic = network.WLAN(network.STA_IF)
nic.active(True)
nic.connect('your-ssid', 'your-password')
nic.connect('your-ssid', 'your-key')
# now use sockets as usual
Constructors
@ -32,9 +32,9 @@ Methods
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)
.. method:: WLAN.connect(ssid=None, key=None, *, bssid=None)
Connect to the specified wireless network, using the specified password.
Connect to the specified wireless network, using the specified key.
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).
@ -52,12 +52,12 @@ Methods
Scanning is only possible on STA interface. Returns list of tuples with
the information about WiFi access points:
(ssid, bssid, channel, RSSI, authmode, hidden)
(ssid, bssid, channel, RSSI, security, 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:
There are five values for security:
* 0 -- open
* 1 -- WEP
@ -112,10 +112,10 @@ Methods
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)
# Set WiFi access point name (formally known as SSID) and WiFi channel
ap.config(ssid='My AP', channel=11)
# Query params one by one
print(ap.config('essid'))
print(ap.config('ssid'))
print(ap.config('channel'))
Following are commonly supported parameters (availability of a specific parameter
@ -125,12 +125,12 @@ Methods
Parameter Description
============= ===========
mac MAC address (bytes)
essid WiFi access point name (string)
ssid 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
hidden Whether SSID is hidden (boolean)
security Security protocol supported (enumeration, see module constants)
key Access key (string)
hostname The hostname that will be sent to DHCP (STA interfaces) and mDNS (if supported, both STA and AP). (Deprecated, use :func:`network.hostname` instead)
reconnects Number of reconnect attempts to make (integer, 0=none, -1=unlimited)
txpower Maximum transmit power in dBm (integer or float)
============= ===========

40
docs/library/network.rst
View File

@ -89,7 +89,7 @@ parameter should be `id`.
network media, there are different variants of predefined/
recommended tuple formats, among them:
* WiFi: (ssid, bssid, channel, RSSI, authmode, hidden). There
* WiFi: (ssid, bssid, channel, RSSI, security, hidden). There
may be further fields, specific to a particular device.
The function may accept additional keyword arguments to filter scan
@ -133,10 +133,10 @@ parameter should be `id`.
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)
# Set WiFi access point name (formally known as SSID) and WiFi channel
ap.config(ssid='My AP', channel=11)
# Query params one by one
print(ap.config('essid'))
print(ap.config('ssid'))
print(ap.config('channel'))
Specific network class implementations
@ -150,7 +150,6 @@ provide a way to control networking interfaces of various kinds.
network.WLAN.rst
network.WLANWiPy.rst
network.CC3K.rst
network.WIZNET5K.rst
network.LAN.rst
@ -159,12 +158,39 @@ Network functions
The following are functions available in the network module.
.. function:: country([code])
Get or set the two-letter ISO 3166-1 Alpha-2 country code to be used for
radio compliance.
If the *code* parameter is provided, the country will be set to this value.
If the function is called without parameters, it returns the current
country.
The default code ``"XX"`` represents the "worldwide" region.
.. function:: hostname([name])
Get or set the hostname that will identify this device on the network. It is
applied to all interfaces.
This hostname is used for:
* Sending to the DHCP server in the client request. (If using DHCP)
* Broadcasting via mDNS. (If enabled)
If the *name* parameter is provided, the hostname will be set to this value.
If the function is called without parameters, it returns the current
hostname.
The default hostname is typically the name of the board.
.. 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.
If the *mode* parameter is provided, the PHY mode will be set to this value.
If the function is called without parameters, it returns the current PHY
mode.
The possible modes are defined as constants:
* ``MODE_11B`` -- IEEE 802.11b,

2
docs/library/pyb.ADC.rst
View File

@ -23,7 +23,7 @@ Usage::
Constructors
------------
.. class:: pyb.ADC(pin)
.. class:: ADC(pin)
Create an ADC object associated with the given pin.
This allows you to then read analog values on that pin.

2
docs/library/pyb.Accel.rst
View File

@ -16,7 +16,7 @@ Raw values are between -32 and 31.
Constructors
------------
.. class:: pyb.Accel()
.. class:: Accel()
Create and return an accelerometer object.

4
docs/library/pyb.CAN.rst
View File

@ -31,7 +31,7 @@ for both classic and FD CAN controllers, unless otherwise stated.
Constructors
------------
.. class:: pyb.CAN(bus, ...)
.. class:: CAN(bus, ...)
Construct a CAN object on the given bus. *bus* can be 1-2, or ``'YA'`` or ``'YB'``.
With no additional parameters, the CAN object is created but not
@ -252,7 +252,7 @@ Methods
For example::
buf = bytearray(8)
lst = [0, 0, 0, memoryview(buf)]
lst = [0, 0, 0, 0, memoryview(buf)]
# No heap memory is allocated in the following call
can.recv(0, lst)

2
docs/library/pyb.DAC.rst
View File

@ -49,7 +49,7 @@ To output a continuous sine-wave at 12-bit resolution::
Constructors
------------
.. class:: pyb.DAC(port, bits=8, *, buffering=None)
.. class:: DAC(port, bits=8, *, buffering=None)
Construct a new DAC object.

2
docs/library/pyb.ExtInt.rst
View File

@ -51,7 +51,7 @@ usrsw.h for an example of using this.
Constructors
------------
.. class:: pyb.ExtInt(pin, mode, pull, callback)
.. class:: ExtInt(pin, mode, pull, callback)
Create an ExtInt object:

4
docs/library/pyb.Flash.rst
View File

@ -15,7 +15,7 @@ application.
Constructors
------------
.. class:: pyb.Flash()
.. class:: Flash()
Create and return a block device that represents the flash device presented
to the USB mass storage interface.
@ -25,7 +25,7 @@ Constructors
This constructor is deprecated and will be removed in a future version of MicroPython.
.. class:: pyb.Flash(*, start=-1, len=-1)
.. class:: Flash(*, start=-1, len=-1)
:noindex:
Create and return a block device that accesses the flash at the specified offset. The length defaults to the remaining size of the device.

6
docs/library/pyb.I2C.rst
View File

@ -56,7 +56,7 @@ Master also has other methods::
Constructors
------------
.. class:: pyb.I2C(bus, ...)
.. class:: I2C(bus, ...)
Construct an I2C object on the given bus. ``bus`` can be 1 or 2, 'X' or
'Y'. With no additional parameters, the I2C object is created but not
@ -96,6 +96,10 @@ Methods
that DMA transfers have more precise timing but currently do not handle bus
errors properly)
The actual clock frequency may be lower than the requested frequency.
This is dependant on the platform hardware. The actual rate may be determined
by printing the I2C object.
.. method:: I2C.is_ready(addr)
Check if an I2C device responds to the given address. Only valid when in controller mode.

2
docs/library/pyb.LCD.rst
View File

@ -41,7 +41,7 @@ For example, to make a bouncing dot, try::
Constructors
------------
.. class:: pyb.LCD(skin_position)
.. class:: LCD(skin_position)
Construct an LCD object in the given skin position. ``skin_position`` can be 'X' or 'Y', and
should match the position where the LCD pyskin is plugged in.

2
docs/library/pyb.LED.rst
View File

@ -10,7 +10,7 @@ The LED object controls an individual LED (Light Emitting Diode).
Constructors
------------
.. class:: pyb.LED(id)
.. class:: LED(id)
Create an LED object associated with the given LED:

31
docs/library/pyb.Pin.rst
View File

@ -58,23 +58,13 @@ an ordinal pin number:
You can set ``pyb.Pin.debug(True)`` to get some debug information about
how a particular object gets mapped to a pin.
When a pin has the ``Pin.PULL_UP`` or ``Pin.PULL_DOWN`` pull-mode enabled,
that pin has an effective 40k Ohm resistor pulling it to 3V3 or GND
respectively (except pin Y5 which has 11k Ohm resistors).
Now every time a falling edge is seen on the gpio pin, the callback will be
executed. Caution: mechanical push buttons have "bounce" and pushing or
releasing a switch will often generate multiple edges.
See: http://www.eng.utah.edu/~cs5780/debouncing.pdf for a detailed
explanation, along with various techniques for debouncing.
All pin objects go through the pin mapper to come up with one of the
gpio pins.
Constructors
------------
.. class:: pyb.Pin(id, ...)
.. class:: Pin(id, ...)
Create a new Pin object associated with the id. If additional arguments are given,
they are used to initialise the pin. See :meth:`pin.init`.
@ -107,7 +97,8 @@ Methods
- ``Pin.IN`` - configure the pin for input;
- ``Pin.OUT_PP`` - configure the pin for output, with push-pull control;
- ``Pin.OUT_OD`` - configure the pin for output, with open-drain control;
- ``Pin.AF_PP`` - configure the pin for alternate function, pull-pull;
- ``Pin.ALT`` - configure the pin for alternate function, input or output;
- ``Pin.AF_PP`` - configure the pin for alternate function, push-pull;
- ``Pin.AF_OD`` - configure the pin for alternate function, open-drain;
- ``Pin.ANALOG`` - configure the pin for analog.
@ -117,10 +108,14 @@ Methods
- ``Pin.PULL_UP`` - enable the pull-up resistor;
- ``Pin.PULL_DOWN`` - enable the pull-down resistor.
When a pin has the ``Pin.PULL_UP`` or ``Pin.PULL_DOWN`` pull-mode enabled,
that pin has an effective 40k Ohm resistor pulling it to 3V3 or GND
respectively (except pin Y5 which has 11k Ohm resistors).
- *value* if not None will set the port output value before enabling the pin.
- *alt* can be used when mode is ``Pin.AF_PP`` or ``Pin.AF_OD`` to set the
index or name of one of the alternate functions associated with a pin.
- *alt* can be used when mode is ``Pin.ALT`` , ``Pin.AF_PP`` or ``Pin.AF_OD`` to
set the index or name of one of the alternate functions associated with a pin.
This arg was previously called *af* which can still be used if needed.
Returns: ``None``.
@ -183,6 +178,10 @@ Methods
Constants
---------
.. data:: Pin.ALT
initialise the pin to alternate-function mode for input or output
.. data:: Pin.AF_OD
initialise the pin to alternate-function mode with an open-drain drive
@ -243,11 +242,11 @@ control is desired.
To configure X3 to expose TIM2_CH3, you could use::
pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, alt=pyb.Pin.AF1_TIM2)
pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.ALT, alt=pyb.Pin.AF1_TIM2)
or::
pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.AF_PP, alt=1)
pin = pyb.Pin(pyb.Pin.board.X3, mode=pyb.Pin.ALT, alt=1)
Methods
-------

2
docs/library/pyb.RTC.rst
View File

@ -17,7 +17,7 @@ Example usage::
Constructors
------------
.. class:: pyb.RTC()
.. class:: RTC()
Create an RTC object.

2
docs/library/pyb.SPI.rst
View File

@ -28,7 +28,7 @@ Additional methods for SPI::
Constructors
------------
.. class:: pyb.SPI(bus, ...)
.. class:: SPI(bus, ...)
Construct an SPI object on the given bus. ``bus`` can be 1 or 2, or
'X' or 'Y'. With no additional parameters, the SPI object is created but

2
docs/library/pyb.Servo.rst
View File

@ -30,7 +30,7 @@ Example usage::
Constructors
------------
.. class:: pyb.Servo(id)
.. class:: Servo(id)
Create a servo object. ``id`` is 1-4, and corresponds to pins X1 through X4.

2
docs/library/pyb.Switch.rst
View File

@ -23,7 +23,7 @@ Example::
Constructors
------------
.. class:: pyb.Switch()
.. class:: Switch()
Create and return a switch object.

29
docs/library/pyb.Timer.rst
View File

@ -53,7 +53,7 @@ limitation.
Constructors
------------
.. class:: pyb.Timer(id, ...)
.. class:: Timer(id, ...)
Construct a new timer object of the given id. If additional
arguments are given, then the timer is initialised by ``init(...)``.
@ -62,7 +62,7 @@ Constructors
Methods
-------
.. method:: Timer.init(*, freq, prescaler, period, mode=Timer.UP, div=1, callback=None, deadtime=0)
.. method:: Timer.init(*, freq, prescaler, period, mode=Timer.UP, div=1, callback=None, deadtime=0, brk=Timer.BRK_OFF)
Initialise the timer. Initialisation must be either by frequency (in Hz)
or by prescaler and period::
@ -107,6 +107,14 @@ Methods
measures ticks of ``source_freq`` divided by ``div`` clock ticks.
``deadtime`` is only available on timers 1 and 8.
- ``brk`` - specifies if the break mode is used to kill the output of
the PWM when the ``BRK_IN`` input is asserted. The value of this
argument determines if break is enabled and what the polarity is, and
can be one of ``Timer.BRK_OFF``, ``Timer.BRK_LOW`` or
``Timer.BRK_HIGH``. To select the ``BRK_IN`` pin construct a Pin object with
``mode=Pin.ALT, alt=Pin.AFn_TIMx``. The pin's GPIO input features are
available in alt mode - ``pull=`` , ``value()`` and ``irq()``.
You must either specify freq or both of period and prescaler.
.. method:: Timer.deinit()
@ -198,6 +206,17 @@ Methods
ch2 = timer.channel(2, pyb.Timer.PWM, pin=pyb.Pin.board.X2, pulse_width=8000)
ch3 = timer.channel(3, pyb.Timer.PWM, pin=pyb.Pin.board.X3, pulse_width=16000)
PWM Motor Example with complementary outputs, dead time, break input and break callback::
from pyb import Timer
from machine import Pin # machine.Pin supports alt mode and irq on the same pin.
pin_t8_1 = Pin(Pin.board.Y1, mode=Pin.ALT, af=Pin.AF3_TIM8) # Pin PC6, TIM8_CH1
pin_t8_1n = Pin(Pin.board.X8, mode=Pin.ALT, af=Pin.AF3_TIM8) # Pin PA7, TIM8_CH1N
pin_bkin = Pin(Pin.board.X7, mode=Pin.ALT, af=Pin.AF3_TIM8) # Pin PA6, TIM8_BKIN
pin_bkin.irq(handler=break_callabck, trigger=Pin.IRQ_FALLING)
timer = pyb.Timer(8, freq=1000, deadtime=1008, brk=Timer.BRK_LOW)
ch1 = timer.channel(1, pyb.Timer.PWM, pulse_width_percent=30)
.. method:: Timer.counter([value])
Get or set the timer counter.
@ -271,3 +290,9 @@ Constants
Timer.CENTER
Configures the timer to count Up, Down, or from 0 to ARR and then back down to 0.
.. data:: Timer.BRK_OFF
Timer.BRK_LOW
Timer.BRK_HIGH
Configures the break mode when passed to the ``brk`` keyword argument.

2
docs/library/pyb.UART.rst
View File

@ -46,7 +46,7 @@ Earlier versions use ``uart.send`` and ``uart.recv``.
Constructors
------------
.. class:: pyb.UART(bus, ...)
.. class:: UART(bus, ...)
Construct a UART object on the given bus.
For Pyboard ``bus`` can be 1-4, 6, 'XA', 'XB', 'YA', or 'YB'.

2
docs/library/pyb.USB_HID.rst
View File

@ -13,7 +13,7 @@ Before you can use this class, you need to use :meth:`pyb.usb_mode()` to set the
Constructors
------------
.. class:: pyb.USB_HID()
.. class:: USB_HID()
Create a new USB_HID object.

2
docs/library/pyb.USB_VCP.rst
View File

@ -12,7 +12,7 @@ the connected host.
Constructors
------------
.. class:: pyb.USB_VCP(id=0)
.. class:: USB_VCP(id=0)
Create a new USB_VCP object. The *id* argument specifies which USB VCP port to
use.

18
docs/library/rp2.StateMachine.rst
View File

@ -55,8 +55,8 @@ Methods
`PIO.SHIFT_LEFT` or `PIO.SHIFT_RIGHT`.
- *push_thresh* is the threshold in bits before auto-push or conditional
re-pushing is triggered.
- *pull_thresh* is the threshold in bits before auto-push or conditional
re-pushing is triggered.
- *pull_thresh* is the threshold in bits before auto-pull or conditional
re-pulling is triggered.
.. method:: StateMachine.active([value])
@ -99,13 +99,17 @@ Methods
.. method:: StateMachine.put(value, shift=0)
Push a word onto the state machine's TX FIFO.
Push words onto the state machine's TX FIFO.
If the FIFO is full, it blocks until there is space (i.e. the state machine
pulls a word).
*value* can be an integer, an array of type ``B``, ``H`` or ``I``, or a
`bytearray`.
The value is first shifted left by *shift* bits, i.e. the state machine
receives ``value << shift``.
This method will block until all words have been written to the FIFO. If
the FIFO is, or becomes, full, the method will block until the state machine
pulls enough words to complete the write.
Each word is first shifted left by *shift* bits, i.e. the state machine
receives ``word << shift``.
.. method:: StateMachine.rx_fifo()

15
docs/library/rp2.rst
View File

@ -47,8 +47,8 @@ For running PIO programs, see :class:`rp2.StateMachine`.
`PIO.SHIFT_LEFT` or `PIO.SHIFT_RIGHT`.
- *push_thresh* is the threshold in bits before auto-push or conditional
re-pushing is triggered.
- *pull_thresh* is the threshold in bits before auto-push or conditional
re-pushing is triggered.
- *pull_thresh* is the threshold in bits before auto-pull or conditional
re-pulling is triggered.
The remaining parameters are:
@ -66,6 +66,17 @@ For running PIO programs, see :class:`rp2.StateMachine`.
>>> rp2.asm_pio_encode("set(0, 1)", 0)
57345
.. function:: bootsel_button()
Temporarily turns the QSPI_SS pin into an input and reads its value,
returning 1 for low and 0 for high.
On a typical RP2040 board with a BOOTSEL button, a return value of 1
indicates that the button is pressed.
Since this function temporarily disables access to the external flash
memory, it also temporarily disables interrupts and the other core to
prevent them from trying to execute code from flash.
.. class:: PIOASMError
This exception is raised from `asm_pio()` or `asm_pio_encode()` if there is

2
docs/library/socket.rst
View File

@ -29,7 +29,7 @@ returned by `getaddrinfo` function, which must be used to resolve textual addres
# You must use getaddrinfo() even for numeric addresses
sockaddr = socket.getaddrinfo('127.0.0.1', 80)[0][-1]
# Now you can use that address
sock.connect(addr)
sock.connect(sockaddr)
Using `getaddrinfo` is the most efficient (both in terms of memory and processing
power) and portable way to work with addresses.

13
docs/library/ssl.rst
View File

@ -13,7 +13,7 @@ facilities for network sockets, both client-side and server-side.
Functions
---------
.. function:: ssl.wrap_socket(sock, server_side=False, keyfile=None, certfile=None, cert_reqs=CERT_NONE, ca_certs=None, do_handshake=True)
.. function:: ssl.wrap_socket(sock, server_side=False, keyfile=None, certfile=None, cert_reqs=CERT_NONE, cadata=None, server_hostname=None, do_handshake=True)
Takes a `stream` *sock* (usually socket.socket instance of ``SOCK_STREAM`` type),
and returns an instance of ssl.SSLSocket, which wraps the underlying stream in
@ -31,6 +31,17 @@ Functions
until it completes. Note that in AXTLS the handshake can be deferred until the first
read or write but it then blocks until completion.
- *cert_reqs* determines whether the peer (server or client) must present a valid certificate.
Note that for mbedtls based ports, ``ssl.CERT_NONE`` and ``ssl.CERT_OPTIONAL`` will not
validate any certificate, only ``ssl.CERT_REQUIRED`` will.
- *cadata* is a bytes object containing the CA certificate chain (in DER format) that will
validate the peer's certificate. Currently only a single DER-encoded certificate is supported.
- *server_hostname* is for use as a client, and sets the hostname to check against the received
server certificate. It also sets the name for Server Name Indication (SNI), allowing the server
to present the proper certificate.
Depending on the underlying module implementation in a particular
:term:`MicroPython port`, some or all keyword arguments above may be not supported.

57
docs/library/struct.rst
View File

@ -6,11 +6,58 @@
|see_cpython_module| :mod:`python:struct`.
Supported size/byte order prefixes: ``@``, ``<``, ``>``, ``!``.
The following byte orders are supported:
Supported format codes: ``b``, ``B``, ``h``, ``H``, ``i``, ``I``, ``l``,
``L``, ``q``, ``Q``, ``s``, ``P``, ``f``, ``d`` (the latter 2 depending
on the floating-point support).
+-----------+------------------------+----------+-----------+
| Character | Byte order | Size | Alignment |
+===========+========================+==========+===========+
| @ | native | native | native |
+-----------+------------------------+----------+-----------+
| < | little-endian | standard | none |
+-----------+------------------------+----------+-----------+
| > | big-endian | standard | none |
+-----------+------------------------+----------+-----------+
| ! | network (= big-endian) | standard | none |
+-----------+------------------------+----------+-----------+
The following data types are supported:
+--------+--------------------+-------------------+---------------+
| Format | C Type | Python type | Standard size |
+========+====================+===================+===============+
| b | signed char | integer | 1 |
+--------+--------------------+-------------------+---------------+
| B | unsigned char | integer | 1 |
+--------+--------------------+-------------------+---------------+
| h | short | integer | 2 |
+--------+--------------------+-------------------+---------------+
| H | unsigned short | integer | 2 |
+--------+--------------------+-------------------+---------------+
| i | int | integer (`1<fn>`) | 4 |
+--------+--------------------+-------------------+---------------+
| I | unsigned int | integer (`1<fn>`) | 4 |
+--------+--------------------+-------------------+---------------+
| l | long | integer (`1<fn>`) | 4 |
+--------+--------------------+-------------------+---------------+
| L | unsigned long | integer (`1<fn>`) | 4 |
+--------+--------------------+-------------------+---------------+
| q | long long | integer (`1<fn>`) | 8 |
+--------+--------------------+-------------------+---------------+
| Q | unsigned long long | integer (`1<fn>`) | 8 |
+--------+--------------------+-------------------+---------------+
| f | float | float (`2<fn>`) | 4 |
+--------+--------------------+-------------------+---------------+
| d | double | float (`2<fn>`) | 8 |
+--------+--------------------+-------------------+---------------+
| s | char[] | bytes | |
+--------+--------------------+-------------------+---------------+
| P | void * | integer | |
+--------+--------------------+-------------------+---------------+
.. _fn:
(1) Requires long support when used with values larger than 30 bits.
(2) Requires floating point support.
.. admonition:: Difference to CPython
:class: attention
@ -43,5 +90,5 @@ Functions
.. function:: unpack_from(fmt, data, offset=0, /)
Unpack from the *data* starting at *offset* according to the format string
*fmt*. *offset* may be negative to count from the end of *buffer*. The return
*fmt*. *offset* may be negative to count from the end of *data*. The return
value is a tuple of the unpacked values.

4
docs/library/time.rst
View File

@ -10,8 +10,8 @@ The ``time`` module provides functions for getting the current time and date,
measuring time intervals, and for delays.
**Time Epoch**: Unix port uses standard for POSIX systems epoch of
1970-01-01 00:00:00 UTC. However, embedded ports use epoch of
2000-01-01 00:00:00 UTC.
1970-01-01 00:00:00 UTC. However, some embedded ports use epoch of
2000-01-01 00:00:00 UTC. Epoch year may be determined with ``gmtime(0)[0]``.
**Maintaining actual calendar date/time**: This requires a
Real Time Clock (RTC). On systems with underlying OS (including some

24
docs/library/uasyncio.rst
View File

@ -71,9 +71,9 @@ Additional functions
than *timeout* seconds. If *awaitable* is not a task then a task will be
created from it.
If a timeout occurs, it cancels the task and raises ``asyncio.TimeoutError``:
If a timeout occurs, it cancels the task and raises ``uasyncio.TimeoutError``:
this should be trapped by the caller. The task receives
``asyncio.CancelledError`` which may be ignored or trapped using ``try...except``
``uasyncio.CancelledError`` which may be ignored or trapped using ``try...except``
or ``try...finally`` to run cleanup code.
Returns the return value of *awaitable*.
@ -108,7 +108,7 @@ class Task
.. method:: Task.cancel()
Cancel the task by injecting ``asyncio.CancelledError`` into it. The task may
Cancel the task by injecting ``uasyncio.CancelledError`` into it. The task may
ignore this exception. Cleanup code may be run by trapping it, or via
``try ... finally``.
@ -148,14 +148,20 @@ class ThreadSafeFlag
.. class:: ThreadSafeFlag()
Create a new flag which can be used to synchronise a task with code running
outside the asyncio loop, such as other threads, IRQs, or scheduler
callbacks. Flags start in the cleared state.
outside the uasyncio loop, such as other threads, IRQs, or scheduler
callbacks. Flags start in the cleared state. The class does not currently
work under the Unix build of MicroPython.
.. method:: ThreadSafeFlag.set()
Set the flag. If there is a task waiting on the event, it will be scheduled
Set the flag. If there is a task waiting on the flag, it will be scheduled
to run.
.. method:: ThreadSafeFlag.clear()
Clear the flag. This may be used to ensure that a possibly previously-set
flag is clear before waiting for it.
.. method:: ThreadSafeFlag.wait()
Wait for the flag to be set. If the flag is already set then it returns
@ -237,9 +243,11 @@ TCP stream connections
This is a coroutine.
.. method:: Stream.read(n)
.. method:: Stream.read(n=-1)
Read up to *n* bytes and return them.
Read up to *n* bytes and return them. If *n* is not provided or -1 then read all
bytes until EOF. The returned value will be an empty bytes object if EOF is
encountered before any bytes are read.
This is a coroutine.

3
docs/mimxrt/pinout.rst
View File

@ -322,7 +322,8 @@ Olimex RT1010Py - CS0/-/SDO/SDI/SCK SDCARD wi
Seeed ARCH MIX J4_12/-/J4_14/J4_13/J4_15 J3_09/J3_05/J3_08_J3_11
================= ========================= ======================= ===============
Pins denoted with (*) are by default not wired at the board.
Pins denoted with (*) are by default not wired at the board. The CS0 and CS1 signals
are enabled with the keyword option cs=0 or cs=1 of the SPI object constructor.
.. _mimxrt_i2c_pinout:

17
docs/mimxrt/quickref.rst
View File

@ -56,21 +56,18 @@ Use the :mod:`time <time>` module::
Timers
------
The i.MXRT port has three hardware timers. Use the :ref:`machine.Timer <machine.Timer>` class
with a timer ID from 0 to 2 (inclusive)::
The i.MXRT port supports virtual Timers. Example of usage::
from machine import Timer
tim0 = Timer(0)
tim0 = Timer(-1)
tim0.init(period=5000, mode=Timer.ONE_SHOT, callback=lambda t:print(0))
tim1 = Timer(1)
tim1 = Timer(-1)
tim1.init(period=2000, mode=Timer.PERIODIC, callback=lambda t:print(1))
The period is in milliseconds.
Virtual timers are not currently supported on this port.
.. _mimxrt_Pins_and_GPIO:
Pins and GPIO
@ -301,13 +298,19 @@ There are up to four hardware SPI channels that allow faster transmission
rates (up to 30Mhz). Hardware SPI is accessed via the
:ref:`machine.SPI <machine.SPI>` class and has the same methods as software SPI above::
from machine import SPI
from machine import SPI, Pin
spi = SPI(0, 10000000)
cs_pin = Pin(6, Pin.OUT, value=1)
cs_pin(0)
spi.write('Hello World')
cs_pin(1)
For the assignment of Pins to SPI signals, refer to
:ref:`Hardware SPI pinout <mimxrt_spi_pinout>`.
The keyword option cs=n can be used to enable the cs pin 0 or 1 for an automatic cs signal. The
default is cs=-1. Using cs=-1 the automatic cs signal is not created.
In that case, cs has to be set by the script. Clearing that assignment requires a power cycle.
Notes:

4
docs/pyboard/tutorial/lcd160cr_skin.rst
View File

@ -40,9 +40,9 @@ Testing the display
There is a test program which you can use to test the features of the display,
and which also serves as a basis to start creating your own code that uses the
LCD. This test program is included in recent versions of the pyboard firmware
and is also available on GitHub
LCD. This test program is available on GitHub
`here <https://github.com/micropython/micropython/blob/master/drivers/display/lcd160cr_test.py>`__.
Copy it to the board over USB mass storage, or by using :ref:`mpremote`.
To run the test from the MicroPython prompt do::

2
docs/reference/constrained.rst
View File

@ -392,6 +392,8 @@ Symbol Meaning
F float
B byte code
M module
S string or bytes
A bytearray
====== =================
Each letter represents a single block of memory, a block being 16 bytes. So each

32
docs/reference/glossary.rst
View File

@ -52,7 +52,7 @@ Glossary
cross-compiler
Also known as ``mpy-cross``. This tool runs on your PC and converts a
:term:`.py file` containing MicroPython code into a :term:`.mpy file`
containing MicroPython bytecode. This means it loads faster (the board
containing MicroPython :term:`bytecode`. This means it loads faster (the board
doesn't have to compile the code), and uses less space on flash (the
bytecode is more space efficient).
@ -128,7 +128,7 @@ Glossary
Unlike the :term:`CPython` stdlib, micropython-lib modules are
intended to be installed individually - either using manual copying or
using :term:`upip`.
using :term:`mip`.
MicroPython port
MicroPython supports different :term:`boards <board>`, RTOSes, and
@ -151,16 +151,28 @@ Glossary
machine-independent features. It can also function in a similar way to
:term:`CPython`'s ``python`` executable.
mip
A package installer for MicroPython (mip - "mip installs packages"). It
installs MicroPython packages either from :term:`micropython-lib`,
GitHub, or arbitrary URLs. mip can be used on-device on
network-capable boards, and internally by tools such
as :term:`mpremote`.
See :ref:`packages` for more information on using ``mip``.
mpremote
A tool for interacting with a MicroPython device. See :ref:`mpremote`.
.mpy file
The output of the :term:`cross-compiler`. A compiled form of a
:term:`.py file` that contains MicroPython bytecode instead of Python
source code.
:term:`.py file` that contains MicroPython :term:`bytecode` instead of
Python source code.
native
Usually refers to "native code", i.e. machine code for the target
microcontroller (such as ARM Thumb, Xtensa, x86/x64). The ``@native``
decorator can be applied to a MicroPython function to generate native
code instead of bytecode for that function, which will likely be
code instead of :term:`bytecode` for that function, which will likely be
faster but use more RAM.
port
@ -193,8 +205,10 @@ Glossary
as a serial port over USB.
upip
(Literally, "micro pip"). A package manager for MicroPython, inspired
A now-obsolete package manager for MicroPython, inspired
by :term:`CPython`'s pip, but much smaller and with reduced
functionality.
upip runs both on the :term:`Unix port <MicroPython Unix port>` and on
:term:`baremetal` ports which offer filesystem and networking support.
functionality. See its replacement, :term:`mip`.
webrepl
A way of connecting to the REPL (and transferring files) on a device
over the internet from a browser. See https://micropython.org/webrepl

271
docs/reference/manifest.rst
View File

@ -1,35 +1,177 @@
.. _manifest:
MicroPython manifest files
==========================
When building firmware for a device the following components are included in
the compilation process:
Summary
-------
- the core MicroPython virtual machine and runtime
- port-specific system code and drivers to interface with the
microcontroller/device that the firmware is targeting
- standard built-in modules, like ``sys``
- extended built-in modules, like ``json`` and ``machine``
- extra modules written in C/C++
- extra modules written in Python
MicroPython has a feature that allows Python code to be "frozen" into the
firmware, as an alternative to loading code from the filesystem.
All the modules included in the firmware are available via ``import`` from
Python code. The extra modules written in Python that are included in a build
(the last point above) are called *frozen modules*, and are specified by a
``manifest.py`` file. Changing this manifest requires rebuilding the firmware.
This has the following benefits:
It's also possible to add additional modules to the filesystem of the device
once it is up and running. Adding and removing modules to/from the filesystem
does not require rebuilding the firmware so is a simpler process than rebuilding
firmware. The benefit of using a manifest is that frozen modules are more
efficient: they are faster to import and take up less RAM once imported.
- the code is pre-compiled to bytecode, avoiding the need for the Python
source to be compiled at load-time.
- the bytecode can be executed directly from ROM (i.e. flash memory) rather than
being copied into RAM. Similarly any constant objects (strings, tuples, etc)
are loaded from ROM also. This can lead to significantly more memory being
available for your application.
- on devices that do not have a filesystem, this is the only way to
load Python code.
MicroPython manifest files are Python files and can contain arbitrary Python
code. There are also a set of commands (predefined functions) which are used
to specify the Python source files to include. These commands are described
below.
During development, freezing is generally not recommended as it will
significantly slow down your development cycle, as each update will require
re-flashing the entire firmware. However, it can still be useful to
selectively freeze some rarely-changing dependencies (such as third-party
libraries).
Freezing source code
--------------------
The way to list the Python files to be be frozen into the firmware is via
a "manifest", which is a Python file that will be interpreted by the build
process. Typically you would write a manifest file as part of a board
definition, but you can also write a stand-alone manifest file and use it with
an existing board definition.
Manifest files can define dependencies on libraries from :term:`micropython-lib`
as well as Python files on the filesystem, and also on other manifest files.
Writing manifest files
----------------------
A manifest file is a Python file containing a series of function calls. See the
available functions defined below.
Any paths used in manifest files can include the following variables. These all
resolve to absolute paths.
- ``$(MPY_DIR)`` -- path to the micropython repo.
- ``$(MPY_LIB_DIR)`` -- path to the micropython-lib submodule. Prefer to use
``require()``.
- ``$(PORT_DIR)`` -- path to the current port (e.g. ``ports/stm32``)
- ``$(BOARD_DIR)`` -- path to the current board
(e.g. ``ports/stm32/boards/PYBV11``)
Custom manifest files should not live in the main MicroPython repository. You
should keep them in version control with the rest of your project.
Typically a manifest used for compiling firmware will need to include the port
manifest, which might include frozen modules that are required for the board to
function. If you just want to add additional modules to an existing board, then
include the board manifest (which will in turn include the port manifest).
Building with a custom manifest
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Your manifest can be specified on the ``make`` command line with:
.. code-block:: bash
$ make BOARD=MYBOARD FROZEN_MANIFEST=/path/to/my/project/manifest.py
This applies to all ports, including CMake-based ones (e.g. esp32, rp2), as the
Makefile wrapper that will pass this into the CMake build.
Adding a manifest to a board definition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you have a custom board definition, you can make it include your custom
manifest automatically. On make-based ports (most ports), in your
``mpconfigboard.mk`` set the ``FROZEN_MANIFEST`` variable.
.. code-block:: makefile
FROZEN_MANIFEST ?= $(BOARD_DIR)/manifest.py
On CMake-based ports (e.g. esp32, rp2), instead use ``mpconfigboard.cmake``
.. code-block:: cmake
set(MICROPY_FROZEN_MANIFEST ${MICROPY_BOARD_DIR}/manifest.py)
High-level functions
~~~~~~~~~~~~~~~~~~~~
Note: The ``opt`` keyword argument can be set on the various functions, this controls
the optimisation level used by the cross-compiler.
See :func:`micropython.opt_level`.
.. function:: package(package_path, files=None, base_path=".", opt=None)
This is equivalent to copying the "package_path" directory to the device
(except as frozen code).
In the simplest case, to freeze a package "foo" in the current directory:
.. code-block:: python3
package("foo")
will recursively include all .py files in foo, and will be frozen as
``foo/**/*.py``.
If the package isn't in the same directory as the manifest file, use ``base_path``:
.. code-block:: python3
package("foo", base_path="path/to/libraries")
You can use the variables above, such as ``$(PORT_DIR)`` in ``base_path``.
To restrict to certain files in the package use ``files`` (note: paths
should be relative to the package): ``package("foo", files=["bar/baz.py"])``.
.. function:: module(module_path, base_path=".", opt=None)
Include a single Python file as a module.
If the file is in the current directory:
.. code-block:: python3
module("foo.py")
Otherwise use base_path to locate the file:
.. code-block:: python3
module("foo.py", base_path="src/drivers")
You can use the variables above, such as ``$(PORT_DIR)`` in ``base_path``.
.. function:: require(name, unix_ffi=False)
Require a package by name (and its dependencies) from :term:`micropython-lib`.
Optionally specify unix_ffi=True to use a module from the unix-ffi directory.
.. function:: include(manifest_path)
Include another manifest.
Typically a manifest used for compiling firmware will need to include the
port manifest, which might include frozen modules that are required for
the board to function.
The *manifest* argument can be a string (filename) or an iterable of
strings.
Relative paths are resolved with respect to the current manifest file.
If the path is to a directory, then it implicitly includes the
manifest.py file inside that directory.
You can use the variables above, such as ``$(PORT_DIR)`` in ``manifest_path``.
.. function:: metadata(description=None, version=None, license=None, author=None)
Define metadata for this manifest file. This is useful for manifests for
micropython-lib packages.
Low-level functions
~~~~~~~~~~~~~~~~~~~
These functions are documented for completeness, but with the exception of
``freeze_as_str`` all functionality can be accessed via the high-level functions.
.. function:: freeze(path, script=None, opt=0)
@ -42,9 +184,7 @@ Freezing source code
module will start after *path*, i.e. *path* is excluded from the module
name.
If *path* is relative, it is resolved to the current ``manifest.py``. Use
``$(MPY_DIR)``, ``$(MPY_LIB_DIR)``, ``$(PORT_DIR)``, ``$(BOARD_DIR)`` if you
need to access specific paths.
If *path* is relative, it is resolved to the current ``manifest.py``.
If *script* is None, all files in *path* will be frozen.
@ -75,71 +215,48 @@ Freezing source code
Freeze the input, which must be ``.mpy`` files that are frozen directly.
See ``freeze()`` for further details on the arguments.
Including other manifest files
------------------------------
.. function:: include(manifest, **kwargs)
Include another manifest.
The *manifest* argument can be a string (filename) or an iterable of
strings.
Relative paths are resolved with respect to the current manifest file.
Optional *kwargs* can be provided which will be available to the included
script via the *options* variable.
For example:
.. code-block:: python3
include("path.py", extra_features=True)
then in path.py:
.. code-block:: python3
options.defaults(standard_features=True)
# freeze minimal modules.
if options.standard_features:
# freeze standard modules.
if options.extra_features:
# freeze extra modules.
Examples
--------
To freeze a single file which is available as ``import mydriver``, use:
To freeze a single file from the current directory which will be available as
``import mydriver``, use:
.. code-block:: python3
freeze(".", "mydriver.py")
module("mydriver.py")
To freeze a set of files which are available as ``import test1`` and
``import test2``, and which are compiled with optimisation level 3, use:
To freeze a directory of files in a subdirectory "mydriver" of the current
directory which will be available as ``import mydriver``, use:
.. code-block:: python3
freeze("/path/to/tests", ("test1.py", "test2.py"), opt=3)
package("mydriver")
To freeze a module which can be imported as ``import mymodule``, use:
To freeze the "hmac" library from :term:`micropython-lib`, use:
.. code-block:: python3
freeze(
"../relative/path",
(
"mymodule/__init__.py",
"mymodule/core.py",
"mymodule/extra.py",
),
)
require("hmac")
To include a manifest from the MicroPython repository, use:
A more complete example of a custom ``manifest.py`` file for the ``PYBD_SF2``
board is:
.. code-block:: python3
include("$(MPY_DIR)/extmod/uasyncio/manifest.py")
# Include the board's default manifest.
include("$(BOARD_DIR)/manifest.py")
# Add a custom driver
module("mydriver.py")
# Add aiorepl from micropython-lib
require("aiorepl")
Then the board can be compiled with
.. code-block:: bash
$ cd ports/stm32
$ make BOARD=PYBD_SF2 FROZEN_MANIFEST=~/src/myproject/manifest.py
Note that most boards do not have their own ``manifest.py``, rather they use the
port one directly, in which case your manifest should just
``include("$(PORT_DIR)/boards/manifest.py")`` instead.

53
docs/reference/mpremote.rst
View File

@ -1,3 +1,5 @@
.. _mpremote:
MicroPython remote control: mpremote
====================================
@ -17,10 +19,10 @@ The simplest way to use this tool is just by invoking it without any arguments:
mpremote
This command automatically detects and connects to the first available serial
device and provides an interactive REPL. Serial ports are opened in exclusive
mode, so running a second (or third, etc) instance of ``mpremote`` will connect
to subsequent serial devices, if any are available.
This command automatically detects and connects to the first available USB
serial device and provides an interactive REPL. Serial ports are opened in
exclusive mode, so running a second (or third, etc) instance of ``mpremote``
will connect to subsequent serial devices, if any are available.
Commands
@ -30,6 +32,9 @@ For REPL access, running ``mpremote`` without any arguments is usually all that
is needed. ``mpremote`` also supports a set of commands given at the command
line which will perform various actions on remote MicroPython devices.
For commands that support multiple arguments (e.g. a list of files), the
argument list can be terminated with ``+``.
The full list of supported commands are:
- connect to a specified device via a device-name shortcut:
@ -47,7 +52,7 @@ The full list of supported commands are:
``<device>`` may be one of:
- ``list``: list available devices
- ``auto``: connect to the first available device
- ``auto``: connect to the first available USB serial port
- ``id:<serial>``: connect to the device with USB serial number
``<serial>`` (the second entry in the output from the ``connect list``
command)
@ -128,6 +133,26 @@ The full list of supported commands are:
- ``rm <src...>`` to remove files on the device
- ``mkdir <dirs...>`` to create directories on the device
- ``rmdir <dirs...>`` to remove directories on the device
- ``touch <file..>`` to create the files (if they don't already exist)
- edit a file on the device:
.. code-block:: bash
$ mpremote edit <files...>
The ``edit`` command will copy each file from the device to a local temporary
directory and then launch your editor for each file (defined by the environment
variable ``$EDITOR``). If the editor exits successfully, the updated file will
be copied back to the device.
- install packages from :term:`micropython-lib` (or GitHub) using the ``mip`` tool:
.. code-block:: bash
$ mpremote mip install <packages...>
See :ref:`packages` for more information.
- mount the local directory on the remote device:
@ -161,8 +186,8 @@ Auto connection and soft-reset
Connection and disconnection will be done automatically at the start and end of
the execution of the tool, if such commands are not explicitly given. Automatic
connection will search for the first available serial device. If no action is
specified then the REPL will be entered.
connection will search for the first available USB serial device. If no action
is specified then the REPL will be entered.
Once connected to a device, ``mpremote`` will automatically soft-reset the
device if needed. This clears the Python heap and restarts the interpreter,
@ -189,8 +214,8 @@ Shortcuts can be defined using the macro system. Built-in shortcuts are::
- ``c0``, ``c1``, ``c2``, ``c3``: connect to COM?
- ``cat``, ``ls``, ``cp``, ``rm``, ``mkdir``, ``rmdir``, ``df``: filesystem
commands
- ``cat``, ``ls``, ``cp``, ``rm``, ``mkdir``, ``rmdir``, ``touch``, ``df``:
filesystem commands
- ``reset``: reset the device
@ -247,4 +272,14 @@ Examples
mpremote cp main.py :
mpremote cp :a.py :b.py
mpremote cp -r dir/ :
mpremote cp a.py b.py : + repl
mpremote mip install aioble
mpremote mip install github:org/repo@branch
mpremote mip install --target /flash/third-party functools

6
docs/reference/mpyfiles.rst
View File

@ -27,6 +27,11 @@ Compatibility is based on the following:
* Version of the .mpy file: the version of the file must match the version
supported by the system loading it.
* Sub-version of the .mpy file: if the .mpy file contains native machine code
then the sub-version of the file must match the version support by the
system loading it. Otherwise, if there is no native machine code in the .mpy
file, then the sub-version is ignored when loading.
* Small integer bits: the .mpy file will require a minimum number of bits in
a small integer and the system loading it must support at least this many
bits.
@ -55,6 +60,7 @@ If importing an .mpy file fails then try the following:
'armv6', 'armv6m', 'armv7m', 'armv7em', 'armv7emsp', 'armv7emdp',
'xtensa', 'xtensawin'][sys_mpy >> 10]
print('mpy version:', sys_mpy & 0xff)
print('mpy sub-version:', sys_mpy >> 8 & 3)
print('mpy flags:', end='')
if arch:
print(' -march=' + arch, end='')

463
docs/reference/packages.rst
View File

@ -1,314 +1,153 @@
.. _packages:
Distribution packages, package management, and deploying applications
=====================================================================
Just as the "big" Python, MicroPython supports creation of "third party"
packages, distributing them, and easily installing them in each user's
environment. This chapter discusses how these actions are achieved.
Some familiarity with Python packaging is recommended.
Overview
--------
Steps below represent a high-level workflow when creating and consuming
packages:
1. Python modules and packages are turned into distribution package
archives, and published at the Python Package Index (PyPI).
2. :term:`upip` package manager can be used to install a distribution package
on a :term:`MicroPython port` with networking capabilities (for example,
on the Unix port).
3. For ports without networking capabilities, an "installation image"
can be prepared on the Unix port, and transferred to a device by
suitable means.
4. For low-memory ports, the installation image can be frozen as the
bytecode into MicroPython executable, thus minimizing the memory
storage overheads.
The sections below describe this process in details.
Distribution packages
---------------------
Python modules and packages can be packaged into archives suitable for
transfer between systems, storing at the well-known location (PyPI),
and downloading on demand for deployment. These archives are known as
*distribution packages* (to differentiate them from Python packages
(means to organize Python source code)).
The MicroPython distribution package format is a well-known tar.gz
format, with some adaptations however. The Gzip compressor, used as
an external wrapper for TAR archives, by default uses 32KB dictionary
size, which means that to uncompress a compressed stream, 32KB of
contiguous memory needs to be allocated. This requirement may be not
satisfiable on low-memory devices, which may have total memory available
less than that amount, and even if not, a contiguous block like that
may be hard to allocate due to memory fragmentation. To accommodate
these constraints, MicroPython distribution packages use Gzip compression
with the dictionary size of 4K, which should be a suitable compromise
with still achieving some compression while being able to uncompressed
even by the smallest devices.
Besides the small compression dictionary size, MicroPython distribution
packages also have other optimizations, like removing any files from
the archive which aren't used by the installation process. In particular,
:term:`upip` package manager doesn't execute ``setup.py`` during installation
(see below), and thus that file is not included in the archive.
At the same time, these optimizations make MicroPython distribution
packages not compatible with :term:`CPython`'s package manager, ``pip``.
This isn't considered a big problem, because:
1. Packages can be installed with :term:`upip`, and then can be used with
CPython (if they are compatible with it).
2. In the other direction, majority of CPython packages would be
incompatible with MicroPython by various reasons, first of all,
the reliance on features not implemented by MicroPython.
Summing up, the MicroPython distribution package archives are highly
optimized for MicroPython's target environments, which are highly
resource constrained devices.
``upip`` package manager
------------------------
MicroPython distribution packages are intended to be installed using
the :term:`upip` package manager. :term:`upip` is a Python application which is
usually distributed (as frozen bytecode) with network-enabled
:term:`MicroPython ports <MicroPython port>`. At the very least,
:term:`upip` is available in the :term:`MicroPython Unix port`.
On any :term:`MicroPython port` providing :term:`upip`, it can be accessed as
following::
import upip
upip.help()
upip.install(package_or_package_list, [path])
Where *package_or_package_list* is the name of a distribution
package to install, or a list of such names to install multiple
packages. Optional *path* parameter specifies filesystem
location to install under and defaults to the standard library
location (see below).
An example of installing a specific package and then using it::
>>> import upip
>>> upip.install("micropython-pystone_lowmem")
[...]
>>> import pystone_lowmem
>>> pystone_lowmem.main()
Note that the name of Python package and the name of distribution
package for it in general don't have to match, and oftentimes they
don't. This is because PyPI provides a central package repository
for all different Python implementations and versions, and thus
distribution package names may need to be namespaced for a particular
implementation. For example, all packages from `micropython-lib`
follow this naming convention: for a Python module or package named
``foo``, the distribution package name is ``micropython-foo``.
For the ports which run MicroPython executable from the OS command
prompts (like the Unix port), `upip` can be (and indeed, usually is)
run from the command line instead of MicroPython's own REPL. The
commands which corresponds to the example above are::
micropython -m upip -h
micropython -m upip install [-p <path>] <packages>...
micropython -m upip install micropython-pystone_lowmem
[TODO: Describe installation path.]
Cross-installing packages
-------------------------
For :term:`MicroPython ports <MicroPython port>` without native networking
capabilities, the recommend process is "cross-installing" them into a
"directory image" using the :term:`MicroPython Unix port`, and then
transferring this image to a device by suitable means.
Installing to a directory image involves using ``-p`` switch to :term:`upip`::
micropython -m upip install -p install_dir micropython-pystone_lowmem
After this command, the package content (and contents of every dependency
packages) will be available in the ``install_dir/`` subdirectory. You
would need to transfer contents of this directory (without the
``install_dir/`` prefix) to the device, at the suitable location, where
it can be found by the Python ``import`` statement (see discussion of
the :term:`upip` installation path above).
Cross-installing packages with freezing
---------------------------------------
For the low-memory :term:`MicroPython ports <MicroPython port>`, the process
described in the previous section does not provide the most efficient
resource usage,because the packages are installed in the source form,
so need to be compiled to the bytecome on each import. This compilation
requires RAM, and the resulting bytecode is also stored in RAM, reducing
its amount available for storing application data. Moreover, the process
above requires presence of the filesystem on a device, and the most
resource-constrained devices may not even have it.
The bytecode freezing is a process which resolves all the issues
mentioned above:
* The source code is pre-compiled into bytecode and store as such.
* The bytecode is stored in ROM, not RAM.
* Filesystem is not required for frozen packages.
Using frozen bytecode requires building the executable (firmware)
for a given :term:`MicroPython port` from the C source code. Consequently,
the process is:
1. Follow the instructions for a particular port on setting up a
toolchain and building the port. For example, for ESP8266 port,
study instructions in ``ports/esp8266/README.md`` and follow them.
Make sure you can build the port and deploy the resulting
executable/firmware successfully before proceeding to the next steps.
2. Build :term:`MicroPython Unix port` and make sure it is in your PATH and
you can execute ``micropython``.
3. Change to port's directory (e.g. ``ports/esp8266/`` for ESP8266).
4. Run ``make clean-frozen``. This step cleans up any previous
modules which were installed for freezing (consequently, you need
to skip this step to add additional modules, instead of starting
from scratch).
5. Run ``micropython -m upip install -p modules <packages>...`` to
install packages you want to freeze.
6. Run ``make clean``.
7. Run ``make``.
After this, you should have the executable/firmware with modules as
the bytecode inside, which you can deploy the usual way.
Few notes:
1. Step 5 in the sequence above assumes that the distribution package
is available from PyPI. If that is not the case, you would need
to copy Python source files manually to ``modules/`` subdirectory
of the port directory. (Note that upip does not support
installing from e.g. version control repositories).
2. The firmware for baremetal devices usually has size restrictions,
so adding too many frozen modules may overflow it. Usually, you
would get a linking error if this happens. However, in some cases,
an image may be produced, which is not runnable on a device. Such
cases are in general bugs, and should be reported and further
investigated. If you face such a situation, as an initial step,
you may want to decrease the amount of frozen modules included.
Creating distribution packages
------------------------------
Distribution packages for MicroPython are created in the same manner
as for CPython or any other Python implementation, see references at
the end of chapter. Setuptools (instead of distutils) should be used,
because distutils do not support dependencies and other features. "Source
distribution" (``sdist``) format is used for packaging. The post-processing
discussed above, (and pre-processing discussed in the following section)
is achieved by using custom ``sdist`` command for setuptools. Thus, packaging
steps remain the same as for the standard setuptools, the user just
needs to override ``sdist`` command implementation by passing the
appropriate argument to ``setup()`` call::
from setuptools import setup
import sdist_upip
setup(
...,
cmdclass={'sdist': sdist_upip.sdist}
)
The sdist_upip.py module as referenced above can be found in
`micropython-lib`:
https://github.com/micropython/micropython-lib/blob/master/sdist_upip.py
Application resources
---------------------
A complete application, besides the source code, oftentimes also consists
of data files, e.g. web page templates, game images, etc. It's clear how
to deal with those when application is installed manually - you just put
those data files in the filesystem at some location and use the normal
file access functions.
The situation is different when deploying applications from packages - this
is more advanced, streamlined and flexible way, but also requires more
advanced approach to accessing data files. This approach is treating
the data files as "resources", and abstracting away access to them.
Python supports resource access using its "setuptools" library, using
``pkg_resources`` module. MicroPython, following its usual approach,
implements subset of the functionality of that module, specifically
``pkg_resources.resource_stream(package, resource)`` function.
The idea is that an application calls this function, passing a
resource identifier, which is a relative path to data file within
the specified package (usually top-level application package). It
returns a stream object which can be used to access resource contents.
Thus, the ``resource_stream()`` emulates interface of the standard
`open()` function.
Implementation-wise, ``resource_stream()`` uses file operations
underlyingly, if distribution package is install in the filesystem.
However, it also supports functioning without the underlying filesystem,
e.g. if the package is frozen as the bytecode. This however requires
an extra intermediate step when packaging application - creation of
"Python resource module".
The idea of this module is to convert binary data to a Python bytes
object, and put it into the dictionary, indexed by the resource name.
This conversion is done automatically using overridden ``sdist`` command
described in the previous section.
Let's trace the complete process using the following example. Suppose
your application has the following structure::
my_app/
__main__.py
utils.py
data/
page.html
image.png
``__main__.py`` and ``utils.py`` should access resources using the
following calls::
import pkg_resources
pkg_resources.resource_stream(__name__, "data/page.html")
pkg_resources.resource_stream(__name__, "data/image.png")
You can develop and debug using the :term:`MicroPython Unix port` as usual.
When time comes to make a distribution package out of it, just use
overridden "sdist" command from sdist_upip.py module as described in
the previous section.
This will create a Python resource module named ``R.py``, based on the
files declared in ``MANIFEST`` or ``MANIFEST.in`` files (any non-``.py``
file will be considered a resource and added to ``R.py``) - before
proceeding with the normal packaging steps.
Prepared like this, your application will work both when deployed to
filesystem and as frozen bytecode.
If you would like to debug ``R.py`` creation, you can run::
python3 setup.py sdist --manifest-only
Alternatively, you can use tools/mpy_bin2res.py script from the
MicroPython distribution, in which can you will need to pass paths
to all resource files::
mpy_bin2res.py data/page.html data/image.png
References
----------
* Python Packaging User Guide: https://packaging.python.org/
* Setuptools documentation: https://setuptools.readthedocs.io/
* Distutils documentation: https://docs.python.org/3/library/distutils.html
Package management
==================
Installing packages with ``mip``
--------------------------------
Network-capable boards include the ``mip`` module, which can install packages
from :term:`micropython-lib` and from third-party sites (including GitHub).
``mip`` ("mip installs packages") is similar in concept to Python's ``pip`` tool,
however it does not use the PyPI index, rather it uses :term:`micropython-lib`
as its index by default. ``mip`` will automatically fetch compiled
:term:`.mpy file` when downloading from micropython-lib.
The most common way to use ``mip`` is from the REPL::
>>> import mip
>>> mip.install("pkgname") # Installs the latest version of "pkgname" (and dependencies)
>>> mip.install("pkgname", version="x.y") # Installs version x.y of "pkgname"
>>> mip.install("pkgname", mpy=False) # Installs the source version (i.e. .py rather than .mpy files)
``mip`` will detect an appropriate location on the filesystem by searching
``sys.path`` for the first entry ending in ``/lib``. You can override the
destination using ``target``, but note that this path must be in ``sys.path`` to be
able to subsequently import it.::
>>> mip.install("pkgname", target="third-party")
>>> sys.path.append("third-party")
As well as downloading packages from the micropython-lib index, ``mip`` can also
install third-party libraries. The simplest way is to download a file directly::
>>> mip.install("http://example.com/x/y/foo.py")
>>> mip.install("http://example.com/x/y/foo.mpy")
When installing a file directly, the ``target`` argument is still supported to set
the destination path, but ``mpy`` and ``version`` are ignored.
The URL can also start with ``github:`` as a simple way of pointing to content
hosted on GitHub::
>>> mip.install("github:org/repo/path/foo.py") # Uses default branch
>>> mip.install("github:org/repo/path/foo.py", version="branch-or-tag") # Optionally specify the branch or tag
More sophisticated packages (i.e. with more than one file, or with dependencies)
can be downloaded by specifying the path to their ``package.json``.
>>> mip.install("http://example.com/x/package.json")
>>> mip.install("github:org/user/path/package.json")
If no json file is specified, then "package.json" is implicitly added::
>>> mip.install("http://example.com/x/")
>>> mip.install("github:org/repo")
>>> mip.install("github:org/repo", version="branch-or-tag")
Using ``mip`` on the Unix port
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
On the Unix port, ``mip`` can be used at the REPL as above, and also by using ``-m``::
$ ./micropython -m mip install pkgname-or-url
$ ./micropython -m mip install pkgname-or-url@version
The ``--target=path``, ``--no-mpy``, and ``--index`` arguments can be set::
$ ./micropython -m mip install --target=third-party pkgname
$ ./micropython -m mip install --no-mpy pkgname
$ ./micropython -m mip install --index https://host/pi pkgname
Installing packages with ``mpremote``
-------------------------------------
The :term:`mpremote` tool also includes the same functionality as ``mip`` and
can be used from a host PC to install packages to a locally connected device
(e.g. via USB or UART)::
$ mpremote mip install pkgname
$ mpremote mip install pkgname@x.y
$ mpremote mip install http://example.com/x/y/foo.py
$ mpremote mip install github:org/repo
$ mpremote mip install github:org/repo@branch-or-tag
The ``--target=path``, ``--no-mpy``, and ``--index`` arguments can be set::
$ mpremote mip install --target=/flash/third-party pkgname
$ mpremote mip install --no-mpy pkgname
$ mpremote mip install --index https://host/pi pkgname
Installing packages manually
----------------------------
Packages can also be installed (in either .py or .mpy form) by manually copying
the files to the device. Depending on the board this might be via USB Mass Storage,
the :term:`mpremote` tool (e.g. ``mpremote fs cp path/to/package.py :package.py``),
:term:`webrepl`, etc.
Writing & publishing packages
-----------------------------
Publishing to :term:`micropython-lib` is the easiest way to make your package
broadly accessible to MicroPython users, and automatically available via
``mip`` and ``mpremote`` and compiled to bytecode. See
https://github.com/micropython/micropython-lib for more information.
To write a "self-hosted" package that can be downloaded by ``mip`` or
``mpremote``, you need a static webserver (or GitHub) to host either a
single .py file, or a package.json file alongside your .py files.
A typical package.json for an example ``mlx90640`` library looks like::
{
"urls": [
["mlx90640/__init__.py", "github:org/micropython-mlx90640/mlx90640/__init__.py"],
["mlx90640/utils.py", "github:org/micropython-mlx90640/mlx90640/utils.py"]
],
"deps": [
["collections-defaultdict", "latest"],
["os-path", "latest"]
],
"version": "0.2"
}
This includes two files, hosted at a GitHub repo named
``org/micropython-mlx90640``, which install into the ``mlx90640`` directory on
the device. It depends on ``collections-defaultdict`` and ``os-path`` which will
be installed automatically.
Freezing packages
-----------------
When a Python module or package is imported from the device filesystem, it is
compiled into :term:`bytecode` in RAM, ready to be executed by the VM. For
a :term:`.mpy file`, this conversion has been done already, but the bytecode
still ends up in RAM.
For low-memory devices, or for large applications, it can be advantageous to
instead run the bytecode from ROM (i.e. flash memory). This can be done
by "freezing" the bytecode into the MicroPython firmware, which is then flashed
to the device. The runtime performance is the same (although importing is
faster), but it can free up significant amounts of RAM for your program to
use.
The downside of this approach is that it's much slower to develop, because you
have to flash the firmware each time, but it can be still useful to freeze
dependencies that don't change often.
Freezing is done by writing a manifest file and using it in the build, often as
part of a custom board definition. See the :ref:`manifest` guide for more
information.

5
docs/reference/pyboard.py.rst
View File

@ -92,12 +92,13 @@ Filesystem access
Using the ``-f`` flag, the following filesystem operations are supported:
* ``cp src [src...] dest`` Copy files to/from the device.
* ``cat path`` Print the contents of a file on the device.
* ``cp src [src...] dest`` Copy files to/from the device.
* ``ls [path]`` List contents of a directory (defaults to current working directory).
* ``rm path`` Remove a file.
* ``mkdir path`` Create a directory.
* ``rm path`` Remove a file.
* ``rmdir path`` Remove a directory.
* ``touch path`` Create a file if it doesn't already exist.
The ``cp`` command uses a ``ssh``-like convention for referring to local and
remote files. Any path starting with a ``:`` will be interpreted as on the

18
docs/renesas-ra/quickref.rst
View File

@ -110,6 +110,24 @@ Use the :ref:`machine.Pin <machine.Pin>` class::
Pin id is available corresponding to the RA MCU's pin name which are Pin.cpu.P106 and 'P106'. The RA MCU has many feature's pins. However, there are some cases that pin feature is fixed or not connected by the board. Please confirm the board manual for the pin mapping.
The following *drive* keyword argument are available if the port drive capability of the Pin is supported by the MCU::
Pin.DRIVE_0: Low drive
Pin.DRIVE_1: Middle drive
Pin.DRIVE_2: Middle drive for I2C Fast-mode
Pin.DRIVE_3: High drive
The *alt* keyword argument is not supported.
The following functions are not supported::
Pin.irq(priority=) # priority keyword argument is not supported
Pin.irq(wake=) # wake keyword argument is not supported
Pin.irq(hard=) # hard keyword argument is ignored because hardware interrupt is used
Pin.mode()
Pin.pull()
Pin.drive()
UART (serial bus)
-----------------

4
docs/renesas-ra/tutorial/program_in_flash.rst
View File

@ -18,8 +18,8 @@ As the factory setting, following size is allocated for the file system:
--------------- -------------------
EK-RA4M1 36KB ( 36864B)
EK-RA4W1 64KB ( 65536B)
EK-RA6M1 128KB (131072B)
EK-RA6M2 256KB (262144B)
EK-RA6M1 64KB ( 65536B)
EK-RA6M2 128KB (131072B)
RA4M1 CLICKER 36KB ( 36864B)
=============== ===================

1
docs/rp2/quickref.rst
View File

@ -296,6 +296,7 @@ See :ref:`machine.WDT <machine.WDT>`. ::
wdt = WDT(timeout=5000)
wdt.feed()
The maximum value for timeout is 8388 ms.
OneWire driver
--------------

7
docs/rp2/tutorial/pio.rst
View File

@ -76,9 +76,10 @@ and state machines. Below is the code for reference.
nop() [29]
jmp(x_dec, "delay_high")
# Cycles: 1 + 7 + 32 * (30 + 1) = 1000
# Cycles: 1 + 1 + 6 + 32 * (30 + 1) = 1000
nop()
set(pins, 0)
set(x, 31) [6]
set(x, 31) [5]
label("delay_low")
nop() [29]
jmp(x_dec, "delay_low")
@ -113,6 +114,8 @@ the following:
X starts with the value 31 this jump will happen 31 times, so the ``nop() [29]``
runs 32 times in total (note there is also one instruction cycle taken by the
``jmp`` for each of these 32 loops).
- The single ``nop()`` correlates with the cycle used for IRQ raise, and ensures
the same number of cycles are used for LED on and LED off.
- ``set(pins, 0)`` will turn the LED off by setting pin 25 low.
- Another 32 loops of ``nop() [29]`` and ``jmp(...)`` will execute.
- Because ``wrap_target()`` and ``wrap()`` are not specified, their default will

88
docs/samd/general.rst Normal file
View File

@ -0,0 +1,88 @@
.. _samd_general:
General information about the SAMD port
=======================================
The SAMD21/SAMD51 MCU family is a high performance family of devices made by MicroChip.
The SAMD21 devices are based on an ARM M0+ core, the SAMD51 device on ARM Cortex M4 core.
They provide many on-chip I/O units for building small to medium sized devices.
Multitude of boards
-------------------
There is a multitude of modules and boards from different sources which carry
an SAMD21/SAMD51 chip. MicroPython aims to provide a generic port which runs on
as many boards/modules as possible, but there may be limitations. The
Adafruit ItsyBitsy M0 Express, Adafruit Feather M4 Express and the Adafruit ItsyBitsy M4 Express
development boards are taken as reference for the port (for example, testing is performed on them).
For any board you are using please make sure you have a data sheet, schematics
and other reference materials so you can look up any board-specific functions.
The following boards are at the moment supported by the port:
- ADAFRUIT FEATHER M0 EXPRESS
- ADAFRUIT FEATHER M4 EXPRESS
- ADAFRUIT ITSYBITSY M0 EXPRESS
- ADAFRUIT ITSYBITSY M4 EXPRESS
- ADAFRUIT TRINKET M0
- MINISAM M4
- SAMD21 XPLAINED PRO
- SEEED WIO TERMINAL
- SEEED XIAO
To make a generic SAMD port and support as many boards as possible the
following design and implementation decision were made:
* GPIO pin numbering is based on the board numbering.
Please have the manual/pin diagram of your board at hand
to find correspondence between your board pins and actual SAMD21/SAMD51 pins.
For the boards listed above, the relation between the board pin number and
the GPIO number can be found at :ref:`samd_pinout`.
* The pins that can be used by MicroPython are limited to those listed
in the board definition files.
Technical specifications and SoC data sheets
--------------------------------------------
The data sheets and other reference material for SAMD21/SAMD51 chip are available
from the vendor site: https://www.microchip.com/en-us/products/microcontrollers-and-microprocessors/32-bit-mcus/sam-32-bit-mcus
They are the primary reference for the chip technical specifications, capabilities,
operating modes, internal functioning, etc.
For your convenience, a few technical specifications are provided below:
SAMD21:
* Architecture: ARM Cortex M0+
* CPU frequency: up to 48MHz
* Total RAM available: up to 32 kB (see table)
* Internal FlashROM: up to 256 kB
Some boards provide additional external SPI flash.
* GPIO: up to 52 (GPIOs are multiplexed with other functions, including
external FlashROM, UART, etc.)
* UART: up to 6 serial devices, which can used for UART, SPI or I2C.
* I2S: 1 I2S interfaces
* ADC: One 12-bit SAR ADC converter with 16 channels.
* Programming: using BootROM bootloader from USB.
SAMD51:
* Architecture: ARM Cortex M4
* CPU frequency: up to 120MHz
* Total RAM available: up to 256 kB
* Internal FlashROM: up to 1 MB
Some boards provide additional external SPI flash.
* GPIO: up to 99 (GPIOs are multiplexed with other functions, including
external FlashROM, UART, etc.)
* UART: up to 8 serial devices, which can used for UART, SPI or I2C.
* I2S: 1 I2S interfaces
* ADC: Dual 12-bit SAR ADC converter with 16 channels.
* Programming: using BootROM bootloader from USB.
For more information see the excellent SAMD21/SAMD51 data sheets or reference manuals.
At the moment, the SAM21 port of MicroPython requires 256kB flash, of which 64kB is used
for a small file system. The SAM51 port requires 512 kB of flash, of which all flash beyond
384kB is used for a file system. Some boards have additional flash memory, which can be used
as additional file space.

BIN
docs/samd/img/itsybitsy_m4_express.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 148 KiB

856
docs/samd/pinout.rst Normal file
View File

@ -0,0 +1,856 @@
.. _samd_pinout:
Pinout for the SAMD machine modules
===================================
The assignment of device functions to pins is very flexible. The same function may be used
at different pins. The representation of the assignment choices are given by a table,
which is a subset of the MCU's Pin MUX table and is specific to each board, as the
available pin set varies. The structure of the table is the same for each board, but
the set of rows is different.
.. _samd21_pinout_table:
Adafruit ItsyBitsy M0 Express pin assignment table
--------------------------------------------------
=== ==== ============ ==== ==== ====== ====== ====== ======
Pin GPIO Pin name IRQ ADC Serial Serial TCC/TC TCC/TC
=== ==== ============ ==== ==== ====== ====== ====== ======
0 PA11 D0 11 19 0/3 2/3 1/1 0/3
1 PA10 D1 10 18 0/2 2/2 1/0 0/2
2 PA14 D2 14 - 2/2 4/2 3/0 0/4
3 PA09 D3 9 17 0/1 2/1 0/1 1/3
4 PA08 D4 - 16 0/0 2/0 0/0 1/2
5 PA15 D5 15 - 2/3 4/3 3/1 0/5
7 PA21 D7 5 - 5/3 3/3 7/1 0/7
9 PA07 D9 7 7 - 0/3 1/1 -
10 PA18 D10 2 - 1/2 3/2 3/0 0/2
11 PA16 D11 0 - 1/0 3/0 2/0 0/6
12 PA19 D12 3 - 1/3 3/3 3/1 0/3
13 PA17 D13 1 - 1/1 3/1 2/1 0/7
14 PA02 A0 2 0 - - - -
15 PB08 A1 8 2 - 4/0 4/0 -
16 PB09 A2 9 3 - 4/1 4/1 -
17 PA04 A3 4 4 - 0/0 0/0 -
18 PA05 A4 5 5 - 0/1 0/1 -
19 PB02 A5 2 - - 5/0 6/0 -
20 PA22 SDA 6 - 3/0 5/0 4/0 0/4
21 PA23 SCL 7 - 3/1 5/1 4/1 0/5
22 PB10 MOSI 10 - - 4/2 5/0 0/4
23 PA12 MISO 12 - 2/0 4/0 2/0 0/6
24 PB11 SCK 11 - - 4/3 5/1 0/5
25 PA00 DOTSTAR_CLK 0 - - 1/0 2/0 -
26 PA01 DOTSTAR_DATA 1 - - 1/1 2/1 -
27 PB22 FLASH_MOSI 6 - - 5/2 7/0 -
28 PB03 FLASH_MISO 3 - - 5/1 6/1 -
29 PB23 FLASH_SCK 7 - - 5/3 7/1 -
=== ==== ============ ==== ==== ====== ====== ====== ======
Description of the columns:
- *Pin* - The number that is expected at ``machine.Pin(n)``, if the pin is given
as a number. This is NOT the GPIO number, but the board pin number, as
given in the board specific definition file.
- *GPIO* - The GPIO number.
- *Pin Name* - The name of a Pin which is expected argument to ``machine.Pin("name")``.
- *IRQ* - The IRQ number assigned to that GPIO, used internally by ``Pin.irq()``. When
using ``Pin.irq()``, different pins must use different IRQs
- *ADC* - The ADC channel assigned to the pin. When using ADC, different pins must
not use the same ADC channel.
- *Serial* - Two columns with optional Serial signal assignments. Both may be used.
The cell content is device #/pad #. The pad # is the respective internal
signal of that serial device. Details below.
- *TCC/TC* - Two columns with assignments of the TCC modules for PWM.
The cell content is device #/output #. For PWM, devices 0, 1, and 2
are used. The TC device pair 3/4 is used for ``ticks_us()``.
SAMD21 UART assignments
```````````````````````
The UART devices and signals must be chosen according to the following rules:
- The TX signal must be at a Pin with pad numbers 2 or 0, like Pin D1 with serial
device 0 or 2.
- The RX pin may be assigned to one of the other pads.
Examples for Adafruit ItsyBitsy M0 Express:
- uart 0 at pins D0/D1 This is the default UART at the RX/TX labelled pins
- uart 1 at pins D12/D10
- uart 2 at pins D0/D1
- uart 3 at pins D11/D13
- uart 4 at pins D2/D5
- uart 5 at pins SCL/SDA
or other combinations.
SAMD21 I2C assignments
``````````````````````
The I2C devices and signals must be chosen according to the following rules:
- The SDA signal must be at a Pin with pad numbers 0.
- The SCL signal must be at a Pin with pad numbers 1.
Examples for Adafruit ItsyBitsy M0 Express:
- I2C 0 at Pin A3/A4
- I2C 1 at pins D11/D13
- I2C 2 at the pins D4/D3
- I2C 3 at the pins SDA/SCL This is the default I2C device at the SDA/SCl labelled pin
- I2C 4 at the pins A1/A2
- I2C 5 at the pins SDA/SCL,
or other combinations.
SAMD21 SPI assignments
``````````````````````
The I2C devices and signals must be chosen according to the following rules:
- The following pad number pairs are suitable for MOSI/SCK: 0/1, 2/3, 3/1, and 0/3.
- The MISO signal must be at a Pin with a different pad number than MOSI or SCK.
Examples for Adafruit ItsyBitsy M0 Express:
- SPI 0 at pins D0/D4/D1
- SPI 1 at pins D11/D12/D13
- SPI 2 at pins D0/D4/D1
- SPI 3 at pins D11/D12/D13
- SPI 4 at Pin MOSI/MISO/SCK This is the default SPI device at the MOSI/MISO/SCK labelled pins.
or other combinations.
SAMD21 PWM assignments
``````````````````````
The TCC/TC device numbers 0, 1 and 2 can be used for PWM. Device 0 has four
channels, device 1 and 2 have two channels. So in total 3 different PWM
frequencies can be used, and 8 different duty cycle values.
The DAC output for the Adafruit ItsyBitsy M0 Express board is available at the pin A0.
.. _samd51_pinout_table:
Adafruit ItsyBitsy M4 Express pin assignment table
--------------------------------------------------
=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
Pin GPIO Pin name IRQ ADC ADC Serial Serial TC PWM PWM
=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
2 PA02 A0 2 0 - - - - - -
5 PA05 A1 5 5 - - 0/1 0/1 - -
40 PB08 A2 8 2 0 - 4/0 4/0 - -
41 PB09 A3 9 3 1 - 4/1 4/1 - -
4 PA04 A4 4 4 - - 0/0 0/0 - -
6 PA06 A5 6 6 - - 0/2 1/0 - -
16 PA16 D0 0 - - 1/0 3/1 2/0 1/0 0/4
17 PA17 D1 1 - - 1/1 3/0 2/1 1/1 0/5
7 PA07 D2 7 7 - - 0/3 1/1 - -
54 PB22 D3 22 - - 1/2 5/2 7/0 - -
14 PA14 D4 14 - - 2/2 4/2 3/0 2/0 1/2
15 PA15 D5 15 - - 2/3 4/3 3/1 2/1 1/3
18 PA18 D7 2 - - 1/2 3/2 3/0 1/2 0/6
19 PA19 D9 3 - - 1/3 3/3 3/1 1/3 0/7
20 PA20 D10 4 - - 5/2 3/2 7/0 1/4 0/0
21 PA21 D11 5 - - 5/3 3/3 7/1 1/5 0/1
23 PA23 D12 7 - - 3/1 5/0 4/1 1/7 0/3
22 PA22 D13 6 - - 3/0 5/1 4/0 1/6 0/2
34 PB02 DOTSTAR_CLK 2 14 - - 5/0 6/0 2/2 -
35 PB03 DOTSTAR_DATA 9 15 - - 5/1 6/1 - -
43 PB11 FLASH_CS 12 - - - 4/3 5/1 0/5 1/1
11 PA11 FLASH_HOLD 11 11 - 0/3 2/3 1/1 0/3 1/7
9 PA09 FLASH_MISO 9 9 3 0/1 2/0 0/1 0/1 1/5
8 PA08 FLASH_MOSI - 8 2 0/0 2/1 0/0 0/0 1/4
42 PB10 FLASH_SCK 10 - - - 4/2 5/0 0/4 1/0
10 PA10 FLASH_WP 10 10 - 0/2 2/2 1/0 0/2 1/6
55 PB23 MISO 7 - - 1/3 5/3 7/1 - -
0 PA00 MOSI 0 - - - 1/0 2/0 - -
1 PA01 SCK 1 - - - 1/1 2/1 - -
13 PA13 SCL 13 - - 2/1 4/0 2/1 0/7 1/3
12 PA12 SDA 12 - - 2/0 4/1 2/0 0/6 1/2
30 PA30 SWCLK 14 - - 7/2 1/2 6/0 2/0 -
31 PA31 SWDIO 15 - - 7/3 1/3 6/1 2/1 -
24 PA24 USB_DM 8 - - 3/2 5/2 5/0 2/2 -
25 PA25 USB_DP 9 - - 3/3 5/3 5/1 - -
3 PA03 - 3 10 - - - - - -
27 PA27 - 11 - - - - - - -
=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
Description of the columns:
- *Pin* - The number that is expected at ``machine.Pin(n)``, if the pin is given
as a number. This is NOT the GPIO number, but the board pin number, as
given in the board specific definition file.
- *GPIO* - The GPIO number.
- *Pin Name* The name of a Pin which is expected argument to ``machine.Pin("name")``.
- *IRQ* - The IRQ number assigned to that GPIO, used internally by ``Pin.irq()``. When
using ``Pin.irq()``, different pins must use different IRQs
- *ADC* - The ADC0/1 channel assigned to the pin. When using ADC, different pins must
not use the same ADC device and channel.
- *Serial* - Two columns with optional Serial signal assignments. Both may be used.
The cell content is device #/pad #. The pad # is the respective internal
signal of that serial device. Details below.
- *TC* - These device are currently not assigned to Pin. the TC device pair 0/1
is used for ``ticks_us()``.
- *PWM* - Two columns with assignments of the TCC modules for PWM
The cell content is device #/output #. Details below.
SAMD51 UART assignments
```````````````````````
The UART devices and signals must be chosen according to the following rules:
- The TX signal must be at a Pin with pad numbers 0, like Pin D1 with serial
device 3.
- The RX pin may be assigned to one of the other pads.
Examples for Adafruit ItsyBitsy 4 Express:
- uart 0 at pins A4/A1
- uart 1 at pins D1/D0 This is the default UART at the RX/TX labelled pins
- uart 2 at pins SCL/SDA This is the default I2C device at the SDA/SCl labelled pin
- uart 3 at pins D0/D1
- uart 4 at pins SDA/SCL
- uart 5 at pins D12/D13
or other combinations.
SAMD51 I2C assignments
``````````````````````
The I2C devices and signals must be chosen according to the following rules:
- The SDA signal must be at a Pin with pad numbers 0.
- The SCL signal must be at a Pin with pad numbers 1.
Examples for Adafruit ItsyBitsy M0 Express:
- I2C 0 at pins A3/A4
- I2C 1 at pins D0/D1
- I2C 2 at the pins SDA/SCL
- I2C 3 at the pins D1/D0
- I2C 4 at the pins A2/A3
- I2C 5 at the pins D12/D13
or other combinations.
SAMD51 SPI assignments
``````````````````````
The SPI devices and signals must be chosen according to the following rules:
- The following pad number pairs are suitable for MOSI/SCK: 0/1 and 3/1.
- The MISO signal must be at a Pin with a different pad number than MOSI or SCK.
Examples for Adafruit ItsyBitsy M0 Express:
- SPI 1 at Pin MOSI/MISO/SCK This is the default SPI device at the MOSI/MISO/SCK labelled pins.
- SPI 3 at pins D13/D11/D12
- SPI 5 at pins D12/D3/D13
or other combinations.
SAMD51 PWM assignments
``````````````````````
The TCC/PWM device numbers 0 through 4 can be used for PWM. Device 0 has six
channels, device 1 has four channels, device 2 has three channels and devices
3 and 4 have two channels. So in total up to 5 different PWM frequencies
can be used, and up to 17 different duty cycle values. Note that these numbers
do not apply to every board.
The DAC outputs for the Adafruit ItsyBitsy M4 Express board are available at the pins A0 and A1.
Adafruit Feather M4 Express pin assignment table
------------------------------------------------
=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
Pin GPIO Pin name IRQ ADC ADC Serial Serial TC PWM PWM
=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
2 PA02 A0 2 0 - - - - - -
5 PA05 A1 5 5 - - 0/1 0/1 - -
40 PB08 A2 8 2 0 - 4/0 4/0 - -
41 PB09 A3 9 3 1 - 4/1 4/1 - -
4 PA04 A4 4 4 - - 0/0 0/0 - -
38 PB06 A5 6 - 8 - - - - -
49 PB17 D0 1 - - 5/1 - 6/1 3/1 0/5
48 PB16 D1 0 - - 5/0 - 6/0 3/0 0/4
14 PA14 D4 14 - - 2/2 4/2 3/0 2/0 1/2
16 PA16 D5 0 - - 1/0 3/1 2/0 1/0 0/4
18 PA18 D6 2 - - 1/2 3/2 3/0 1/2 0/6
19 PA19 D9 3 - - 1/3 3/3 3/1 1/3 0/7
3 PA03 AREF 3 10 - - - - - -
20 PA20 D10 4 - - 5/2 3/2 7/0 1/4 0/0
21 PA21 D11 5 - - 5/3 3/3 7/1 1/5 0/1
22 PA22 D12 6 - - 3/0 5/1 4/0 1/6 0/2
23 PA23 D13 7 - - 3/1 5/0 4/1 1/7 0/3
43 PB11 FLASH_CS 12 - - - 4/3 5/1 0/5 1/1
11 PA11 FLASH_HOLD 11 11 - 0/3 2/3 1/1 0/3 1/7
9 PA09 FLASH_MISO 9 9 3 0/1 2/0 0/1 0/1 1/5
8 PA08 FLASH_MOSI - 8 2 0/0 2/1 0/0 0/0 1/4
42 PB10 FLASH_SCK 10 - - - 4/2 5/0 0/4 1/0
10 PA10 FLASH_WP 10 10 - 0/2 2/2 1/0 0/2 1/6
54 PB22 MISO 22 - - 1/2 5/2 7/0 - -
55 PB23 MOSI 7 - - 1/3 5/3 7/1 - -
35 PB03 NEOPIXEL 9 15 - - 5/1 6/1 - -
17 PA17 SCK 1 - - 1/1 3/0 2/1 1/1 0/5
13 PA13 SCL 13 - - 2/1 4/0 2/1 0/7 1/3
12 PA12 SDA 12 - - 2/0 4/1 2/0 0/6 1/2
30 PA30 SWCLK 14 - - 7/2 1/2 6/0 2/0 -
31 PA31 SWDIO 15 - - 7/3 1/3 6/1 2/1 -
24 PA24 USB_DM 8 - - 3/2 5/2 5/0 2/2 -
25 PA25 USB_DP 9 - - 3/3 5/3 5/1 - -
33 PB01 VDIV 1 13 - - 5/3 7/1 - -
0 PA00 - 0 - - - 1/0 2/0 - -
1 PA01 - 1 - - - 1/1 2/1 - -
6 PA06 - 6 6 - - 0/2 1/0 - -
7 PA07 - 7 7 - - 0/3 1/1 - -
15 PA15 - 15 - - 2/3 4/3 3/1 2/1 1/3
27 PA27 - 11 - - - - - - -
32 PB00 - 9 12 - - 5/2 7/0 - -
34 PB02 - 2 14 - - 5/0 6/0 2/2 -
36 PB04 - 4 - 6 - - - - -
37 PB05 - 5 - 7 - - - - -
39 PB07 - 7 - 9 - - - - -
44 PB12 - 12 - - 4/0 - 4/0 3/0 0/0
45 PB13 - 13 - - 4/1 - 4/1 3/1 0/1
46 PB14 - 14 - - 4/2 - 5/0 4/0 0/2
47 PB15 - 15 - - 4/3 - 5/1 4/1 0/3
62 PB30 - 14 - - 7/0 5/1 0/0 4/0 0/6
63 PB31 - 15 - - 7/1 5/0 0/1 4/1 0/7
=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
For the definition of the table columns see the explanation at the table for
Adafruit ItsyBitsy M4 Express :ref:`samd51_pinout_table`.
The default devices at the board are:
- UART 5 at pins D0/D1, labelled RX/TX
- I2C 2 at pins PA12/PA13, labelled SDA/SCL
- SPI 1 at pins PA23/PA22/PA17, labelled MOSI, MISO and SCK
- DAC output on pins PA02 and PA05, labelled A0 and A1
SEEED XIAO pin assignment table
-------------------------------
=== ==== ============ ==== ==== ====== ====== ====== ======
Pin GPIO Pin name IRQ ADC Serial Serial TCC/TC TCC/TC
=== ==== ============ ==== ==== ====== ====== ====== ======
2 PA02 A0_D0 2 0 - - - -
4 PA04 A1_D1 4 4 - 0/0 0/0 -
10 PA10 A2_D2 10 18 0/2 2/2 1/0 0/2
11 PA11 A3_D3 11 19 0/3 2/3 1/1 0/3
8 PA08 A4_D4 - 16 0/0 2/0 0/0 1/2
9 PA09 A5_D5 9 17 0/1 2/1 0/1 1/3
40 PB08 A6_D6 8 2 - 4/0 4/0 -
41 PB09 A7_D7 9 3 - 4/1 4/1 -
7 PA07 A8_D8 7 7 - 0/3 1/1 -
5 PA05 A9_D9 5 5 - 0/1 0/1 -
6 PA06 A10_D10 6 6 - 0/2 1/0 -
18 PA18 RX_LED 2 - 1/2 3/2 3/0 0/2
30 PA30 SWCLK 10 - - 1/2 1/0 -
31 PA31 SWDIO 11 - - 1/3 1/1 -
19 PA19 TX_LED 3 - 1/3 3/3 3/1 0/3
24 PA24 USB_DM 12 - 3/2 5/2 5/0 1/2
25 PA25 USB_DP 13 - 3/3 5/3 5/1 1/3
17 PA17 USER_LED 1 - 1/1 3/1 2/1 0/7
0 PA00 - 0 - - 1/0 2/0 -
1 PA01 - 1 - - 1/1 2/1 -
3 PA03 - 3 1 - - - -
12 PA12 - 12 - 2/0 4/0 2/0 0/6
13 PA13 - 13 - 2/1 4/1 2/0 0/7
14 PA14 - 14 - 2/2 4/2 3/0 0/4
15 PA15 - 15 - 2/3 4/3 3/1 0/5
16 PA16 - 0 - 1/0 3/0 2/0 0/6
20 PA20 - 4 - 5/2 3/2 7/0 0/4
21 PA21 - 5 - 5/3 3/3 7/1 0/7
22 PA22 - 6 - 3/0 5/0 4/0 0/4
23 PA23 - 7 - 3/1 5/1 4/1 0/5
27 PA27 - 15 - - - - -
28 PA28 - 8 - - - - -
34 PB02 - 2 10 - 5/0 6/0 -
35 PB03 - 3 11 - 5/1 6/1 -
42 PB10 - 10 - - 4/2 5/0 0/4
43 PB11 - 11 - - 4/3 5/1 0/5
54 PB22 - 6 - - 5/2 7/0 -
55 PB23 - 7 - - 5/3 7/1 -
=== ==== ============ ==== ==== ====== ====== ====== ======
For the definition of the table columns see the explanation at the table for
Adafruit ItsyBitsy M0 Express :ref:`samd21_pinout_table`.
The default devices at the board are:
- UART 4 at pins PB08/PB09, labelled A6_D6/A7_D7
- I2C 2 at pins PA08/PA09, labelled A4_D4/A5_D5
- SPI 0 at pins PA06/PA05/PA07, labelled A10_D10, A9_D9 and A8_D8
- DAC output on pin PA02, labelled A0_D0
Adafruit Feather M0 Express pin assignment table
------------------------------------------------
=== ==== ============ ==== ==== ====== ====== ====== ======
Pin GPIO Pin name IRQ ADC Serial Serial TCC/TC TCC/TC
=== ==== ============ ==== ==== ====== ====== ====== ======
2 PA02 A0 2 0 - - - -
40 PB08 A1 8 2 - 4/0 4/0 -
41 PB09 A2 9 3 - 4/1 4/1 -
4 PA04 A3 4 4 - 0/0 0/0 -
5 PA05 A4 5 5 - 0/1 0/1 -
34 PB02 A5 2 10 - 5/0 6/0 -
11 PA11 D0 11 19 0/3 2/3 1/1 0/3
10 PA10 D1 10 18 0/2 2/2 1/0 0/2
14 PA14 D2 14 - 2/2 4/2 3/0 0/4
9 PA09 D3 9 17 0/1 2/1 0/1 1/3
8 PA08 D4 - 16 0/0 2/0 0/0 1/2
15 PA15 D5 15 - 2/3 4/3 3/1 0/5
20 PA20 D6 4 - 5/2 3/2 7/0 0/4
21 PA21 D7 5 - 5/3 3/3 7/1 0/7
7 PA07 D9 7 7 - 0/3 1/1 -
55 PB23 RX 7 - - 5/3 7/1 -
54 PB22 TX 6 - - 5/2 7/0 -
18 PA18 D10 2 - 1/2 3/2 3/0 0/2
16 PA16 D11 0 - 1/0 3/0 2/0 0/6
19 PA19 D12 3 - 1/3 3/3 3/1 0/3
17 PA17 D13 1 - 1/1 3/1 2/1 0/7
13 PA13 FLASH_CS 13 - 2/1 4/1 2/0 0/7
35 PB03 LED_RX 3 11 - 5/1 6/1 -
27 PA27 LED_TX 15 - - - - -
12 PA12 MISO 12 - 2/0 4/0 2/0 0/6
42 PB10 MOSI 10 - - 4/2 5/0 0/4
6 PA06 NEOPIXEL 6 6 - 0/2 1/0 -
43 PB11 SCK 11 - - 4/3 5/1 0/5
23 PA23 SCL 7 - 3/1 5/1 4/1 0/5
22 PA22 SDA 6 - 3/0 5/0 4/0 0/4
30 PA30 SWCLK 10 - - 1/2 1/0 -
31 PA31 SWDIO 11 - - 1/3 1/1 -
24 PA24 USB_DM 12 - 3/2 5/2 5/0 1/2
25 PA25 USB_DP 13 - 3/3 5/3 5/1 1/3
0 PA00 - 0 - - 1/0 2/0 -
1 PA01 - 1 - - 1/1 2/1 -
3 PA03 - 3 1 - - - -
28 PA28 - 8 - - - - -
=== ==== ============ ==== ==== ====== ====== ====== ======
For the definition of the table columns see the explanation at the table for
Adafruit ItsyBitsy M0 Express :ref:`samd21_pinout_table`.
The default devices at the board are:
- UART 5 at pins PB23/PB22, labelled RX/TX
- I2C 3 at pins PA22/PA23, labelled SDA/SCL
- SPI 4 at pins PA10/PA12/PA11, labelled MOSI, MISO and SCK
- DAC output on pin PA02, labelled A0
Adafruit Trinket M0 pin assignment table
------------------------------------------------
=== ==== ============ ==== ==== ====== ====== ====== ======
Pin GPIO Pin name IRQ ADC Serial Serial TCC/TC TCC/TC
=== ==== ============ ==== ==== ====== ====== ====== ======
8 PA08 D0 - 16 0/0 2/0 0/0 1/2
2 PA02 D1 2 0 - - - -
9 PA09 D2 9 17 0/1 2/1 0/1 1/3
7 PA07 D3 7 7 - 0/3 1/1 -
6 PA06 D4 6 6 - 0/2 1/0 -
1 PA01 DOTSTAR_CLK 1 - - 1/1 2/1 -
0 PA00 DOTSTAR_DATA 0 - - 1/0 2/0 -
10 PA10 LED 10 18 0/2 2/2 1/0 0/2
30 PA30 SWCLK 10 - - 1/2 1/0 -
31 PA31 SWDIO 11 - - 1/3 1/1 -
24 PA24 USB_DM 12 - 3/2 5/2 5/0 1/2
25 PA25 USB_DP 13 - 3/3 5/3 5/1 1/3
3 PA03 - 3 1 - - - -
4 PA04 - 4 4 - 0/0 0/0 -
5 PA05 - 5 5 - 0/1 0/1 -
11 PA11 - 11 19 0/3 2/3 1/1 0/3
14 PA14 - 14 - 2/2 4/2 3/0 0/4
15 PA15 - 15 - 2/3 4/3 3/1 0/5
16 PA16 - 0 - 1/0 3/0 2/0 0/6
17 PA17 - 1 - 1/1 3/1 2/1 0/7
18 PA18 - 2 - 1/2 3/2 3/0 0/2
19 PA19 - 3 - 1/3 3/3 3/1 0/3
22 PA22 - 6 - 3/0 5/0 4/0 0/4
23 PA23 - 7 - 3/1 5/1 4/1 0/5
27 PA27 - 15 - - - - -
28 PA28 - 8 - - - - -
=== ==== ============ ==== ==== ====== ====== ====== ======
For the definition of the table columns see the explanation at the table for
Adafruit ItsyBitsy M0 Express :ref:`samd21_pinout_table`.
The default devices at the board are:
- UART 0 at pins PA07/PA06, labelled D3/D4
- I2C 2 at pins PA08/PA09, labelled D0/D2
- SPI 0 at pins PA06/PA09/PA08, labelled D4, D2 and D0
- DAC output on pin PA02, labelled D1
SAMD21 Xplained PRO pin assignment table
----------------------------------------
=== ==== ============ ==== ==== ====== ====== ====== ======
Pin GPIO Pin name IRQ ADC Serial Serial TCC/TC TCC/TC
=== ==== ============ ==== ==== ====== ====== ====== ======
32 PB00 EXT1_PIN3 0 8 - 5/2 7/0 -
33 PB01 EXT1_PIN4 1 9 - 5/3 7/1 -
38 PB06 EXT1_PIN5 6 14 - - - -
39 PB07 EXT1_PIN6 7 15 - - - -
34 PB02 EXT1_PIN7 2 10 - 5/0 6/0 -
35 PB03 EXT1_PIN8 3 11 - 5/1 6/1 -
36 PB04 EXT1_PIN9 4 12 - - - -
37 PB05 EXT1_PIN10 5 13 - - - -
8 PA08 EXT1_PIN11 - 16 0/0 2/0 0/0 1/2
9 PA09 EXT1_PIN12 9 17 0/1 2/1 0/1 1/3
41 PB09 EXT1_PIN13 9 3 - 4/1 4/1 -
40 PB08 EXT1_PIN14 8 2 - 4/0 4/0 -
5 PA05 EXT1_PIN15 5 5 - 0/1 0/1 -
6 PA06 EXT1_PIN16 6 6 - 0/2 1/0 -
4 PA04 EXT1_PIN17 4 4 - 0/0 0/0 -
7 PA07 EXT1_PIN18 7 7 - 0/3 1/1 -
10 PA10 EXT2_PIN3 10 18 0/2 2/2 1/0 0/2
11 PA11 EXT2_PIN4 11 19 0/3 2/3 1/1 0/3
20 PA20 EXT2_PIN5 4 - 5/2 3/2 7/0 0/4
21 PA21 EXT2_PIN6 5 - 5/3 3/3 7/1 0/7
44 PB12 EXT2_PIN7 12 - 4/0 - 4/0 0/6
45 PB13 EXT2_PIN8 13 - 4/1 - 4/1 0/7
46 PB14 EXT2_PIN9 14 - 4/2 - 5/0 -
47 PB15 EXT2_PIN10 15 - 4/3 - 5/1 -
43 PB11 EXT2_PIN13 11 - - 4/3 5/1 0/5
42 PB10 EXT2_PIN14 10 - - 4/2 5/0 0/4
17 PA17 EXT2_PIN15 1 - 1/1 3/1 2/1 0/7
18 PA18 EXT2_PIN16 2 - 1/2 3/2 3/0 0/2
16 PA16 EXT2_PIN17 0 - 1/0 3/0 2/0 0/6
19 PA19 EXT2_PIN18 3 - 1/3 3/3 3/1 0/3
2 PA02 EXT3_PIN3 2 0 - - - -
3 PA03 EXT3_PIN4 3 1 - - - -
15 PA15 EXT3_PIN6 15 - 2/3 4/3 3/1 0/5
12 PA12 EXT3_PIN7 12 - 2/0 4/0 2/0 0/6
13 PA13 EXT3_PIN8 13 - 2/1 4/1 2/0 0/7
28 PA28 EXT3_PIN9 8 - - - - -
27 PA27 EXT3_PIN10 15 - - - - -
49 PB17 EXT3_PIN15 1 - 5/1 - 6/1 0/5
54 PB22 EXT3_PIN16 6 - - 5/2 7/0 -
48 PB16 EXT3_PIN17 9 - 5/0 - 6/0 0/4
55 PB23 EXT3_PIN18 7 - - 5/3 7/1 -
62 PB30 LED 14 - - 5/0 0/0 1/2
30 PA30 SWCLK 10 - - 1/2 1/0 -
31 PA31 SWDIO 11 - - 1/3 1/1 -
24 PA24 USB_DM 12 - 3/2 5/2 5/0 1/2
25 PA25 USB_DP 13 - 3/3 5/3 5/1 1/3
0 PA00 - 0 - - 1/0 2/0 -
1 PA01 - 1 - - 1/1 2/1 -
14 PA14 - 14 - 2/2 4/2 3/0 0/4
22 PA22 - 6 - 3/0 5/0 4/0 0/4
23 PA23 - 7 - 3/1 5/1 4/1 0/5
63 PB31 - 15 - - 5/1 0/1 1/3
=== ==== ============ ==== ==== ====== ====== ====== ======
For the definition of the table columns see the explanation at the table for
Adafruit ItsyBitsy M0 Express :ref:`samd21_pinout_table`.
There are no pins labelled for default devices on this board. DAC output
is on pin PA02, labelled EXT3_PIN3
Minisam M4 pin assignment table
-------------------------------
=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
Pin GPIO Pin name IRQ ADC ADC Serial Serial TC PWM PWM
=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
16 PA16 D0 0 - - 1/0 3/1 2/0 1/0 0/4
17 PA17 D1 1 - - 1/1 3/0 2/1 1/1 0/5
19 PA19 D3 3 - - 1/3 3/3 3/1 1/3 0/7
20 PA20 D4 4 - - 5/2 3/2 7/0 1/4 0/0
21 PA21 D5 5 - - 5/3 3/3 7/1 1/5 0/1
2 PA02 A0_D9 2 0 - - - - - -
40 PB08 A1_D10 8 2 0 - 4/0 4/0 - -
41 PB09 A2_D11 9 3 1 - 4/1 4/1 - -
4 PA04 A3_D12 4 4 - - 0/0 0/0 - -
5 PA05 A4_D13 5 5 - - 0/1 0/1 - -
6 PA06 A5 6 6 - - 0/2 1/0 - -
7 PA07 A6_D2 7 7 - - 0/3 1/1 - -
3 PA03 AREF 3 10 - - - - - -
0 PA00 BUTTON 0 - - - 1/0 2/0 - -
34 PB02 DOTSTAR_CLK 2 14 - - 5/0 6/0 2/2 -
35 PB03 DOTSTAR_DATA 9 15 - - 5/1 6/1 - -
15 PA15 LED 15 - - 2/3 4/3 3/1 2/1 1/3
55 PB23 MISO 7 - - 1/3 5/3 7/1 - -
54 PB22 MOSI 22 - - 1/2 5/2 7/0 - -
1 PA01 SCK 1 - - - 1/1 2/1 - -
13 PA13 SCL 13 - - 2/1 4/0 2/1 0/7 1/3
12 PA12 SDA 12 - - 2/0 4/1 2/0 0/6 1/2
30 PA30 SWCLK 14 - - 7/2 1/2 6/0 2/0 -
31 PA31 SWDIO 15 - - 7/3 1/3 6/1 2/1 -
24 PA24 USB_DM 8 - - 3/2 5/2 5/0 2/2 -
25 PA25 USB_DP 9 - - 3/3 5/3 5/1 - -
8 PA08 - - 8 2 0/0 2/1 0/0 0/0 1/4
9 PA09 - 9 9 3 0/1 2/0 0/1 0/1 1/5
10 PA10 - 10 10 - 0/2 2/2 1/0 0/2 1/6
11 PA11 - 11 11 - 0/3 2/3 1/1 0/3 1/7
14 PA14 - 14 - - 2/2 4/2 3/0 2/0 1/2
18 PA18 - 2 - - 1/2 3/2 3/0 1/2 0/6
22 PA22 - 6 - - 3/0 5/1 4/0 1/6 0/2
23 PA23 - 7 - - 3/1 5/0 4/1 1/7 0/3
27 PA27 - 11 - - - - - - -
42 PB10 - 10 - - - 4/2 5/0 0/4 1/0
43 PB11 - 12 - - - 4/3 5/1 0/5 1/1
=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
For the definition of the table columns see the explanation at the table for
Adafruit ItsyBitsy M4 Express :ref:`samd51_pinout_table`.
The default devices at the board are:
- UART 1 at pins PA16/PA17, labelled D0/D1
- I2C 2 at pins PA12/PA13, labelled SDA/SCL
- SPI 1 at pins PB22/PB23/PA01, labelled MOSI, MISO and SCK
- DAC output on pins PA02 and PA05, labelled A0_D9 and A4_D13
Seeed WIO Terminal pin assignment table
---------------------------------------
=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
Pin GPIO Pin name IRQ ADC ADC Serial Serial TC PWM PWM
=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
33 PB01 CS 1 13 - - 5/3 7/1 - -
59 PB27 RX 13 - - 2/1 4/0 - 1/3 -
58 PB26 TX 12 - - 2/0 4/1 - 1/2 -
79 PC15 3V3_ENABLE 15 - - 7/3 6/3 - 0/5 1/1
78 PC14 5V_ENABLE 14 - - 7/2 6/2 - 0/4 1/0
40 PB08 A0_D0 8 2 0 - 4/0 4/0 - -
41 PB09 A1_D1 9 3 1 - 4/1 4/1 - -
7 PA07 A2_D2 7 7 - - 0/3 1/1 - -
36 PB04 A3_D3 4 - 6 - - - - -
37 PB05 A4_D4 5 - 7 - - - - -
38 PB06 A5_D5 6 - 8 - - - - -
4 PA04 A6_D6 4 4 - - 0/0 0/0 - -
39 PB07 A7_D7 7 - 9 - - - - -
6 PA06 A8_D8 6 6 - - 0/2 1/0 - -
90 PC26 BUTTON_1 10 - - - - - - -
91 PC27 BUTTON_2 11 - - 1/0 - - - -
92 PC28 BUTTON_3 12 - - 1/1 - - - -
107 PD11 BUZZER 6 - - 7/3 6/3 - 0/4 -
47 PB15 GPCLK0 15 - - 4/3 - 5/1 4/1 0/3
44 PB12 GPCLK1 12 - - 4/0 - 4/0 3/0 0/0
45 PB13 GPCLK2 13 - - 4/1 - 4/1 3/1 0/1
48 PB16 I2C_BCLK 0 - - 5/0 - 6/0 3/0 0/4
20 PA20 I2S_LRCLK 4 - - 5/2 3/2 7/0 1/4 0/0
21 PA21 I2S_SDIN 5 - - 5/3 3/3 7/1 1/5 0/1
22 PA22 I2S_SDOUT 6 - - 3/0 5/1 4/0 1/6 0/2
50 PB18 LCD_MISO 2 - - 5/2 7/2 - 1/0 -
51 PB19 LCD_MOSI 3 - - 5/3 7/3 - 1/1 -
52 PB20 LCD_SCK 4 - - 3/0 7/1 - 1/2 -
53 PB21 LCD_CS 5 - - 3/1 7/0 - 1/3 -
70 PC06 LCD_D/C 6 - - 6/2 - - - -
71 PC07 LCD_RESET 9 - - 6/3 - - - -
74 PC10 LCD_XL 10 - - 6/2 7/2 - 0/0 1/4
76 PC12 LCD_XR 12 - - 7/0 6/1 - 0/2 1/6
77 PC13 LCD_YD 13 - - 7/1 6/0 - 0/3 1/7
75 PC11 LCD_YU 11 - - 6/3 7/3 - 0/1 1/5
15 PA15 LED_BLUE 15 - - 2/3 4/3 3/1 2/1 1/3
69 PC05 LED_LCD 5 - - 6/1 - - - -
94 PC30 MIC 14 - 12 - - - - -
32 PB00 MISO 9 12 - - 5/2 7/0 - -
34 PB02 MOSI 2 14 - - 5/0 6/0 2/2 -
35 PB03 SCK 9 15 - - 5/1 6/1 - -
12 PA12 SCL0 12 - - 2/0 4/1 2/0 0/6 1/2
13 PA13 SDA0 13 - - 2/1 4/0 2/1 0/7 1/3
16 PA16 SCL1 0 - - 1/0 3/1 2/0 1/0 0/4
17 PA17 SDA1 1 - - 1/1 3/0 2/1 1/1 0/5
117 PD21 SD_DET 11 - - 1/3 3/3 - 1/1 -
83 PC19 SD_CS 3 - - 6/3 0/3 - 0/3 -
82 PC18 SD_MISO 2 - - 6/2 0/2 - 0/2 -
80 PC16 SD_MOSI 0 - - 6/0 0/1 - 0/0 -
81 PC17 SD_SCK 1 - - 6/1 0/0 - 0/1 -
30 PA30 SWCLK 14 - - 7/2 1/2 6/0 2/0 -
31 PA31 SWDIO 15 - - 7/3 1/3 6/1 2/1 -
108 PD12 SWITCH_B 7 - - - - - 0/5 -
116 PD20 SWITCH_U 10 - - 1/2 3/2 - 1/0 -
104 PD08 SWITCH_X 3 - - 7/0 6/1 - 0/1 -
105 PD09 SWITCH_Y 4 - - 7/1 6/0 - 0/2 -
106 PD10 SWITCH_Z 5 - - 7/2 6/2 - 0/3 -
24 PA24 USB_DM 8 - - 3/2 5/2 5/0 2/2 -
25 PA25 USB_DP 9 - - 3/3 5/3 5/1 - -
0 PA00 - 0 - - - 1/0 2/0 - -
1 PA01 - 1 - - - 1/1 2/1 - -
2 PA02 - 2 0 - - - - - -
3 PA03 - 3 10 - - - - - -
5 PA05 - 5 5 - - 0/1 0/1 - -
8 PA08 - - 8 2 0/0 2/1 0/0 0/0 1/4
9 PA09 - 9 9 3 0/1 2/0 0/1 0/1 1/5
10 PA10 - 10 10 - 0/2 2/2 1/0 0/2 1/6
11 PA11 - 11 11 - 0/3 2/3 1/1 0/3 1/7
14 PA14 - 14 - - 2/2 4/2 3/0 2/0 1/2
18 PA18 - 2 - - 1/2 3/2 3/0 1/2 0/6
19 PA19 - 3 - - 1/3 3/3 3/1 1/3 0/7
23 PA23 - 7 - - 3/1 5/0 4/1 1/7 0/3
27 PA27 - 11 - - - - - - -
42 PB10 - 10 - - - 4/2 5/0 0/4 1/0
43 PB11 - 12 - - - 4/3 5/1 0/5 1/1
46 PB14 - 14 - - 4/2 - 5/0 4/0 0/2
49 PB17 - 1 - - 5/1 - 6/1 3/1 0/5
54 PB22 - 22 - - 1/2 5/2 7/0 - -
55 PB23 - 7 - - 1/3 5/3 7/1 - -
56 PB24 - 8 - - 0/0 2/1 - - -
57 PB25 - 9 - - 0/1 2/0 - - -
60 PB28 - 14 - - 2/2 4/2 - 1/4 -
61 PB29 - 15 - - 2/3 4/3 - 1/5 -
62 PB30 - 14 - - 7/0 5/1 0/0 4/0 0/6
63 PB31 - 15 - - 7/1 5/0 0/1 4/1 0/7
64 PC00 - 0 - 10 - - - - -
65 PC01 - 1 - 11 - - - - -
66 PC02 - 2 - 4 - - - - -
67 PC03 - 3 - 5 - - - - -
68 PC04 - 4 - - 6/0 - - 0/0 -
84 PC20 - 4 - - - - - 0/4 -
85 PC21 - 5 - - - - - 0/5 -
86 PC22 - 6 - - 1/0 3/1 - 0/5 -
87 PC23 - 7 - - 1/1 3/0 - 0/7 -
88 PC24 - 8 - - 0/2 2/2 - - -
89 PC25 - 9 - - 0/3 2/3 - - -
95 PC31 - 15 - 13 - - - - -
96 PD00 - 0 - 14 - - - - -
97 PD01 - 1 - 15 - - - - -
=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
For the definition of the table columns see the explanation at the table for
Adafruit ItsyBitsy M4 Express :ref:`samd51_pinout_table`.
Default pin assignments:
- UART 2 at pins PB27 and PB26, labelled RX and TX
- I2C 4 at pins PA12 and PA13, labelled SCL0 and SDA0
- I2C 3 at pins PA16 and PA17, labelled SCL1 and SDA1
- SPI 5 at pins PB00, PB02 and PB03, labelle MISO, MOSI and SCK
There seems to be no default pin assignment for this board.
Sparkfun SAMD51 Thing Plus pin assignment table
------------------------------------------------
=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
Pin GPIO Pin name IRQ ADC ADC Serial Serial TC PWM PWM
=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
2 PA02 A0 2 0 - - - - - -
40 PB08 A1 8 2 0 - 4/0 4/0 - -
41 PB09 A2 9 3 1 - 4/1 4/1 - -
4 PA04 A3 4 4 - - 0/0 0/0 - -
5 PA05 A4 5 5 - - 0/1 0/1 - -
34 PB02 A5 2 14 - - 5/0 6/0 2/2 -
13 PA13 D0 13 - - 2/1 4/0 2/1 0/7 1/3
12 PA12 D1 12 - - 2/0 4/1 2/0 0/6 1/2
6 PA06 D4 6 6 - - 0/2 1/0 - -
15 PA15 D5 15 - - 2/3 4/3 3/1 2/1 1/3
20 PA20 D6 4 - - 5/2 3/2 7/0 1/4 0/0
21 PA21 D7 5 - - 5/3 3/3 7/1 1/5 0/1
7 PA07 D9 7 7 - - 0/3 1/1 - -
18 PA18 D10 2 - - 1/2 3/2 3/0 1/2 0/6
16 PA16 D11 0 - - 1/0 3/1 2/0 1/0 0/4
19 PA19 D12 3 - - 1/3 3/3 3/1 1/3 0/7
17 PA17 D13 1 - - 1/1 3/0 2/1 1/1 0/5
10 PA10 FLASH_CS 10 10 - 0/2 2/2 1/0 0/2 1/6
11 PA11 FLASH_MISO 11 11 - 0/3 2/3 1/1 0/3 1/7
8 PA08 FLASH_MOSI - 8 2 0/0 2/1 0/0 0/0 1/4
9 PA09 FLASH_SCK 9 9 3 0/1 2/0 0/1 0/1 1/5
43 PB11 MISO 12 - - - 4/3 5/1 0/5 1/1
44 PB12 MOSI 12 - - 4/0 - 4/0 3/0 0/0
55 PB23 RXD 7 - - 1/3 5/3 7/1 - -
35 PB03 RXLED 9 15 - - 5/1 6/1 - -
45 PB13 SCK 13 - - 4/1 - 4/1 3/1 0/1
23 PA23 SCL 7 - - 3/1 5/0 4/1 1/7 0/3
22 PA22 SDA 6 - - 3/0 5/1 4/0 1/6 0/2
30 PA30 SWCLK 14 - - 7/2 1/2 6/0 2/0 -
31 PA31 SWDIO 15 - - 7/3 1/3 6/1 2/1 -
54 PB22 TXD 22 - - 1/2 5/2 7/0 - -
27 PA27 TXLED 11 - - - - - - -
24 PA24 USB_DM 8 - - 3/2 5/2 5/0 2/2 -
25 PA25 USB_DP 9 - - 3/3 5/3 5/1 - -
0 PA00 - 0 - - - 1/0 2/0 - -
1 PA01 - 1 - - - 1/1 2/1 - -
3 PA03 - 3 10 - - - - - -
14 PA14 - 14 - - 2/2 4/2 3/0 2/0 1/2
32 PB00 - 9 12 - - 5/2 7/0 - -
33 PB01 - 1 13 - - 5/3 7/1 - -
36 PB04 - 4 - 6 - - - - -
37 PB05 - 5 - 7 - - - - -
38 PB06 - 6 - 8 - - - - -
39 PB07 - 7 - 9 - - - - -
42 PB10 - 10 - - - 4/2 5/0 0/4 1/0
46 PB14 - 14 - - 4/2 - 5/0 4/0 0/2
47 PB15 - 15 - - 4/3 - 5/1 4/1 0/3
48 PB16 - 0 - - 5/0 - 6/0 3/0 0/4
49 PB17 - 1 - - 5/1 - 6/1 3/1 0/5
62 PB30 - 14 - - 7/0 5/1 0/0 4/0 0/6
63 PB31 - 15 - - 7/1 5/0 0/1 4/1 0/7
=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
For the definition of the table columns see the explanation at the table for
Adafruit ItsyBitsy M4 Express :ref:`samd51_pinout_table`.
The default devices at the board are:
- UART 1 at pins PB23/PB22, labelled RXD/TXD
- I2C 5 at pins PA22/PA23, labelled SDA/SCL
- SPI 4 at pins PB12/PB11/PB13, labelled MOSI, MISO and SCK
- DAC output on pins PA02 and PA05, labelled A0 and A4
Scripts for creating the pin assignment tables
----------------------------------------------
The tables shown above were created with small a Python script running on the target board::
from samd import pininfo
from machine import Pin
import os
def print_entry(e, txt):
print(txt, end=": ")
if e == 255:
print(" - ", end="")
else:
print("%d/%d" % (e >> 4, e & 0x0f), end="")
def print_pininfo(pin, info):
print("%3d" % pin, end=" ")
print("P%c%02d" % ("ABCD"[pin // 32], pin % 32), end="")
print(" %12s" % info[0], end="")
print(" IRQ:%2s" % (info[1] if info[1] != 255 else "-"), end="")
print(" ADC0:%2s" % (info[2] if info[2] != 255 else "-"), end="")
if len(info) == 7:
print_entry(info[3], " Serial1")
print_entry(info[4], " Serial2")
print_entry(info[5], " PWM1" if (info[5] >> 4) < 3 else " TC")
print_entry(info[6], " PWM2")
else:
print(" ADC1:%2s" % (info[3] if info[3] != 255 else "-"), end="")
print_entry(info[4], " Serial1")
print_entry(info[5], " Serial2")
print_entry(info[6], " TC")
print_entry(info[7], " PWM1")
print_entry(info[8], " PWM2")
print()
def tblkey(i):
name = i[1][0]
if name != "-":
if len(name) < 3:
return " " + name
else:
return name
else:
return "zzzzzzz%03d" % i[0]
def table(num = 127):
pintbl = []
for i in range(num):
try:
pintbl.append((i, pininfo(i)))
except:
pass
# print("not defined")
pintbl.sort(key=tblkey)
for item in pintbl:
print_pininfo(item[0], item[1])
table()

519
docs/samd/quickref.rst Normal file
View File

@ -0,0 +1,519 @@
.. _samd_quickref:
Quick reference for the SAMD21/SAMD51 family
============================================
.. image:: img/itsybitsy_m4_express.jpg
:alt: Adafruit ItsyBitsy M4 Express board
:width: 640px
The Adafruit ItsyBitsy M4 Express board.
Below is a quick reference for SAMD21/SAMD51-based boards. If it is your first time
working with this board it may be useful to get an overview of the microcontroller:
.. toctree::
:maxdepth: 1
general.rst
tutorial/intro.rst
pinout.rst
Installing MicroPython
----------------------
See the corresponding section of tutorial: :ref:`samd_intro`. It also includes
a troubleshooting subsection.
General board control
---------------------
The MicroPython REPL is on the USB port, configured in VCP mode.
Tab-completion is useful to find out what methods an object has.
Paste mode (Ctrl-E) is useful to paste a large slab of Python code into
the REPL.
The :mod:`machine` module::
import machine
machine.freq() # get the current frequency of the CPU
machine.freq(96_000_000) # set the CPU frequency to 96 MHz
The range accepted by the function call is 1_000_000 to 200_000_000 (1 MHz to 200 MHz)
for SAMD51 and 1_000_000 to 54_000_000 (1 MHz to 54 MHz) for SAMD21. The safe
range for SAMD51 according to the data sheet is up to 120 MHz, for the SAMD21 up to 48Mhz.
Frequencies below 48Mhz are set by dividing 48Mhz by an integer, limiting the number of
discrete frequencies to 24Mhz, 16Mhz, 12MHz, and so on.
At frequencies below 8 MHz USB will be disabled. Changing the frequency below 48 MHz
impacts the baud rates of UART, I2C and SPI. These have to be set again after
changing the CPU frequency. The ms and µs timers are not affected by the frequency
change.
Delay and timing
----------------
Use the :mod:`time <time>` module::
import time
time.sleep(1) # sleep for 1 second
time.sleep_ms(500) # sleep for 500 milliseconds
time.sleep_us(10) # sleep for 10 microseconds
start = time.ticks_ms() # get millisecond counter
delta = time.ticks_diff(time.ticks_ms(), start) # compute time difference
Clock and time
--------------
Two groups of functions are provided for time information. All boards have the
datetime(), mktime() and time() functions. Boards with a 32kHz crystal also
provide an RTC() module. The epoch start date is 1.1.2000.
Use the :mod:`time <time>` module::
import time
date_time = time.localtime() # Show the actual date/time information
date_time = time.localtime(seconds) # decode the date/time form the seconds value
seconds = time.mktime(date_time_tuple) # Convert seconds to a datetime tuple
second = time.time() # Return the actual system time.
The format of the date_time tuple follows the standard. The µs value of the date_time
tuple is ignored. On boards without the RTC module, time.localtime(seconds) sets the
system time. Use of the Use the :mod:`RTC <RTC>` module::
from machine import RTC
rtc = RTC()
date_time = rtc.datetime() # return the actual date & time.
rtc.datetime(date_time_tuple) # Set date & time, ignoring weekday
date_time = rtc.now() # Return date & time in Unix order.
rtc.calibration(value) # Set a calibration factor
The weekday value set will be ignored and calculated in the returned tuple from the
actual date. rtc.now() is only provided at SAMD51 boards. The value used in the
rtc.calibration() call has a range from -127 - 127. It defines roughly a
ppm quantity, by which the clock can run faster or slower.
Timers
------
The SAMD21/SAMD51 uses software timers. Use the :ref:`machine.Timer <machine.Timer>` class::
from machine import Timer
tim0 = Timer()
tim0.init(period=5000, mode=Timer.ONE_SHOT, callback=lambda t:print(0))
tim1 = Timer()
tim1.init(period=2000, mode=Timer.PERIODIC, callback=lambda t:print(1))
The period is in milliseconds.
.. _samd_Pins_and_GPIO:
Pins and GPIO
-------------
Use the :ref:`machine.Pin <machine.Pin>` class::
from machine import Pin
p0 = Pin('D0', Pin.OUT) # create output pin on GPIO0
p0.on() # set pin to "on" (high) level
p0.off() # set pin to "off" (low) level
p0.value(1) # set pin to on/high
p2 = Pin('D2', Pin.IN) # create input pin on GPIO2
print(p2.value()) # get value, 0 or 1
p4 = Pin('D4', Pin.IN, Pin.PULL_UP) # enable internal pull-up resistor
p7 = Pin("PA07", Pin.OUT, value=1) # set pin high on creation
Pins can be denoted by a string or a number. The string is either the
pin label of the respective board, like "D0" or "SDA", or in the form
"Pxnn", where x is A,B,C or D, and nn a two digit number in the range 0-31.
Examples: "PA03", PD31".
Pin numbers are the MCU port numbers in the range::
PA0..PA31: 0..31
PB0..PB31: 32..63
PC0..PC31: 64..95
PD0..PD31: 96..127
Note: On Adafruit Feather and ItsyBity boards, pin D5 is connected to an external
gate output and can therefore only be used as input.
UART (serial bus)
-----------------
See :ref:`machine.UART <machine.UART>`. ::
# Use UART 3 on a ItsyBitsy M4 board
from machine import UART
uart3 = UART(3, tx=Pin(1), rx=Pin(0), baudrate=115200)
uart3.write('hello') # write 5 bytes
uart3.read(5) # read up to 5 bytes
The SAMD21/SAMD51 MCUs have up to eight hardware so called SERCOM devices, which can be used as UART,
SPI or I2C device, but not every MCU variant and board exposes all
TX and RX pins for users. For the assignment of Pins to devices and UART signals,
refer to the :ref:`SAMD pinout <samd_pinout>`.
PWM (pulse width modulation)
----------------------------
Up to five timer device of the SAMD21/SAMD51 MCUs are used for creating PWM signals.
The PWM functions are provided by the :ref:`machine.PWM <machine.PWM>` class.
It supports all basic methods listed for that class. ::
# Samples for Adafruit ItsyBitsy M4 Express
from machine import Pin, PWM
pwm = PWM(Pin(7)) # create PWM object from a pin
pwm.freq() # get current frequency
pwm.freq(1000) # set frequency
pwm.duty_u16() # get current duty cycle, range 0-65535
pwm.duty_u16(200) # set duty cycle, range 0-65535
pwm.deinit() # turn off PWM on the pin
pwm # show the PWM objects properties
PWM Constructor
```````````````
.. class:: PWM(dest, freq, duty_u16, duty_ns, *, invert, device)
:noindex:
Construct and return a new PWM object using the following parameters:
- *dest* is the Pin object on which the PWM is output.
PWM objects are provided by TCC timer module. The TCC timer modules have up
to six channels and eight outputs. All channels of a module run at the same
frequency, but allow for different duty cycles. Outputs are assigned to channels
in modulo-n fashion, where n is the number of channels. Outputs of a channel
have the same frequency and duty rate, but may have different polarity.
So if for instance a module has four channels, output 0 and 4, 1 and 5,
2 and 6, 3, and 7 share the same frequency and duty rate.
Only one of *duty_u16* and *duty_ns* should be specified at a time.
Keyword arguments:
- *freq* should be an integer which sets the frequency in Hz for the
PWM cycle. The valid frequency range is 1 Hz to 24 MHz.
- *duty_u16* sets the duty cycle as a ratio ``duty_u16 / 65536``.
The duty cycle of a X channel can only be changed, if the A and B channel
of the respective submodule is not used. Otherwise the duty_16 value of the
X channel is 32768 (50%).
- *duty_ns* sets the pulse width in nanoseconds. The limitation for X channels
apply as well.
- *invert*\=True|False. Setting a bit inverts the respective output.
- *device*\=n Use TCC module n if available. At some pins two TCC modules could be
used. If not device is mentioned, the software tries to use a module which is not yet
used for a PWM signal. But if pins shall have the same frequency and/or duty cycle
to be changed synchronously, they must be driven by the same TCC module.
PWM Methods
```````````
The methods are identical to the generic :ref:`machine.PWM <machine.PWM>` class,
with additional keyword arguments to the init() method, matchings those of the constructor.
PWM Pin Assignment
``````````````````
Pins are specified in the same way as for the Pin class. For the assignment of Pins
to PWM signals, refer to the :ref:`SAMD pinout <samd_pinout>`.
ADC (analog to digital conversion)
----------------------------------
On the SAMD21/SAMD51 ADC functionality is available on Pins labelled 'Ann'.
Use the :ref:`machine.ADC <machine.ADC>` class::
from machine import ADC
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 12 bit with 12 bit accuracy, irrespective of the
value returned by read_u16(). If you need a higher resolution or better accuracy, use
an external ADC.
ADC Constructor
```````````````
.. class:: ADC(dest, *, average=16, vref=n)
:noindex:
Construct and return a new ADC object using the following parameters:
- *dest* is the Pin object on which the ADC is output.
Keyword arguments:
- *average* is used to reduce the noise. With a value of 16 the LSB noise is about 1 digit.
- *vref* sets the reference voltage for the ADC.
The default setting is for 3.3V. Other values are:
==== ============================== ===============================
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
==== ============================== ===============================
ADC Methods
```````````
.. method:: read_u16()
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)
----------------------------------
The DAC class provides a fast digital to analog 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, SAMD51 devices have 2 DAC channels at GPIO PA02 and PA05.
DAC Constructor
```````````````
.. class:: DAC(id, *, vref=3)
:noindex:
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
==== ============================ ================================
DAC Methods
```````````
.. method:: write(value)
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.
Software SPI bus
----------------
Software SPI (using bit-banging) works on all pins, and is accessed via the
:ref:`machine.SoftSPI <machine.SoftSPI>` class. ::
from machine import Pin, SoftSPI
# construct a SoftSPI bus on the given pins
# polarity is the idle state of SCK
# phase=0 means sample on the first edge of SCK, phase=1 means the second
spi = SoftSPI(baudrate=100000, polarity=1, phase=0, sck=Pin(7), mosi=Pin(9), miso=Pin(10))
spi.init(baudrate=200000) # set the baud rate
spi.read(10) # read 10 bytes on MISO
spi.read(10, 0xff) # read 10 bytes while outputting 0xff on MOSI
buf = bytearray(50) # create a buffer
spi.readinto(buf) # read into the given buffer (reads 50 bytes in this case)
spi.readinto(buf, 0xff) # read into the given buffer and output 0xff on MOSI
spi.write(b'12345') # write 5 bytes on MOSI
buf = bytearray(4) # create a buffer
spi.write_readinto(b'1234', buf) # write to MOSI and read from MISO into the buffer
spi.write_readinto(buf, buf) # write buf to MOSI and read MISO back into buf
The highest supported baud rate is 500000.
Hardware SPI bus
----------------
The SAMD21/SAMD51 MCUs have up to eight hardware so called SERCOM devices, which can be used as UART,
SPI or I2C device, but not every MCU variant and board exposes all
signal pins for users. Hardware SPI is accessed via the
:ref:`machine.SPI <machine.SPI>` class and has the same methods as software SPI above::
from machine import SPI
spi = SPI(1, sck=Pin("SCK"), mosi=Pin("MOSI"), miso=Pin("MISO"), baudrate=10000000)
spi.write('Hello World')
If miso is not specified, it is not used. For the assignment of Pins to SPI devices and signals, refer to
:ref:`SAMD pinout <samd_pinout>`.
Note: Even if the highest reliable baud rate at the moment is about 24 Mhz,
setting a baud rate will not always result in exactly that frequency, especially
at high baud rates.
Software I2C bus
----------------
Software I2C (using bit-banging) works on all output-capable pins, and is
accessed via the :ref:`machine.SoftI2C <machine.SoftI2C>` class::
from machine import Pin, SoftI2C
i2c = SoftI2C(scl=Pin(10), sda=Pin(11), freq=100000)
i2c.scan() # scan for devices
i2c.readfrom(0x3a, 4) # read 4 bytes from device with address 0x3a
i2c.writeto(0x3a, '12') # write '12' to device with address 0x3a
buf = bytearray(10) # create a buffer with 10 bytes
i2c.writeto(0x3a, buf) # write the given buffer to the slave
The highest supported freq is 400000.
Hardware I2C bus
----------------
The SAMD21/SAMD51 MCUs have up to eight hardware so called SERCOM devices,
which can be used as UART, SPI or I2C device, but not every MCU variant
and board exposes all signal pins for users.
For the assignment of Pins to devices and I2C signals, refer to :ref:`SAMD pinout <samd_pinout>`.
Hardware I2C is accessed via the :ref:`machine.I2C <machine.I2C>` class and
has the same methods as software SPI above::
from machine import I2C
i2c = I2C(2, scl=Pin("SCL"), sda=Pin("SDA"), freq=400_000)
i2c.writeto(0x76, b"Hello World")
OneWire driver
--------------
The OneWire driver is implemented in software and works on all pins::
from machine import Pin
import onewire
ow = onewire.OneWire(Pin(12)) # create a OneWire bus on GPIO12
ow.scan() # return a list of devices on the bus
ow.reset() # reset the bus
ow.readbyte() # read a byte
ow.writebyte(0x12) # write a byte on the bus
ow.write('123') # write bytes on the bus
ow.select_rom(b'12345678') # select a specific device by its ROM code
There is a specific driver for DS18S20 and DS18B20 devices::
import time, ds18x20
ds = ds18x20.DS18X20(ow)
roms = ds.scan()
ds.convert_temp()
time.sleep_ms(750)
for rom in roms:
print(ds.read_temp(rom))
Be sure to put a 4.7k pull-up resistor on the data line. Note that
the ``convert_temp()`` method must be called each time you want to
sample the temperature.
DHT driver
----------
The DHT driver is implemented in software and works on all pins::
import dht
import machine
d = dht.DHT11(machine.Pin(4))
d.measure()
d.temperature() # eg. 23 (°C)
d.humidity() # eg. 41 (% RH)
d = dht.DHT22(machine.Pin(4))
d.measure()
d.temperature() # eg. 23.6 (°C)
d.humidity() # eg. 41.3 (% RH)
Be sure to have a 4.7k pull-up resistor on the data line. Some
DHT modules may already have one.
Driving an APA102 LED
---------------------
The APA102 on some Adafruit boards can be controlled using SoftSPI::
from machine import SoftSPI, Pin
# create the SPI object. miso can be any unused pin.
spi=SoftSPI(sck=Pin(25), mosi=Pin(26), miso=Pin(14))
# define a little function that writes the data with
# preamble and postfix
def write(red, green, blue):
spi.write(b"\x00\x00\x00\x00\xff")
spi.write(bytearray((blue, green, red)))
spi.write(b"\xff\xff\xff")
# set the LED to red
write(128, 0, 0)
Since SoftSPI does not allow miso to be undefined, miso has to be
assigned to an otherwise unused pin.
Driving a Neopixel LED
----------------------
The built-in machine.bitstream() method supports driving Neopixel LEDs in combination
with the Neopixel driver from the MicroPython driver library::
import neopixel
import machine
# 1 LED connected to Pin D8 on Adafruit Feather boards
p = machine.Pin(8, machine.Pin.OUT)
n = neopixel.NeoPixel(p, 1)
# set the led to red.
n[0] = (128, 0, 0)
# Update the LED.
n.write()
machine.bitstream() is set up for a SAMD21 clock frequency of 48MHz and a SAMD51
clock frequency of 120 MHz. At other clock frequencies, the timing will not fit.
Transferring files
------------------
Files can be transferred to the SAMD21/SAMD51 devices for instance with the
:ref:`mpremote <mpremote>` tool. See the MicroPython forum for community-supported
alternatives to transfer files to an SAMD21/SAMD51 board, like rshell or Thonny.

84
docs/samd/tutorial/intro.rst Normal file
View File

@ -0,0 +1,84 @@
.. _samd_intro:
Getting started with MicroPython on the SAMD
==============================================
Using MicroPython is a great way to get the most of your SAMD board. And
vice versa, the SAMD chip is a great platform for using MicroPython. This
tutorial will guide you through setting up MicroPython, getting a prompt, using
the hardware peripherals, and controlling some external components.
Let's get started!
Requirements
------------
The first thing you need is a board with an SAMD chip. The MicroPython
software supports the SAMD chip itself and any board should work. The main
characteristic of a board is how the GPIO pins are connected to the outside
world, and whether it includes a built-in USB-serial converter to make the
UART available to your PC.
Names of pins will be given in this tutorial using the board names ("D0")
and it should be straightforward to find which pin this corresponds to on your
particular board.
Powering the board
------------------
If your board has a USB connector on it then most likely it is powered through
this when connected to your PC. Otherwise you will need to power it directly.
Please refer to the documentation for your board for further details.
Getting the firmware
--------------------
Firmware versions are provided at the
`MicroPython download page <https://micropython.org/download/?port=samd>`_.
You can download the most recent MicroPython firmware .uf2 file to load
onto your SAMD device. From that download page you have two main choices:
* stable firmware builds
* daily firmware builds
If you are just starting with MicroPython, the best bet is to go for the stable
firmware builds. If you are an advanced, experienced MicroPython SAMD user
who would like to follow development closely and help with testing new
features, there are daily builds. They run through the same rigid internal
test sequence as the stable builds, but the firmware features may change.
Deploying the firmware
----------------------
Once you have the MicroPython firmware you need to load it onto your
SAMD device. Most of the boards support the following easy procedure for
firmware upload.
- Connect the board by an USB-A/USB-Micro cable to your PC.
- Push the reset button twice. Then, a drive should pop up at the
PC's file manager. Many boards have a on-board RGB LED, which first lights up
red, and then changes it's colour to green. The timing of the double push is
sometimes tricky. So you may have to try to get the proper rhythm.
- Copy the .uf2 file to that newly opened drive. A LED on the board may
flash a while. When the copy is finished, the board drive will disappear and the
RGB led will turn from green to the initial state.
Serial prompt
-------------
Once you have the firmware on the device you can access the REPL (Python prompt)
over USB.
From there you can follow the SAMD tutorial.
Troubleshooting installation problems
-------------------------------------
If you experience problems during flashing or with running firmware immediately
after it, here are some troubleshooting recommendations:
* Be aware of and try to exclude hardware problems. There are two common
problems: bad power source quality, and worn-out/defective Flash ROM.
Speaking of power source, not just raw amperage is important, but also low
ripple and noise/EMI in general. The most reliable and convenient power
source is a USB port.

5
docs/static/custom.css vendored Normal file
View File

@ -0,0 +1,5 @@
/* Workaround to force Sphinx to render tables to 100% and wordwrap */
/* See https://stackoverflow.com/questions/69359978/grid-table-does-not-word-wrap for more details */
.wy-table-responsive table td, .wy-table-responsive table th {
white-space: inherit;
}

25
docs/templates/layout.html vendored
View File

@ -4,3 +4,28 @@
{# we change the master_doc variable so that links to the index
page are to index.html instead of <port>_index.html #}
{% set master_doc = "index" %}
{% block document %}
{% if is_release %}
<div class="wy-alert wy-alert-danger">
<p>
This is the v{{ release }} version of the MicroPython
documentation. The <a href="/en/latest/{{ pagename }}.html">latest
development version</a> of this page may be more current.
</p>
</div>
{% else %}
<div class="wy-alert wy-alert-danger">
<p>
This is the documentation for the latest development branch of
MicroPython and may refer to features that are not available in released
versions.
</p>
<p>
If you are looking for the documentation for a specific release, use
the drop-down menu on the left and select the desired version.
</p>
</div>
{% endif %}
{{ super() }}
{% endblock %}

9
docs/templates/topindex.html vendored
View File

@ -5,8 +5,7 @@
<h1>MicroPython documentation</h1>
<p>
{{ _('Welcome! This is the documentation for MicroPython') }}
v{{ release|e }}{% if last_updated %}, {{ _('last updated') }} {{ last_updated|e }}{% endif %}.
{{ _('Welcome! This is the documentation for MicroPython') }}{% if last_updated %}, {{ _('last updated') }} {{ last_updated|e }}{% endif %}.
</p>
<p>
@ -82,6 +81,10 @@
<a class="biglink" href="{{ pathto("renesas-ra/quickref") }}">Quick reference for the Renesas RA</a><br/>
<span class="linkdescr">general information for Renesas RA based boards, snippets of useful code, and a tutorial</span>
</p>
<p class="biglink">
<a class="biglink" href="{{ pathto("samd/quickref") }}">Quick reference for the SAMD21/SAMD51</a><br/>
<span class="linkdescr">general information for SAMD21/SAMD51 based boards, snippets of useful code, and a tutorial</span>
</p>
</td>
</tr></table>
@ -119,7 +122,7 @@
<span class="linkdescr">the official MicroPython site</span>
</p>
<p class="biglink">
<a class="biglink" href="http://forum.micropython.org">MicroPython forum</a><br/>
<a class="biglink" href="https://github.com/orgs/micropython/discussions">GitHub Discussions</a><br/>
<span class="linkdescr">community discussion for all things related to MicroPython</span>
</p>
</td>

8
docs/zephyr/quickref.rst
View File

@ -151,7 +151,7 @@ Use the :ref:`zsensor.Sensor <zsensor.Sensor>` class to access sensor data::
accel.measure() # obtain a measurement reading from the accelerometer
# each of these prints the value taken by measure()
accel.float(zsensor.ACCEL_X) # print measurement value for accelerometer X-axis sensor channel as float
accel.millis(zsensor.ACCEL_Y) # print measurement value for accelerometer Y-axis sensor channel in millionths
accel.micro(zsensor.ACCEL_Z) # print measurement value for accelerometer Z-axis sensor channel in thousandths
accel.int(zsensor.ACCEL_X) # print measurement integer value only for accelerometer X-axis sensor channel
accel.get_float(zsensor.ACCEL_X) # print measurement value for accelerometer X-axis sensor channel as float
accel.get_millis(zsensor.ACCEL_Y) # print measurement value for accelerometer Y-axis sensor channel in millionths
accel.get_micro(zsensor.ACCEL_Z) # print measurement value for accelerometer Z-axis sensor channel in thousandths
accel.get_int(zsensor.ACCEL_X) # print measurement integer value only for accelerometer X-axis sensor channel

Some files were not shown because too many files have changed in this diff Show More