このドキュメンテーションは、MicroPython の最新開発ブランチのためのものです。 リリースバージョンでは利用できない機能に言及することがあります。

特定のリリースのドキュメントをお探しの場合は、左側のドロップダウンメニューを使って、 望みのバージョンを選択します。

esp32 --- EDS32 に固有の機能

esp32 モジュールは、ESP32 モジュールに固有の制御を目的とした関数とクラスが含まれています。

関数

esp32.wake_on_touch(wake)

タッチでデバイスをスリープから復帰させるかどうかを設定します。 wake はブール型でなければなりません。

esp32.wake_on_ulp(wake)

超低消費電力コプロセッサーがデバイスをスリープから起床できるようにするかを設定します。 wake 引数はブール値でなければなりません。

esp32.wake_on_ext0(pin, level)

EXT0 がデバイスをスリープから復帰させる方法を設定します。 pin には None あるいは有効な Pin オブジェクトを指定します。 level には esp32.WAKEUP_ALL_LOW または esp32.WAKEUP_ANY_HIGH を指定する必要があります。

esp32.wake_on_ext1(pins, level)

EXT1 がデバイスをスリープから復帰させる方法を設定します。 pin には None あるいは有効な Pin オブジェクトのタプル/リストを指定します。 level には esp32.WAKEUP_ALL_LOW または esp32.WAKEUP_ANY_HIGH を指定する必要があります。

esp32.gpio_deep_sleep_hold(enable)

ディープスリープモード中のパッドホールドについて、RTC 以外の GPIO ピンの設定を保持するかどうかを設定します。 enable 引数はブール値でなければなりません。

esp32.raw_temperature()

内部温度センサーの素の値を読み、整数を返します。

esp32.idf_heap_info(capabilities)

ESP-IDF ヒープメモリ領域の情報を返します。MicroPython はヒープメモリ領域の1つを使っており、他は ESP-IDF がネットワークバッファなどのデータ領域として使っています。この情報は特に ESP-IDF とネットワークスタックで利用可能なメモリ量を把握するのに役立ちます。また、アロケーションの失敗により ESP-IDF の操作が失敗した場合の状況を知ることができるかもしれません。

capabilities パラメータは ESP-IDF の MALLOC_CAP_XXX の値に相当しますが、最も有用な2つの値は esp32 モジュールに予め定義されています。 esp32.HEAP_DATA はデータヒープ領域用であり、 esp32.HEAP_EXEC はネイティブコードエミッタで使用される実行可能領域用です。

戻り値は4項目タプルのリストで、4項目タプルのそれぞれが1つのヒープに対応しています。タプルの各項目は、合計バイト数、空きバイト数、最大空きブロック数、時間経過にともなう最小空きブロック数を意味します。

ブート後の例:

>>> 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)]

注釈

esp32.HEAP_DATA 領域中の空き IDF ヒープメモリは、MicroPython のアロケーションが失敗するのを防ぐよう自動的に MicroPython ヒープに追加できるようになっています。ただし、ここで返される情報はそれ以外の Python アロケーション失敗のトラブルシューティングには 役立ちません 。代わりに micropython.mem_info() および gc.mem_free() を使ってください:

micropython.mem_info() の出力にある "max new split" 値は、ESP-IDF ヒープの最大の空きブロックに対応し、必要に応じて MicroPython ヒープに自動的に追加できるものです。

gc.mem_free() の結果は、 micropython.mem_info() によって表示される現在の "free" と "max new split" の値の合計です。

フラッシュのパーティション

このクラスは、デバイスのフラッシュメモリ内のパーティションへのアクセスを提供します。加えて、over-the-air (OTA) 更新を可能にするメソッドもあります。

class esp32.Partition(id, block_size=4096, /)

パーティションを表すオブジェクトを作成します。 id は取得するパーティションのラベルである文字列、または定数 BOOT または RUNNING のいずれかです。 block_size は個々のブロックのバイトサイズを指定します。

classmethod Partition.find(type=TYPE_APP, subtype=0xff, label=None, block_size=4096)

type, subtype, label で指定したパーティションを見つけます。戻り値は Partition オブジェクトのリストです(空の場合もあります)。注記: subtype=0xff 任意のサブタイプにマッチ、 label=None は任意のラベルにマッチします。

block_size は、返されるオブジェクトが使う個々のブロックのバイトサイズを指定します。

Partition.info()

(type, subtype, addr, size, label, encrypted) の6項目のタプルを返します。

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)

これらのメソッドは vfs.AbstractBlockDev によって定義されたシンプルで:ref:extended ブロックプロトコルを実装します。

Partition.set_boot()

パーティションをブートパーティションとして設定します。

注釈

OTA ブートパーティションを変更した後、ハード reset または電源の入れ直しをせずに deepsleep に入らないでください。そうしておけば、ブートローダーが新しいイメージをブートする前に新しいイメージの検証を行います。

Partition.get_next_update()

このパーティションの次の更新パーティションを取得し、新しいパーティションオブジェクトを返します。よく使うのは Partition(Partition.RUNNING).get_next_update() で、これは現在更新中のパーティションの次のパーティションを返します。

classmethod Partition.mark_app_valid_cancel_rollback()

現在のブートが成功したことを示します。次のブート時の自動ロールバックを避けるために、新しいパーティションの最初のブート時に mark_app_valid_cancel_rollback を呼び出す必要があります。これは ESP-IDF の "app rollback" 機能を "CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE" 指定で使っているので、この機能が有効になっていないファームウェアで呼び出すと "OSError(-261)" が発生します。 mark_app_valid_cancel_rollback はブートのたびに呼び出しても問題なく、esptool を使ってロードしたファームウェアをブートする場合は呼び出す必要ありません。

定数

Partition.BOOT
Partition.RUNNING

Partition コンストラクタで取得するパーティションを指定するために使います: BOOT は次のリセット時に起動されるパーティションで、 RUNNING は現在実行中のパーティションです。

Partition.TYPE_APP
Partition.TYPE_DATA

Partition.find でパーティションタイプを指定するために使います: APP はブート可能なファームウェアパーティション(通常は factory, ota_0, ota_1 などのラベルがついています)、 DATA はその他のパーティションです(たとえば nvs, otadata, phy_init, vfs)。

esp32.HEAP_DATA
esp32.HEAP_EXEC

idf_heap_info で使います。

RMT

ESP32 に固有の RMT (リモートコントロール)モジュールは、もともと赤外線リモートコントロール信号を送受信するために設計されました。ただし、柔軟な設計と非常に正確な(12.5ns程度の)パルス生成により、他の多くのタイプのデジタル信号の送受信にも使用できます:

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, idle_level=0)

# 高出力にキャリア周波数を適用する場合
r = esp32.RMT(0, pin=Pin(18), clock_div=8, tx_carrier=(38000, 50, 1))

# チャンネルの分解能は 100ns (1/(source_freq/clock_div))
r.write_pulses((1, 20, 2, 40), 0)  # 0 を 100ns, 1 を 2000ns, 0 を 200ns, 1 を 4000ns 送信

RMT モジュールへの入力は 80MHz クロックです(将来的には入力クロックを設定できる可能性もありますが、現時点では固定です)。RMT チャネルの分解能は、クロック入力を clock_div で除算することにより決まります。write_pulses で指定した数値については、分解能を乗算してパルスが決まります。

clock_div は8ビット(0-255)の分周器で、各パルスは、分解能に15ビット(1-PULSE_MAX)の数値を乗算することで定義できます。8つのチャネル(0-7)があり、それぞれ異なるクロック分周器を使えます。

上記の例では80MHzクロックを8で除算しています。したがって分解能は (1/(80Mhz/8)) で 100ns になります。開始レベルは 0 であり、各数値でレベルが切り替わるので、ビットストリームは 0101 で各ビットについて [100ns, 2000ns, 100ns, 4000ns] の持続時間を有します。

詳細については ESP-IDF RMT documentation. を参照してください。

警告

現在の MicroPython RMT 実装にはいくつかの機能がありませんが、最も顕著なのは受信パルスです。RMT は ベータ機能 と見なすべきであり、インターフェースは将来変更する可能性があります。

class esp32.RMT(channel, *, pin=None, clock_div=8, idle_level=False, tx_carrier=None)

このクラスは、8つのRMTチャネルの1つへのアクセスを提供します。 channel は必須であり、どの RMT チャネル(0-7)を使うのかを識別します。 pin も必須であり、RMTチャネルにバインドするピンを設定します。 clock_div はソースクロック(80MHz)を分割する8ビットのクロック分周器であり、RMTチャネルの分解能を指定できます。 idle_level は、送信が行われていないときの出力レベルを指定するもので、 ブール型に変換される任意の値を指定でき、 True が高電圧、 False が低電圧を意味します。

伝送キャリア機能を有効にするには、 tx_carrier 引数に3項目の整数値のタプルを指定します。3項目はそれぞれキャリア周波数、デューティ比(0 から 100 で指定)、キャリアを適用する出力レベル(idle_level と同様のブール値)を意味します

classmethod RMT.source_freq()

ソースクロック周波数を返します。現在のところソースクロックは設定できないため、常に 80MHz が返されます。

RMT.clock_div()

クロック分周器を返します。チャネルの分解能は 1 / (source_freq / clock_div) であることに注意してください。

RMT.wait_done(*, timeout=0)

チャネルがアイドル状態であれば True を返します。RMT.write_pulses で開始したパルスのシーケンスが転送中の状態にあれば False を返します。 timeout キーワード引数を指定した場合、伝送が完了するまでの間、最大で指定のミリ秒だけブロックします。

RMT.loop(enable_loop)

チャネルのループを設定します。 enable_loop はブール型で、 True にすると、 RMT.write_pulses次の 呼び出しでループを有効にします。ループシーケンスの転送中に False で呼び出された場合、現在のループを完了し、転送を停止します。

RMT.write_pulses(duration, data=True)

シーケンスの送信を開始します。これを指定するには、次の3つの方法があります:

モード1: duration は、パルス幅のリストまたはタプルです。オプションの data 引数は初期出力レベルを指定します。出力レベルは各期間の後に切り替わります。

モード2: duration は正の整数であり、 data は出力レベルのリストまたはタプルです。 duration には毎回固定のパルス幅を指定します。

モード3: durationdata は同じ長さのリストまたはタプルであり、個々のパルス幅とそれぞれの出力レベルを指定します。

パルス幅は整数単位で指定するチャネルの分解能(上記のとおり)であり、1から PULSE_MAX の間の値となります。出力レベルはブール型に変換できる任意の値であり、 True が高電圧、 False が低電圧を意味します。

以前のシーケンスの送信が進行中の場合、このメソッドは以前の伝送が完了するまで新しいシーケンスを開始をブロックします。

ループが RMT.loop で有効になっている場合、シーケンスが無期限に繰り返されます。このメソッドをさらに呼び出すと、現在のループ反復が終了するまでブロックして、新しいパルスシーケンスのループをすぐに開始します。126 パルスより長いループシーケンスは、ハードウェアでサポートされていません。

static RMT.bitstream_channel([value])

machine.bitstream の実装でどのRMTチャンネルを使用するかを選択します。 value には None または有効な RMT チャンネル番号を指定します。デフォルトの RMT チャンネルは最も大きい番号のチャンネルです。

None を渡すと、RMT の使用が無効になり、代わりに machine.bitstream のビットバング実装が選択されます。

引数なしで渡すとチャンネルは変更されません。この関数は現在のチャンネル番号を返します。

定数

RMT.PULSE_MAX

パルス幅に設定できる最大整数値。

超低消費電力コプロセッサー

このクラスは、ESP32、ESP32-S2、ESP32-S3 チップの超低消費電力(ULP: Ultra-Low-Power)コプロセッサへのアクセスを提供します。

警告

このクラスでは、ESP32-S2 および ESP32-S3 チップに搭載されている RISCV ULP コプロセッサにアクセスできません。

class esp32.ULP

このクラスは超低消費電力コプロセッサーへのアクセスを提供します。

ULP.set_wakeup_period(period_index, period_us)

起床期間を設定します。

ULP.load_binary(load_addr, program_binary)

与えた load_addrprogram_binary を ULP にロードします。

ULP.run(entry_point)

与えた entry_point で ULP を起動します。

定数

esp32.WAKEUP_ALL_LOW
esp32.WAKEUP_ANY_HIGH

ピンの起床レベル。

不揮発ストレージ

このクラスは ESP-IDF が管理する不揮発ストレージ(NVS - Non-Volatile storage)へのアクセスを提供します。NVS は名前空間に区分けされ、角それぞれの名前空間が型付けされたキー/値のペアを持ちます。キーは文字列であり、値は整数型、文字列、バイナリデータブロブなど様々ですは、ドライバーは現在のところサポートしているのは、32ビット符号付き整数とバイナリデータのみです。

警告

NVS への変更は、commit メソッドを呼び出してフラッシュメモリにコミットする必要があります。commit の呼び出しに失敗すると、次のリセット時に変更が失われます。

class esp32.NVS(namespace)

名前空間へのアクセスを提供するオブジェクトを作成します(存在しない場合は自動的に作成されます)。

NVS.set_i32(key, value)

指定のキーに32ビットの符号付き整数値を設定します。 commit の呼出しを忘れないでください!

NVS.get_i32(key)

指定のキーとペアになっている符号付き整数値を返します。キーが存在しないか、値の型が異なる場合、OSError が発生します

NVS.set_blob(key, value)

指定のキーのバイナリデータ値を設定します。渡す値は、bytes、bytearray、str などで、バッファプロトコルをサポートしている必要があります。(esp-idf はバイナリデータと文字列を区別することに注意してください。このメソッドは、文字列が値として渡された場合でも常にバイナリデータとして書き込みます。) commit の呼出しを忘れないでください!

NVS.get_blob(key, buffer)

指定のキーとペアになっているバイナリデータをバッファに読み取ります。バッファは、バイト配列である必要があります。戻り値は読み取った実際の長さです。キーが存在しない場合、値の型が異なる場合、バッファ長が足りない場合は OSError が発生します。

NVS.erase_key(key)

キーと値のペアを消去します。

NVS.commit()

set_xxx メソッドによって行われた変更をフラッシュメモリにコミットします。