summaryrefslogtreecommitdiffstatshomepage
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/develop/natmod.rst9
-rw-r--r--docs/esp32/quickref.rst65
-rw-r--r--docs/esp32/tutorial/pwm.rst220
-rw-r--r--docs/library/esp32.rst31
-rw-r--r--docs/library/framebuf.rst12
-rw-r--r--docs/library/machine.PWM.rst14
-rw-r--r--docs/library/machine.UART.rst3
-rw-r--r--docs/library/socket.rst10
-rw-r--r--docs/library/time.rst11
-rw-r--r--docs/library/wm8960.rst8
-rw-r--r--docs/reference/mpremote.rst8
-rw-r--r--docs/rp2/quickref.rst6
-rw-r--r--docs/samd/pinout.rst120
-rw-r--r--docs/zephyr/quickref.rst2
14 files changed, 440 insertions, 79 deletions
diff --git a/docs/develop/natmod.rst b/docs/develop/natmod.rst
index 18678eaefb..2ccd832885 100644
--- a/docs/develop/natmod.rst
+++ b/docs/develop/natmod.rst
@@ -81,7 +81,14 @@ Linker limitation: the native module is not linked against the symbol table of t
full MicroPython firmware. Rather, it is linked against an explicit table of exported
symbols found in ``mp_fun_table`` (in ``py/nativeglue.h``), that is fixed at firmware
build time. It is thus not possible to simply call some arbitrary HAL/OS/RTOS/system
-function, for example.
+function, for example, unless that resides at a fixed address. In that case, the path
+of a linkerscript containing a series of symbol names and their fixed address can be
+passed to ``mpy_ld.py`` via the ``--externs`` command line argument. That way symbols
+appearing in the linkerscript will take precedence over what is provided from object
+files, but at the moment the object files' implementation will still reside in the
+final MPY file. The linkerscript parser is limited in its capabilities, and is
+currently used only for parsing the ESP8266 port ROM symbols list (see
+``ports/esp8266/boards/eagle.rom.addr.v6.ld``).
New symbols can be added to the end of the table and the firmware rebuilt.
The symbols also need to be added to ``tools/mpy_ld.py``'s ``fun_table`` dict in the
diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst
index ccc01099d1..c394414a76 100644
--- a/docs/esp32/quickref.rst
+++ b/docs/esp32/quickref.rst
@@ -148,6 +148,7 @@ Required keyword arguments for the constructor:
- ``mdc`` and ``mdio`` - :class:`machine.Pin` objects (or integers) specifying
the MDC and MDIO pins.
- ``phy_type`` - Select the PHY device type. Supported devices are
+ ``PHY_GENERIC``,
``PHY_LAN8710``, ``PHY_LAN8720``, ``PHY_IP101``, ``PHY_RTL8201``,
``PHY_DP83848``, ``PHY_KSZ8041`` and ``PHY_KSZ8081``. These values are all
constants defined in the ``network`` module.
@@ -270,8 +271,10 @@ Use the :mod:`time <time>` module::
Timers
------
-The ESP32 port has four hardware timers. Use the :ref:`machine.Timer <machine.Timer>` class
-with a timer ID from 0 to 3 (inclusive)::
+The ESP32 port has one, two or four hardware timers, depending on the ESP32 device type.
+There is 1 timer for ESP32C2, 2 timers for ESP32C4, ESP32C6 and ESP32H4, and
+4 timers otherwise. Use the :ref:`machine.Timer <machine.Timer>` class
+with a timer ID of 0, 0 and 1, or from 0 to 3 (inclusive)::
from machine import Timer
@@ -281,7 +284,8 @@ with a timer ID from 0 to 3 (inclusive)::
tim1 = Timer(1)
tim1.init(period=2000, mode=Timer.PERIODIC, callback=lambda t:print(1))
-The period is in milliseconds.
+The period is in milliseconds. When using UART.IRQ_RXIDLE, timer 0 is needed for
+the IRQ_RXIDLE mechanism and must not be used otherwise.
Virtual timers are not currently supported on this port.
@@ -383,7 +387,7 @@ for more details.
Use the :ref:`machine.PWM <machine.PWM>` class::
- from machine import Pin, PWM
+ from machine import Pin, PWM, lightsleep
pwm0 = PWM(Pin(0), freq=5000, duty_u16=32768) # create PWM object from a pin
freq = pwm0.freq() # get current frequency
@@ -393,7 +397,7 @@ Use the :ref:`machine.PWM <machine.PWM>` class::
pwm0.duty(256) # set duty cycle from 0 to 1023 as a ratio duty/1023, (now 25%)
duty_u16 = pwm0.duty_u16() # get current duty cycle, range 0-65535
- pwm0.duty_u16(2**16*3//4) # set duty cycle from 0 to 65535 as a ratio duty_u16/65535, (now 75%)
+ pwm0.duty_u16(65536*3//4) # set duty cycle from 0 to 65535 as a ratio duty_u16/65535, (now 75%)
duty_ns = pwm0.duty_ns() # get current pulse width in ns
pwm0.duty_ns(250_000) # set pulse width in nanoseconds from 0 to 1_000_000_000/freq, (now 25%)
@@ -402,19 +406,35 @@ Use the :ref:`machine.PWM <machine.PWM>` class::
pwm2 = PWM(Pin(2), freq=20000, duty=512) # create and configure in one go
print(pwm2) # view PWM settings
+ pwm2.deinit() # turn off PWM on the pin
+
+ pwm0 = PWM(Pin(0), duty_u16=16384) # The output is at a high level 25% of the time.
+ pwm2 = PWM(Pin(2), duty_u16=16384, invert=1) # The output is at a low level 25% of the time.
+
+ pwm4 = PWM(Pin(4), lightsleep=True) # Allow PWM during light sleep mode
+
+ lightsleep(10*1000) # pwm0, pwm2 goes off, pwm4 stays on during 10s light sleep
+ # pwm0, pwm2, pwm4 on after 10s light sleep
ESP chips have different hardware peripherals:
-===================================================== ======== ======== ========
-Hardware specification ESP32 ESP32-S2 ESP32-C3
------------------------------------------------------ -------- -------- --------
-Number of groups (speed modes) 2 1 1
-Number of timers per group 4 4 4
-Number of channels per group 8 8 6
------------------------------------------------------ -------- -------- --------
-Different PWM frequencies (groups * timers) 8 4 4
-Total PWM channels (Pins, duties) (groups * channels) 16 8 6
-===================================================== ======== ======== ========
+======================================================= ======== ========= ==========
+Hardware specification ESP32 ESP32-S2, ESP32-C2,
+ ESP32-S3, ESP32-C3,
+ ESP32-P4 ESP32-C5,
+ ESP32-C6,
+ ESP32-H2
+------------------------------------------------------- -------- --------- ----------
+Number of groups (speed modes) 2 1 1
+Number of timers per group 4 4 4
+Number of channels per group 8 8 6
+------------------------------------------------------- -------- --------- ----------
+Different PWM frequencies = (groups * timers) 8 4 4
+Total PWM channels (Pins, duties) = (groups * channels) 16 8 6
+======================================================= ======== ========= ==========
+
+In light sleep, the ESP32 PWM can only operate in low speed mode, so only 4 timers and
+8 channels are available.
A maximum number of PWM channels (Pins) are available on the ESP32 - 16 channels,
but only 8 different PWM frequencies are available, the remaining 8 channels must
@@ -524,14 +544,27 @@ Legacy methods:
Equivalent to ``ADC.block().init(bits=bits)``.
+The only chip that can switch resolution to a lower one is the normal esp32.
+The C2 & S3 are stuck at 12 bits, while the S2 is at 13 bits.
+
For compatibility, the ``ADC`` object also provides constants matching the
-supported ADC resolutions:
+supported ADC resolutions, per chip:
+ESP32:
- ``ADC.WIDTH_9BIT`` = 9
- ``ADC.WIDTH_10BIT`` = 10
- ``ADC.WIDTH_11BIT`` = 11
- ``ADC.WIDTH_12BIT`` = 12
+ESP32 C3 & S3:
+ - ``ADC.WIDTH_12BIT`` = 12
+
+ESP32 S2:
+ - ``ADC.WIDTH_13BIT`` = 13
+
+.. method:: ADC.deinit()
+
+ Provided to deinit the adc driver.
Software SPI bus
----------------
diff --git a/docs/esp32/tutorial/pwm.rst b/docs/esp32/tutorial/pwm.rst
index 2650284d35..82d43b36f6 100644
--- a/docs/esp32/tutorial/pwm.rst
+++ b/docs/esp32/tutorial/pwm.rst
@@ -11,16 +11,20 @@ compared with the length of a single period (low plus high time). Maximum
duty cycle is when the pin is high all of the time, and minimum is when it is
low all of the time.
-* More comprehensive example with all 16 PWM channels and 8 timers::
+* More comprehensive example with all **16 PWM channels and 8 timers**::
+ from time import sleep
from machine import Pin, PWM
try:
- f = 100 # Hz
- d = 1024 // 16 # 6.25%
- pins = (15, 2, 4, 16, 18, 19, 22, 23, 25, 26, 27, 14 , 12, 13, 32, 33)
+ F = 10000 # Hz
+ D = 65536 // 16 # 6.25%
+ pins = (2, 4, 12, 13, 14, 15, 16, 18, 19, 22, 23, 25, 26, 27, 32, 33)
pwms = []
for i, pin in enumerate(pins):
- pwms.append(PWM(Pin(pin), freq=f * (i // 2 + 1), duty= 1023 if i==15 else d * (i + 1)))
+ f = F * (i // 2 + 1)
+ d = min(65535, D * (i + 1))
+ pwms.append(PWM(pin, freq=f, duty_u16=d))
+ sleep(2 / f)
print(pwms[i])
finally:
for pwm in pwms:
@@ -31,65 +35,100 @@ low all of the time.
Output is::
- PWM(Pin(15), freq=100, duty=64, resolution=10, mode=0, channel=0, timer=0)
- PWM(Pin(2), freq=100, duty=128, resolution=10, mode=0, channel=1, timer=0)
- PWM(Pin(4), freq=200, duty=192, resolution=10, mode=0, channel=2, timer=1)
- PWM(Pin(16), freq=200, duty=256, resolution=10, mode=0, channel=3, timer=1)
- PWM(Pin(18), freq=300, duty=320, resolution=10, mode=0, channel=4, timer=2)
- PWM(Pin(19), freq=300, duty=384, resolution=10, mode=0, channel=5, timer=2)
- PWM(Pin(22), freq=400, duty=448, resolution=10, mode=0, channel=6, timer=3)
- PWM(Pin(23), freq=400, duty=512, resolution=10, mode=0, channel=7, timer=3)
- PWM(Pin(25), freq=500, duty=576, resolution=10, mode=1, channel=0, timer=0)
- PWM(Pin(26), freq=500, duty=640, resolution=10, mode=1, channel=1, timer=0)
- PWM(Pin(27), freq=600, duty=704, resolution=10, mode=1, channel=2, timer=1)
- PWM(Pin(14), freq=600, duty=768, resolution=10, mode=1, channel=3, timer=1)
- PWM(Pin(12), freq=700, duty=832, resolution=10, mode=1, channel=4, timer=2)
- PWM(Pin(13), freq=700, duty=896, resolution=10, mode=1, channel=5, timer=2)
- PWM(Pin(32), freq=800, duty=960, resolution=10, mode=1, channel=6, timer=3)
- PWM(Pin(33), freq=800, duty=1023, resolution=10, mode=1, channel=7, timer=3)
-
-* Example of a smooth frequency change::
+ PWM(Pin(2), freq=10000, duty_u16=4096)
+ PWM(Pin(4), freq=10000, duty_u16=8192)
+ PWM(Pin(12), freq=20000, duty_u16=12288)
+ PWM(Pin(13), freq=20000, duty_u16=16384)
+ PWM(Pin(14), freq=30030, duty_u16=20480)
+ PWM(Pin(15), freq=30030, duty_u16=24576)
+ PWM(Pin(16), freq=40000, duty_u16=28672)
+ PWM(Pin(18), freq=40000, duty_u16=32768)
+ PWM(Pin(19), freq=50000, duty_u16=36864)
+ PWM(Pin(22), freq=50000, duty_u16=40960)
+ PWM(Pin(23), freq=60060, duty_u16=45056)
+ PWM(Pin(25), freq=60060, duty_u16=49152)
+ PWM(Pin(26), freq=69930, duty_u16=53248)
+ PWM(Pin(27), freq=69930, duty_u16=57344)
+ PWM(Pin(32), freq=80000, duty_u16=61440)
+ PWM(Pin(33), freq=80000, duty_u16=65535)
+
+
+* Example of a **smooth frequency change**::
from time import sleep
from machine import Pin, PWM
- F_MIN = 500
- F_MAX = 1000
+ F_MIN = 1000
+ F_MAX = 10000
f = F_MIN
- delta_f = 1
+ delta_f = F_MAX // 50
- p = PWM(Pin(5), f)
- print(p)
+ pwm = PWM(Pin(27), f)
while True:
- p.freq(f)
-
- sleep(10 / F_MIN)
+ pwm.freq(f)
+ sleep(1 / f)
+ sleep(0.1)
+ print(pwm)
f += delta_f
- if f >= F_MAX or f <= F_MIN:
+ if f > F_MAX or f < F_MIN:
delta_f = -delta_f
+ print()
+ if f > F_MAX:
+ f = F_MAX
+ elif f < F_MIN:
+ f = F_MIN
- See PWM wave at Pin(5) with an oscilloscope.
+ See PWM wave on Pin(27) with an oscilloscope.
+
+ Output is::
-* Example of a smooth duty change::
+ PWM(Pin(27), freq=998, duty_u16=32768)
+ PWM(Pin(27), freq=1202, duty_u16=32768)
+ PWM(Pin(27), freq=1401, duty_u16=32768)
+ PWM(Pin(27), freq=1598, duty_u16=32768)
+ ...
+ PWM(Pin(27), freq=9398, duty_u16=32768)
+ PWM(Pin(27), freq=9615, duty_u16=32768)
+ PWM(Pin(27), freq=9804, duty_u16=32768)
+ PWM(Pin(27), freq=10000, duty_u16=32768)
+
+ PWM(Pin(27), freq=10000, duty_u16=32768)
+ PWM(Pin(27), freq=9804, duty_u16=32768)
+ PWM(Pin(27), freq=9615, duty_u16=32768)
+ PWM(Pin(27), freq=9398, duty_u16=32768)
+ ...
+ PWM(Pin(27), freq=1598, duty_u16=32768)
+ PWM(Pin(27), freq=1401, duty_u16=32768)
+ PWM(Pin(27), freq=1202, duty_u16=32768)
+ PWM(Pin(27), freq=998, duty_u16=32768)
+
+
+* Example of a **smooth duty change**::
from time import sleep
from machine import Pin, PWM
- DUTY_MAX = 2**16 - 1
+ DUTY_MAX = 65535
duty_u16 = 0
- delta_d = 16
+ delta_d = 256
- p = PWM(Pin(5), 1000, duty_u16=duty_u16)
- print(p)
+ pwm = PWM(Pin(27), freq=1000, duty_u16=duty_u16)
while True:
- p.duty_u16(duty_u16)
+ pwm.duty_u16(duty_u16)
+ sleep(2 / pwm.freq())
+ print(pwm)
- sleep(1 / 1000)
+ if duty_u16 >= DUTY_MAX:
+ print()
+ sleep(2)
+ elif duty_u16 <= 0:
+ print()
+ sleep(2)
duty_u16 += delta_d
if duty_u16 >= DUTY_MAX:
@@ -99,9 +138,106 @@ low all of the time.
duty_u16 = 0
delta_d = -delta_d
- See PWM wave at Pin(5) with an oscilloscope.
+ PWM wave on Pin(27) with an oscilloscope.
+
+ Output is::
+
+ PWM(Pin(27), freq=998, duty_u16=0)
+ PWM(Pin(27), freq=998, duty_u16=256)
+ PWM(Pin(27), freq=998, duty_u16=512)
+ PWM(Pin(27), freq=998, duty_u16=768)
+ PWM(Pin(27), freq=998, duty_u16=1024)
+ ...
+ PWM(Pin(27), freq=998, duty_u16=64512)
+ PWM(Pin(27), freq=998, duty_u16=64768)
+ PWM(Pin(27), freq=998, duty_u16=65024)
+ PWM(Pin(27), freq=998, duty_u16=65280)
+ PWM(Pin(27), freq=998, duty_u16=65535)
+
+ PWM(Pin(27), freq=998, duty_u16=65279)
+ PWM(Pin(27), freq=998, duty_u16=65023)
+ PWM(Pin(27), freq=998, duty_u16=64767)
+ PWM(Pin(27), freq=998, duty_u16=64511)
+ ...
+ PWM(Pin(27), freq=998, duty_u16=1023)
+ PWM(Pin(27), freq=998, duty_u16=767)
+ PWM(Pin(27), freq=998, duty_u16=511)
+ PWM(Pin(27), freq=998, duty_u16=255)
+ PWM(Pin(27), freq=998, duty_u16=0)
+
+
+* Example of a **smooth duty change and PWM output inversion**::
+
+ from utime import sleep
+ from machine import Pin, PWM
+
+ try:
+ DUTY_MAX = 65535
+
+ duty_u16 = 0
+ delta_d = 65536 // 32
+
+ pwm = PWM(Pin(27))
+ pwmi = PWM(Pin(32), invert=1)
+
+ while True:
+ pwm.duty_u16(duty_u16)
+ pwmi.duty_u16(duty_u16)
+
+ duty_u16 += delta_d
+ if duty_u16 >= DUTY_MAX:
+ duty_u16 = DUTY_MAX
+ delta_d = -delta_d
+ elif duty_u16 <= 0:
+ duty_u16 = 0
+ delta_d = -delta_d
+
+ sleep(.01)
+ print(pwm)
+ print(pwmi)
+
+ finally:
+ try:
+ pwm.deinit()
+ except:
+ pass
+ try:
+ pwmi.deinit()
+ except:
+ pass
+
+ Output is::
+
+ PWM(Pin(27), freq=5000, duty_u16=0)
+ PWM(Pin(32), freq=5000, duty_u16=32768, invert=1)
+ PWM(Pin(27), freq=5000, duty_u16=2048)
+ PWM(Pin(32), freq=5000, duty_u16=2048, invert=1)
+ PWM(Pin(27), freq=5000, duty_u16=4096)
+ PWM(Pin(32), freq=5000, duty_u16=4096, invert=1)
+ PWM(Pin(27), freq=5000, duty_u16=6144)
+ PWM(Pin(32), freq=5000, duty_u16=6144, invert=1)
+ PWM(Pin(27), freq=5000, duty_u16=8192)
+ PWM(Pin(32), freq=5000, duty_u16=8192, invert=1)
+ ...
+
+
+ See PWM waves on Pin(27) and Pin(32) with an oscilloscope.
+
+Note: New PWM parameters take effect in the next PWM cycle.
+
+ pwm = PWM(2, duty=512)
+ print(pwm)
+ >>> PWM(Pin(2), freq=5000, duty=1023) # the duty is not relevant
+ pwm.init(freq=2, duty=64)
+ print(pwm)
+ >>> PWM(Pin(2), freq=2, duty=16) # the duty is not relevant
+ time.sleep(1 / 2) # wait one PWM period
+ print(pwm)
+ >>> PWM(Pin(2), freq=2, duty=64) # the duty is actual
+
+Note: machine.freq(20_000_000) reduces the highest PWM frequency to 10 MHz.
-Note: the Pin.OUT mode does not need to be specified. The channel is initialized
+Note: the Pin.OUT mode does not need to be specified. The channel is initialized
to PWM mode internally once for each Pin that is passed to the PWM constructor.
The following code is wrong::
diff --git a/docs/library/esp32.rst b/docs/library/esp32.rst
index dc35e7905e..4be6dc2671 100644
--- a/docs/library/esp32.rst
+++ b/docs/library/esp32.rst
@@ -18,23 +18,31 @@ Functions
Configure whether or not a touch will wake the device from sleep.
*wake* should be a boolean value.
+ .. note:: This is only available for boards that have touch sensor support.
+
.. 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.
+ .. note:: This is only available for boards that have ULP coprocessor support.
+
.. function:: wake_on_ext0(pin, level)
Configure how EXT0 wakes the device from sleep. *pin* can be ``None``
or a valid Pin object. *level* should be ``esp32.WAKEUP_ALL_LOW`` or
``esp32.WAKEUP_ANY_HIGH``.
+ .. note:: This is only available for boards that have ext0 support.
+
.. function:: wake_on_ext1(pins, level)
Configure how EXT1 wakes the device from sleep. *pins* can be ``None``
or a tuple/list of valid Pin objects. *level* should be ``esp32.WAKEUP_ALL_LOW``
or ``esp32.WAKEUP_ANY_HIGH``.
+ .. note:: This is only available for boards that have ext1 support.
+
.. function:: gpio_deep_sleep_hold(enable)
Configure whether non-RTC GPIO pin configuration is retained during
@@ -80,6 +88,29 @@ Functions
The result of :func:`gc.mem_free()` is the total of the current "free"
and "max new split" values printed by :func:`micropython.mem_info()`.
+.. function:: idf_task_info()
+
+ Returns information about running ESP-IDF/FreeRTOS tasks, which include
+ MicroPython threads. This data is useful to gain insight into how much time
+ tasks spend running or if they are blocked for significant parts of time,
+ and to determine if allocated stacks are fully utilized or might be reduced.
+
+ ``CONFIG_FREERTOS_USE_TRACE_FACILITY=y`` must be set in the board
+ configuration to make this method available. Additionally configuring
+ ``CONFIG_FREERTOS_GENERATE_RUN_TIME_STATS=y`` and
+ ``CONFIG_FREERTOS_VTASKLIST_INCLUDE_COREID=y`` is recommended to be able to
+ retrieve the total and per-task runtime and the core ID respectively.
+
+ The return value is a 2-tuple where the first value is the total runtime,
+ and the second a list of tasks. Each task is a 7-tuple containing: the task
+ ID, name, current state, priority, runtime, stack high water mark, and the
+ ID of the core it is running on. Runtime and core ID will be None when the
+ respective FreeRTOS configuration option is not enabled.
+
+ .. note:: For an easier to use output based on this function you can use the
+ `utop library <https://github.com/micropython/micropython-lib/tree/master/micropython/utop>`_,
+ which implements a live overview similar to the Unix ``top`` command.
+
Flash partitions
----------------
diff --git a/docs/library/framebuf.rst b/docs/library/framebuf.rst
index f22a3613bd..e2a231207d 100644
--- a/docs/library/framebuf.rst
+++ b/docs/library/framebuf.rst
@@ -137,6 +137,18 @@ Other methods
is compared to the value from *palette*, not to the value directly from
*fbuf*.)
+ *fbuf* can be another FrameBuffer instance, or a tuple or list of the form::
+
+ (buffer, width, height, format)
+
+ or::
+
+ (buffer, width, height, format, stride)
+
+ This matches the signature of the FrameBuffer constructor, and the elements
+ of the tuple/list are the same as the arguments to the constructor except that
+ the *buffer* here can be read-only.
+
The *palette* argument enables blitting between FrameBuffers with differing
formats. Typical usage is to render a monochrome or grayscale glyph/icon to
a color display. The *palette* is a FrameBuffer instance whose format is
diff --git a/docs/library/machine.PWM.rst b/docs/library/machine.PWM.rst
index 5f592b8dff..c2b606affd 100644
--- a/docs/library/machine.PWM.rst
+++ b/docs/library/machine.PWM.rst
@@ -11,20 +11,20 @@ Example usage::
from machine import PWM
pwm = PWM(pin, freq=50, duty_u16=8192) # create a PWM object on a pin
- # and set freq and duty
- pwm.duty_u16(32768) # set duty to 50%
+ # and set freq 50 Hz and duty 12.5%
+ pwm.duty_u16(32768) # set duty to 50%
# reinitialise with a period of 200us, duty of 5us
pwm.init(freq=5000, duty_ns=5000)
- pwm.duty_ns(3000) # set pulse width to 3us
+ pwm.duty_ns(3000) # set pulse width to 3us
pwm.deinit()
Constructors
------------
-.. class:: PWM(dest, *, freq, duty_u16, duty_ns, invert)
+.. class:: PWM(dest, *, freq, duty_u16, duty_ns, invert=False)
Construct and return a new PWM object using the following parameters:
@@ -40,7 +40,7 @@ Constructors
Setting *freq* may affect other PWM objects if the objects share the same
underlying PWM generator (this is hardware specific).
Only one of *duty_u16* and *duty_ns* should be specified at a time.
- *invert* is not available at all ports.
+ *invert* is available only on the esp32, mimxrt, nrf, rp2, samd and zephyr ports.
Methods
-------
@@ -116,10 +116,10 @@ Limitations of PWM
resolution of 8 bit, not 16-bit as may be expected. In this case, the lowest
8 bits of *duty_u16* are insignificant. So::
- pwm=PWM(Pin(13), freq=300_000, duty_u16=2**16//2)
+ pwm=PWM(Pin(13), freq=300_000, duty_u16=65536//2)
and::
- pwm=PWM(Pin(13), freq=300_000, duty_u16=2**16//2 + 255)
+ pwm=PWM(Pin(13), freq=300_000, duty_u16=65536//2 + 255)
will generate PWM with the same 50% duty cycle.
diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst
index 5be79cccce..fbad3fc592 100644
--- a/docs/library/machine.UART.rst
+++ b/docs/library/machine.UART.rst
@@ -224,7 +224,8 @@ Methods
.. note::
- - The ESP32 port does not support the option hard=True.
+ - The ESP32 port does not support the option hard=True. It uses Timer(0)
+ for UART.IRQ_RXIDLE, so this timer cannot be used for other means.
- The rp2 port's UART.IRQ_TXIDLE is only triggered when the message
is longer than 5 characters and the trigger happens when still 5 characters
diff --git a/docs/library/socket.rst b/docs/library/socket.rst
index 944e7e631a..38e0aab704 100644
--- a/docs/library/socket.rst
+++ b/docs/library/socket.rst
@@ -227,22 +227,28 @@ Methods
has the same "no short writes" policy for blocking sockets, and will return
number of bytes sent on non-blocking sockets.
-.. method:: socket.recv(bufsize)
+.. method:: socket.recv(bufsize, [flags])
Receive data from the socket. The return value is a bytes object representing the data
received. The maximum amount of data to be received at once is specified by bufsize.
+ Most ports support the optional *flags* argument. Available *flags* are defined as constants
+ in the socket module and have the same meaning as in CPython. ``MSG_PEEK`` and ``MSG_DONTWAIT``
+ are supported on all ports which accept the *flags* argument.
+
.. method:: socket.sendto(bytes, address)
Send data to the socket. The socket should not be connected to a remote socket, since the
destination socket is specified by *address*.
-.. method:: socket.recvfrom(bufsize)
+.. method:: socket.recvfrom(bufsize, [flags])
Receive data from the socket. The return value is a pair *(bytes, address)* where *bytes* is a
bytes object representing the data received and *address* is the address of the socket sending
the data.
+ See the `recv` function for an explanation of the optional *flags* argument.
+
.. method:: socket.setsockopt(level, optname, value)
Set the value of the given socket option. The needed symbolic constants are defined in the
diff --git a/docs/library/time.rst b/docs/library/time.rst
index 8c1c1d4d6f..b53bb133ec 100644
--- a/docs/library/time.rst
+++ b/docs/library/time.rst
@@ -9,9 +9,10 @@
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, some embedded ports use epoch of
-2000-01-01 00:00:00 UTC. Epoch year may be determined with ``gmtime(0)[0]``.
+**Time Epoch**: The unix, windows, webassembly, alif, mimxrt and rp2 ports
+use the standard for POSIX systems epoch of 1970-01-01 00:00:00 UTC.
+The other embedded ports use an 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
@@ -57,11 +58,11 @@ Functions
* weekday is 0-6 for Mon-Sun
* yearday is 1-366
-.. function:: mktime()
+.. function:: mktime(date_time_tuple)
This is inverse function of localtime. It's argument is a full 8-tuple
which expresses a time as per localtime. It returns an integer which is
- the number of seconds since Jan 1, 2000.
+ the number of seconds since the time epoch.
.. function:: sleep(seconds)
diff --git a/docs/library/wm8960.rst b/docs/library/wm8960.rst
index 5abfb6a8a0..4115d20758 100644
--- a/docs/library/wm8960.rst
+++ b/docs/library/wm8960.rst
@@ -358,13 +358,13 @@ Run WM8960 on a MIMXRT10xx_DEV board in secondary mode (default)::
sysclk_source=wm8960.SYSCLK_MCLK)
-Record with a Sparkfun WM8960 breakout board with Teensy in secondary mode (default)::
+Record with a SparkFun WM8960 breakout board with Teensy in secondary mode (default)::
# Micro_python WM8960 Codec driver
#
# The breakout board uses a fixed 24MHz MCLK. Therefore the internal
# PLL must be used as sysclk, which is the master audio clock.
- # The Sparkfun board has the WS pins for RX and TX connected on the
+ # The SparkFun board has the WS pins for RX and TX connected on the
# board. Therefore adc_sync must be set to sync_adc, to configure
# it's ADCLRC pin as input.
#
@@ -379,11 +379,11 @@ Record with a Sparkfun WM8960 breakout board with Teensy in secondary mode (defa
right_input=wm8960.INPUT_CLOSED)
-Play with a Sparkfun WM8960 breakout board with Teensy in secondary mode (default)::
+Play with a SparkFun WM8960 breakout board with Teensy in secondary mode (default)::
# The breakout board uses a fixed 24MHz MCLK. Therefore the internal
# PLL must be used as sysclk, which is the master audio clock.
- # The Sparkfun board has the WS pins for RX and TX connected on the
+ # The SparkFun board has the WS pins for RX and TX connected on the
# board. Therefore adc_sync must be set to sync_adc, to configure
# it's ADCLRC pin as input.
diff --git a/docs/reference/mpremote.rst b/docs/reference/mpremote.rst
index 32ca5c246a..bee008c637 100644
--- a/docs/reference/mpremote.rst
+++ b/docs/reference/mpremote.rst
@@ -234,6 +234,7 @@ The full list of supported commands are:
- ``rmdir <dirs...>`` to remove directories on the device
- ``touch <file..>`` to create the files (if they don't already exist)
- ``sha256sum <file..>`` to calculate the SHA256 sum of files
+ - ``tree [-vsh] <dirs...>`` to print a tree of the given directories
The ``cp`` command uses a convention where a leading ``:`` represents a remote
path. Without a leading ``:`` means a local path. This is based on the
@@ -264,6 +265,13 @@ The full list of supported commands are:
There is no supported way to undelete files removed by ``mpremote rm -r :``.
Please use with caution.
+ The ``tree`` command will print a tree of the given directories.
+ Using the ``--size/-s`` option will print the size of each file, or use
+ ``--human/-h`` to use a more human readable format.
+ Note: Directory size is only printed when a non-zero size is reported by the device's filesystem.
+ The ``-v`` option can be used to include the name of the serial device in
+ the output.
+
All other commands implicitly assume the path is a remote path, but the ``:``
can be optionally used for clarity.
diff --git a/docs/rp2/quickref.rst b/docs/rp2/quickref.rst
index 23071d7721..ec31442990 100644
--- a/docs/rp2/quickref.rst
+++ b/docs/rp2/quickref.rst
@@ -135,6 +135,12 @@ Use the :mod:`machine.Timer` class::
tim = Timer(period=5000, mode=Timer.ONE_SHOT, callback=lambda t:print(1))
tim.init(period=2000, mode=Timer.PERIODIC, callback=lambda t:print(2))
+By default, timer callbacks run as soft IRQs so they can allocate but
+are prone to GC jitter and delays. Pass ``hard=True`` to the ``Timer()``
+constructor or ``init()`` method to run the callback in hard-IRQ context
+instead. This reduces delay and jitter, but see :ref:`isr_rules` for the
+restrictions that apply to hard-IRQ handlers.
+
.. _rp2_Pins_and_GPIO:
diff --git a/docs/samd/pinout.rst b/docs/samd/pinout.rst
index 3945e2bf2f..5731a8fa76 100644
--- a/docs/samd/pinout.rst
+++ b/docs/samd/pinout.rst
@@ -650,6 +650,124 @@ Adafruit ItsyBitsy M0 Express :ref:`samd21_pinout_table`.
The board does not provide access to UART, I2C, SPI or DAC.
+SparkFun Redboard Turbo 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
+ 6 PA06 D8 6 6 - 0/2 1/0 -
+ 7 PA07 D9 7 7 - 0/3 1/1 -
+ 11 PA11 RX 11 19 0/3 2/3 1/1 0/3
+ 10 PA10 TX 10 18 0/2 2/2 1/0 0/2
+ 3 PA03 AREF 3 1 - - - -
+ 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 FLASH_MISO 3 11 - 5/1 6/1 -
+ 54 PB22 FLASH_MOSI 6 - - 5/2 7/0 -
+ 55 PB23 FLASH_SCK 7 - - 5/3 7/1 -
+ 31 PA31 LED_RX 11 - - 1/3 1/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
+ 30 PA30 NEOPIXEL 10 - - 1/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 -
+ 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 PA11/PA10, labelled RX/TX
+- I2C 3 at pins PA22/PA23, labelled SDA/SCL
+- SPI 4 at pins PB10/PA12/PB11, labelled MISO, MOSI and SCK
+- DAC output on pin PA02, labelled A0
+
+
+SparkFun SAMD21 Dev Breakout 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
+ 6 PA06 D8 6 6 - 0/2 1/0 -
+ 7 PA07 D9 7 7 - 0/3 1/1 -
+ 11 PA11 RX 11 19 0/3 2/3 1/1 0/3
+ 10 PA10 TX 10 18 0/2 2/2 1/0 0/2
+ 3 PA03 AREF 3 1 - - - -
+ 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
+ 54 PB22 D30 6 - - 5/2 7/0 -
+ 55 PB23 D31 7 - - 5/3 7/1 -
+ 13 PA13 D38 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
+ 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 -
+ 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 PA11/PA10, labelled RX/TX
+- I2C 3 at pins PA22/PA23, labelled SDA/SCL
+- SPI 4 at pins PB10/PA12/PB11, labelled MISO, MOSI and SCK
+- DAC output on pin PA02, labelled A0
SAMD21 Xplained PRO pin assignment table
----------------------------------------
@@ -892,7 +1010,7 @@ Default pin assignments:
There seems to be no default pin assignment for this board.
-Sparkfun SAMD51 Thing Plus pin assignment table
+SparkFun SAMD51 Thing Plus pin assignment table
------------------------------------------------
=== ==== ============ ==== ==== ==== ====== ====== ===== ===== =====
diff --git a/docs/zephyr/quickref.rst b/docs/zephyr/quickref.rst
index a7ae698607..0e985c70b3 100644
--- a/docs/zephyr/quickref.rst
+++ b/docs/zephyr/quickref.rst
@@ -153,6 +153,8 @@ Use the :ref:`zephyr.FlashArea <zephyr.FlashArea>` class to support filesystem::
f.write('Hello world') # write to the file
print(open('/flash/hello.txt').read()) # print contents of the file
+The FlashAreas' IDs that are available are listed in the FlashArea module, as ID_*.
+
Sensor
------
generated by cgit v1.2.3 (git 2.39.1) at 2025-07-04 08:23:58 +0000