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

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

micropython -- MicroPython 内部のアクセスと制御

関数

micropython.const(expr)

コンパイラが最適化できるように、式が定数であることを宣言するために使います。この関数の使い方は次のとおりです:

from micropython import const

CONST_X = const(123)
CONST_Y = const(2 * CONST_X + 1)

このように宣言された定数でも、宣言されているモジュールの外部からグローバル変数としてアクセス可能です。一方、定数名がアンダースコアで始まっていれば不可視となり、グローバル変数として利用でくなくなり、実行中のメモリを消費しません。

この const 関数は MicroPython パーサによって直接認識されます。上記のパターンにしたがって CPython と MicroPython の両方で動作するスクリプトを書けるよう、 micropython モジュールの一部として提供しています。

micropython.opt_level([level])

level を指定した場合、この関数はスクリプトの後続のコンパイルの最適化レベルを設定して、 None を返します。指定しない場合は、現在の最適化レベルを返します。

最適化レベルは、次のコンパイル特性を制御します。

  • アサーション: レベル 0 では、アサーションステートメントが有効になり、バイトコードにコンパイルされます。レベル 1 以上ではアサーションがコンパイルされません。

  • ビルトイン __debug__ 変数: レベル 0 でこの変数が True に展開されます。レベル 1 以上では False で展開されます。

  • ソースコード行番号: レベル 0, 1, 2 では、ソースコードの行番号がバイトコードとともに格納され、例外が発生した行番号を例外として報告することができます。レベル 3 以上では行番号が格納されません。

デフォルトの最適化レベルは通常レベル 0 です。

micropython.alloc_emergency_exception_buf(size)

緊急例外バッファ用に size バイトの RAM を割り当てます(適当なサイズは約 100 バイトです)。このバッファは(たとえば、割り込みハンドラ内などで)通常の RAM の割り当てが失敗した場合に例外を作成するために使用されます。したがって、そのような状況でも有用なトレースバック情報を提供します。

この関数を使う良い方法は、メインスクリプト(たとえば boot.py や main.py)の先頭に置くことです。そのようにしておけば、それに続くすべてのコードに対して緊急例外バッファが有効になります。

micropython.mem_info([verbose])

現在使っているメモリに関する情報を表示します。 verbose を指定すると冗長モードとなり、詳しい情報を表示します。

表示する情報は実装に依存しますが、現在使っているスタックとヒープのサイズは含みます。冗長モードではヒープ全体を出力し、どのブロックが使用され、どのブロックが空いているかを示します。

micropython.qstr_info([verbose])

現在のところのインターンド文字列(内部に蓄えられている文字列)に関する情報を表示します。 verbose を指定すると冗長モードとなり、詳しい情報を表示します。

表示する情報は実装に依存しますが、現在のインターンド文字列の数とそれが使っている RAM のサイズは含みます。冗長モードでは RAM 上のインターンド文字列すべての名前を表示します。

micropython.stack_use()

現在使われているスタックのサイズを表す整数を返します。この値そのものは特に有用ではなく、異なる時点でのスタック使用量の違いを計算するために使用されるべきです。

micropython.heap_lock()
micropython.heap_unlock()
micropython.heap_locked()

ヒープをロックまたはロック解除します。ロックされているとメモリ割り当ては発生せず、ヒープを割り当てようとした場合は MemoryError が発生します。heap_locked() は、ヒープが現在ロックされていれば真値を返します。

これらの関数はネストすることができます。つまり heap_lock() は連続して複数回呼び出すことができ、ロックの深さが増します。その後、ヒープを再度使用可能にするためには heap_unlock() を同じ回数呼び出す必要があります。

heap_unlock() と heap_locked() のどちらも現在のロックの深さを返します(heap_unlock() ではロック解除後の値)。返される値は 0 以上の整数値です。0 はヒープがロックされていないことを意味します。

ヒープがロックされた状態で REPL が有効になると、強制的にロックが解除されます。

注記: heap_locked() はほとんどのポートで有効になっていません。有効にするにはビルド時に MICROPY_PY_MICROPYTHON_HEAP_LOCKED の設定が必要となります。

micropython.kbd_intr(chr)

KeyboardInterrupt 例外を発生させる文字を設定します。デフォルトで、スクリプト実行中は 3 に設定されていて、これは Ctrl-C に該当します。この関数に -1 を渡すとCtrl-C のキャプチャが無効になり、3 を渡すと元に戻ります。

この関数は、通常は REPL で使っている文字の入力ストリームを他の目的で使う場合、そのストリームで Ctrl-C がキャプチャーされるのを防ぐために使えます。

micropython.schedule(func, arg)

関数 func が「早急に」実行されるようにスケジュールします。この関数には、単一の引数として値 arg が渡されます。「早急に」とは、MicroPython ランタイムができるだけ早くに関数を実行すること、効率的にもしようとしていること、および次の条件が満たされるよう最善を尽くすことを意味します。

  • スケジュールされた関数が他のスケジュールされた機能を横取りすることはありません。

  • スケジュールされた関数は常に「オペコード間」で実行されます。つまり、すべての基本的な Python 操作(リストへの追加など)はアトミックであることが保証されています。

  • 使用するポートは、その中でスケジュールされた関数が決して実行されないであろう「クリティカル範囲」を定義するかもしれません。関数はクリティカル範囲内でスケジュールされますが、その範囲が終了するまで実行されません。クリティカル範囲の例としては、割り込み割り込みハンドラ(IRQ)があります。

この関数の用途は、プリエントしている IRQ からのコールバックをスケジュールすることです。そのような IRQ は IRQ で実行されるコードに制限を課し(例えばヒープはロックされるかもしれません)、後で呼び出すために関数をスケジュールすることはそれらの制限を取り除きます。

マルチスレッド対応のポートでは、スケジュールされた関数の動作は、そのポートでのグローバルインタプリタロック(GIL)が有効か無効かによって異なります。

  • GIL が有効な場合、関数は任意のスレッドをプリエンプトして、そのスレッドのコンテキストで実行できます。

  • GIL が無効な場合、関数はメインスレッドのみをプリエンプトし、そのコンテキストで実行されます。

注記: schedule() がプリエントしている IRQ から呼び出された場合、メモリ割り当てが許可されておらず、 schedule() に渡されるコールバックがバウンドメソッドであるときに、これを直接渡すことは失敗します。これは、バウンドメソッドへの参照を作成するとメモリが割り当てられるためです。解決策は、クラスコンストラクターでメソッドへの参照を作成し、その参照を schedule() に渡すことです。これについては 「Pythonオブジェクトの作成」の 参考資料 を参照してください 。

スケジュールされた関数を保持するための有限のキューがあり、キューがいっぱいになると schedule() は RuntimeError を起こします。

クラス

class micropython.RingIO(size)
class micropython.RingIO(buffer)

ストリームインターフェースを備えた、バイトの固定サイズリングバッファを提供します。これは io.BytesIO の FIFO キューのバリアントと考えることができます。

整数サイズを指定して作成すると、適切なバッファが割り当てられます。 bytearray や類似のバッファプロトコルオブジェクトをコンストラクタに渡して、その場で利用することもできます。

クラシックなリングバッファのアルゴリズムが使用されており、任意のサイズのバッファを使用できますが、1バイトは追跡のために消費されます。整数サイズで初期化された場合、このことは考慮されます。たとえば、RingIO(16) は内部で17バイトのバッファを割り当て、16バイトのデータを保持できるようにします。ただし、事前に割り当てられたバッファを渡した場合、元の長さより1バイト少なくなり、 RingIO(bytearray(16)) では15バイトのデータしか保持できません。

RingIO インスタンスは、データを単方向に渡す場合、IRQ/スレッドセーフとして使えます。たとえば、IRQ 中で書き込み、非IRQ関数で読み取ることができます(その逆も可能です)。しかし、IRQと非IRQの両方から同じインスタンスに書き込もうとすると、データの破損が発生することがよくあります。

any()

読み取ることができる文字数を整数で返します。

read([nbytes])

利用可能な文字を読み取ります。これはブロッキングしない関数です。 nbytes が指定されている場合は、最大でそのバイト数までを読み取り、指定されていない場合は可能な限り多くのデータを読み取ります。

戻り値: 読み取ったバイトを含むバイト列オブジェクト。データが利用できない場合は、長さがゼロのバイト列オブジェクトが返されます。

readline([nbytes])

改行文字で終わる行を読み取ります。改行がバッファ内に存在する場合は、そこまでの行を返し、それ以外の場合はバッファ内の利用可能なバイトを返します。 nbytes が指定されている場合は、最大でそのバイト数までを読み取ります。

戻り値: 読み取った行を含む bytes オブジェクト。

readinto(buf[, nbytes])

指定された buf に利用可能なバイトを読み込みます。 nbytes が指定されている場合は、最大でそのバイト数までを読み取り、それ以外の場合は len(buf) バイトまでを読み取ります。

戻り値: buf に読み取ったバイト数を表す整数。

write(buf)

buf からリングバッファにバイト列を書き込みます(非ブロッキング)。リングバッファの空き容量に制限されます。

戻り値: 書き込まれたバイト数を示す整数。

close()

標準の stream インターフェースの一部として提供される何もしない操作。リングバッファ内のデータには影響を与えません。