This commit adds several small items to improve the support for OTA updates on an esp32: - a partition table for 4MB flash modules that has two OTA partitions ready to go to do updates - a GENERIC_OTA board that uses that partition table and that enables automatic roll-back in the bootloader - a new esp32.Partition.mark_app_valid_cancel_rollback() class-method to signal that the boot is successful and should not be rolled back at the next reset - an automated test for doing an OTA update - documentation updates
9 KiB
esp32
esp32
--- functionality
specific to the ESP32
esp32
The esp32
module contains functions and classes
specifically aimed at controlling ESP32 modules.
Functions
wake_on_touch(wake)
Configure whether or not a touch will wake the device from sleep. wake should be a boolean value.
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
.
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
.
raw_temperature()
Read the raw value of the internal temperature sensor, returning an integer.
hall_sensor()
Read the raw value of the internal Hall sensor, returning an integer.
idf_heap_info(capabilities)
Returns information about the ESP-IDF heap memory regions. One of them contains the MicroPython heap and the others are used by ESP-IDF, e.g., for network buffers and other data. This data is useful to get a sense of how much memory is available to ESP-IDF and the networking stack in particular. It may shed some light on situations where ESP-IDF operations fail due to allocation failures. The information returned is not useful to troubleshoot Python allocation failures, use micropython.mem_info() instead.
The capabilities parameter corresponds to ESP-IDF's
MALLOC_CAP_XXX
values but the two most useful ones are
predefined as esp32.HEAP_DATA for data
heap regions and esp32.HEAP_EXEC for
executable regions as used by the native code emitter.
The return value is a list of 4-tuples, where each 4-tuple corresponds to one heap and contains: the total bytes, the free bytes, the largest free block, and the minimum free seen over time.
Example after booting:
>>> import esp32; esp32.idf_heap_info(esp32.HEAP_DATA)
[(240, 0, 0, 0), (7288, 0, 0, 0), (16648, 4, 4, 4), (79912, 35712, 35512, 35108),
(15072, 15036, 15036, 15036), (113840, 0, 0, 0)]
Flash partitions
This class gives access to the partitions in the device's flash memory and includes methods to enable over-the-air (OTA) updates.
Create an object representing a partition. id can be a
string which is the label of the partition to retrieve, or one of the
constants: BOOT
or RUNNING
.
Partition.find(type=TYPE_APP, subtype=0xff, label=None)
Find a partition specified by type, subtype and
label. Returns a (possibly empty) list of Partition objects.
Note: subtype=0xff
matches any subtype and
label=None
matches any label.
Partition.info()
Returns a 6-tuple
(type, subtype, addr, size, label, encrypted)
.
Partition.readblocks(block_num, buf)
Partition.readblocks(block_num, buf, offset)
Partition.writeblocks(block_num, buf)
Partition.writeblocks(block_num, buf, offset)
Partition.ioctl(cmd, arg)
These methods implement the simple and extended
<block-device-interface>
block protocol defined by uos.AbstractBlockDev
.
Partition.set_boot()
Sets the partition as the boot partition.
Partition.get_next_update()
Gets the next update partition after this one, and returns a new
Partition object. Typical usage is
Partition(Partition.RUNNING).get_next_update()
which
returns the next partition to update given the current running one.
Partition.mark_app_valid_cancel_rollback()
Signals that the current boot is considered successful. Calling
mark_app_valid_cancel_rollback
is required on the first
boot of a new partition to avoid an automatic rollback at the next boot.
This uses the ESP-IDF "app rollback" feature with
"CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE" and an
OSError(-261)
is raised if called on firmware that doesn't
have the feature enabled. It is OK to call
mark_app_valid_cancel_rollback
on every boot and it is not
necessary when booting firmare that was loaded using esptool.
Constants
Partition.BOOT Partition.RUNNING
Used in the Partition constructor to
fetch various partitions: BOOT
is the partition that will
be booted at the next reset and RUNNING
is the currently
running partition.
Partition.TYPE_APP Partition.TYPE_DATA
Used in Partition.find to specify the
partition type: APP
is for bootable firmware partitions
(typically labelled factory
, ota_0
,
ota_1
), and DATA
is for other partitions, e.g.
nvs
, otadata
, phy_init
,
vfs
.
HEAP_DATA HEAP_EXEC
Used in idf_heap_info.
RMT
The RMT (Remote Control) module, specific to the ESP32, was originally designed to send and receive infrared remote control signals. However, due to a flexible design and very accurate (as low as 12.5ns) pulse generation, it can also be used to transmit or receive many other types of digital signals:
import esp32
from machine import Pin
r = esp32.RMT(0, pin=Pin(18), clock_div=8)
r # RMT(channel=0, pin=18, source_freq=80000000, clock_div=8)
# The channel resolution is 100ns (1/(source_freq/clock_div)).
r.write_pulses((1, 20, 2, 40), start=0) # Send 0 for 100ns, 1 for 2000ns, 0 for 200ns, 1 for 4000ns
The input to the RMT module is an 80MHz clock (in the future it may
be able to configure the input clock but, for now, it's fixed).
clock_div
divides the clock input which determines
the resolution of the RMT channel. The numbers specificed in
write_pulses
are multiplied by the resolution to define the
pulses.
clock_div
is an 8-bit divider (0-255) and each pulse can
be defined by multiplying the resolution by a 15-bit (0-32,768) number.
There are eight channels (0-7) and each can have a different clock
divider.
So, in the example above, the 80MHz clock is divided by 8. Thus the
resolution is (1/(80Mhz/8)) 100ns. Since the start
level is
0 and toggles with each number, the bitstream is 0101
with
durations of [100ns, 2000ns, 100ns, 4000ns].
For more details see Espressif's ESP-IDF RMT documentation..
Warning
The current MicroPython RMT implementation lacks some features, most notably receiving pulses and carrier transmit. RMT should be considered a beta feature and the interface may change in the future.
This class provides access to one of the eight RMT channels. channel is required and identifies which RMT channel (0-7) will be configured. pin, also required, configures which Pin is bound to the RMT channel. clock_div is an 8-bit clock divider that divides the source clock (80MHz) to the RMT channel allowing the resolution to be specified.
RMT.source_freq()
Returns the source clock frequency. Currently the source clock is not configurable so this will always return 80MHz.
RMT.clock_div()
Return the clock divider. Note that the channel resolution is
1 / (source_freq / clock_div)
.
RMT.wait_done(timeout=0)
Returns True if RMT.write_pulses has completed.
If timeout (defined in ticks of
source_freq / clock_div
) is specified the method will wait
for timeout or until RMT.write_pulses is complete, returning
False
if the channel continues to transmit.
Warning
Avoid using wait_done()
if looping is enabled.
RMT.loop(enable_loop)
Configure looping on the channel, allowing a stream of pulses to be indefinitely repeated. enable_loop is bool, set to True to enable looping.
RMT.write_pulses(pulses, start)
Begin sending pulses, a list or tuple defining the stream of
pulses. The length of each pulse is defined by a number to be multiplied
by the channel resolution (1 / (source_freq / clock_div))
.
start defines whether the stream starts at 0 or 1.
Ultra-Low-Power co-processor
This class provides access to the Ultra-Low-Power co-processor.
ULP.set_wakeup_period(period_index, period_us)
Set the wake-up period.
ULP.load_binary(load_addr, program_binary)
Load a program_binary into the ULP at the given load_addr.
ULP.run(entry_point)
Start the ULP running at the given entry_point.
Constants
esp32.WAKEUP_ALL_LOW esp32.WAKEUP_ANY_HIGH
Selects the wake level for pins.