クラス Counter -- パルスカウンター
Counter は入力信号を監視し、立ち上がりまたは立ち下がりエッジをカウントすることでパルスカウントを実現します。
ESP32 での最小限の使用例:
from machine import Pin, Counter
counter = Counter(0, Pin(0, Pin.IN)) # ピン0の Counter を作成し、カウントを開始
value = counter.value() # 現在のパルスカウント値を取得
対応ポート: ESP32, MIMXRT
コンストラクタ
メソッド
- Counter.init(src, *, ...)
指定したパラメータで Counter を初期化し、リセットします。
src には入力ピンを machine.Pin オブジェクトとして指定します。特定のハードウェアブロックに固定されたピンがあるポートでは省略できます。
ポートでサポートされている可能性がある追加のキーワード指定のみのパラメータは次のとおりです:
edge - カウントするエッジを指定します。
Counter.RISING(デフォルト)とCounter.FALLINGのいずれかを指定します。 (ESP32 でサポート)direction - カウント方向を指定します。
Counter.UP(デフォルト)とCounter.DOWNのいずれかを指定します。 (ESP32 と MIMXRT でサポート) パラメータ引数として machine.Pin オブジェクトを指定した場合、カウント方向を制御するピンを指定したことになります。Low ではカウントアップになり、High ではカウントダウンになります (MIMXRT でサポート)filter_ns - パルスをカウントするために入力信号が安定していなければならない最小時間をナノ秒単位で指定します。実装では、この値以下でハードウェアがサポートする最長のフィルター時間を使います。デフォルトは 0 (フィルターなし)。 (ESP32 と MIMXRT でサポート)
max - 上限カウント範囲を指定します。位置カウンタは、 min 開始値から max までカウントアップし、初期値に戻ってサイクルカウンタを 1 増やします。カウントダウン時は min から max への移行時にサイクルカウンタを減少します。 max と min の両方を 0 に設定することで、範囲がリセットされます。デフォルト値はハードウェアのカウンタ範囲です。 (MIMXRT と ESP32 PCNT モジュールでサポート)
min - カウントの下限範囲を指定します。デフォルト値は0です。 (MIMXRT と ESP32 PCNT モジュールでサポート)
index - インデックスパルスが接続されるピンを指定するピン指定子。インデックスパルスの立ち上がり傾斜時に、パルスカウンタは最小値にリセットされ、サイクルカウンタはカウント方向に応じて1ずつ増減します。 None を指定すると、インデックス入力は無効になります。 (MIMXRT でサポート)
reset - リセットパルスが接続されるピンを指定するピン指定子。リセットパルスの立ち上がり傾斜時にカウンタは初期値に設定されますが、サイクルカウンタは変更されません。 None を指定するとリセット入力が無効になります。 (MIMXRT でサポート)
match - 割り込み IRQ_MATCH が発生するカウンタ値を設定します。この値はカウンタ範囲の範囲内にあるかどうかはチェックされません。このオプションは、ESP32 PCNT モジュールの threshold オプションと同等です。 None を指定すると match 値がリセットされ、IRQ_MATCH 割り込みが無効になります。 (MIMXRT でサポート)
match_pin - マッチ出力が接続されているピンを指定するピン指定子。この出力は、カウンタがマッチ値と一致する限りハイレベルになります。信号はエンコーダロジックによって生成されるため、追加のソフトウェアサポートは不要です。パルス幅は入力信号の周波数によって決まり、20nsのように非常に短い場合もあれば、カウンタがマッチ値で停止した場合はパルス幅が維持される場合もあります。 None を指定するとマッチ出力は無効になります。 (MIMXRT でサポート)
- Counter.deinit()
Counter を停止し、割り込みを無効化してハードウェアリソースを解放します。ソフトリセットを行うと、すべての Counter オブジェクトを初期化解除します。
- Counter.value([value])
カウンター値を符号付き整数として取得し、必要に応じて設定します。実装では、取得と設定をアトミックに(つまりカウントを取りこぼさずに)行うことが求められます。
このカウンター値は 小整数 の範囲を超える可能性があり、その場合
Counter.value()の呼出しによってヒープ領域の確保が発生することがあります。ただし、実装では内部状態に小整数のみを使うようにし、ユーザーがCounter.value()を呼び出すまではメモリ確保が発生しないようにするべきです。たとえば ESP32 では、内部状態としてハードウェアカウンターのオーバーフロー回数(32000 カウントごと)を記録しているため、
2**30 * 32000カウント(1MHz で約1年強)に達するまでは小整数の範囲を超えません。一般的には
Counter.value(0)を使ってカウンターをリセットし(つまり前回呼び出し以降のカウント数を測定)、この問題を回避することを推奨します。
- Counter.cycles([value])
カウンタの現在のサイクルカウンタを、符号付き16ビット整数として取得または設定します。この値は、カウント範囲のオーバーフローまたはアンダーフローイベントを表します。引数を指定しない場合は、実際のサイクルカウンタ値が返されます。単一の値引数を指定すると、サイクルカウンタはその値に設定されます。ベースカウンタは変更されません。このメソッドは、前の値を返します。 (MIMXRT でサポート)
- Counter.irq(handler=None, trigger=0, hard=False)
該当するイベント event が発生したときに呼び出されるハンドラ handler を指定します。
- event には以下のいずれかを指定します:
Counter.IRQ_RESET - reset 入力での遷移によってトリガーします。
Counter.IRQ_INDEX - index 入力での遷移によってトリガーします。
Counter.IRQ_MATCH - 位置カウンタが match 値と一致したときにトリガーします。高速シグナルの場合、コールバックで取得される実際の位置カウンタ値は、トリガー値と異なる場合があります。
Counter.IRQ_ROLL_OVER - 位置カウンタが最大値から最小値にロールオーバーしたときにトリガーします。
Counter.IRQ_ROLL_UNDER - 位置カウンタが最小値から最大値にロールアンダーしたときにトリガーします。
コールバック関数 handler は、Counter オブジェクトである単一の引数を受け取ります。すべてのイベントは同じコールバックを共有します。コールバックをトリガーするイベントは、irq.flags() メソッドで識別できます。引数 hard は、コールバックがハード割り込みとして呼び出されるか、通常のスケジュールされた関数として呼び出されるかを指定します。ハード割り込みは常にレイテンシが短いですが、メモリを割り当ててはならないという制限があります。通常のスケジュールされた関数は使用できるものに制限はありませんが、デバイスの負荷によっては実行が遅れる場合があります。負荷が低い場合、レイテンシの差はわずかです。
デフォルトの引数値は、handler=None、trigger=0、hard=False です。handler=None を指定して呼び出した場合、コールバックは無効になります。
位置の match イベントは、位置と一致値が同一である限りトリガーされます。そのため、位置の match によるコールバックは一度だけ実行され、位置が変更された場合は再度有効にする必要があります。有効にするには
Counter.irq()またはirq().trigger()でトリガーを再定義します。ESP32の場合、Counter の割り込みは PCNT で処理します。 (MIMXRT でサポート)