クラス Encoder -- 直交デコード
Encoder は、ロータリーエンコーダなどから一般的に出力される直交信号(位相の異なる２つのパルス信号)をデコードし、そのパルスの順序に応じてカウントを増加または減少させます。
ESP32 での最小限の使用例:
from machine import Pin, Encoder
encoder = Encoder(0, Pin(0, Pin.IN), Pin(1, Pin.IN)) # ピン 0, 1 の Encoder を作成し、カウントを開始
value = encoder.value() # 現在のカウント値を取得
対応ポート: ESP32, MIMXRT
コンストラクタ
メソッド
- Encoder.init(phase_a, phase_b, *, ...)
指定したパラメータで Encoder を初期化し、リセットします:
phase_a - 第1入力ピンを machine.Pin オブジェクトとして指定します。
phase_a - 第2入力ピンを machine.Pin オブジェクトとして指定します。
これらのピンは、特定のハードウェアブロックに固定されたピンを持つポートでは省略できます。
ポートでサポートされている可能性がある追加のキーワード指定のみのパラメータは次のとおりです:
filter_ns - パルスをカウントするために入力信号が安定していなければならない最小時間をナノ秒単位で指定します。実装では、この値以下でハードウェアがサポートする最長のフィルター時間を使います。デフォルトは 0 (フィルターなし)。 (ESP32 と MIMXRT でサポート)
phases - カウントする信号エッジの数を指定し、デコードの細かさ(分解能)を決定します。たとえば 4 を指定すると「4x 直交デコード」となり、1 パルスあたり 4 カウントが行われます。ポートによっては 1, 2, 4 フェーズがサポートされ、デフォルトは 1 フェーズです。 (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でサポート)
- Encoder.deinit()
Encoder を停止し、割り込みを無効化してハードウェアリソースを解放します。ソフトリセットを行うと、すべての Encoder オブジェクトを初期化解除します。
- Encoder.value([value])
エンコーダ値を符号付き整数として取得し、必要に応じて設定します。実装では、取得と設定をアトミック(不可分)に行うことが推奨されます。
この値のオーバーフローについては
machine.Counter.value()の説明を参照してください。
- Encoder.cycles([value])
カウンタの現在のサイクルカウンタを、符号付き16ビット整数として取得または設定します。この値は、カウント範囲のオーバーフローまたはアンダーフローイベントを表します。引数を指定しない場合は、実際のサイクルカウンタ値が返されます。単一の値引数を指定すると、サイクルカウンタはその値に設定されます。ベースカウンタは変更されません。このメソッドは、前の値を返します。 (MIMXRT でサポート)
- Encoder.irq(handler=None, trigger=0, hard=False)
該当するイベント event が発生したときに呼び出されるハンドラ handler を指定します。
- event には以下のいずれかを指定します:
Encoder.IRQ_RESET - reset 入力での遷移によってトリガーします。
Encoder.IRQ_INDEX - index 入力での遷移によってトリガーします。
Encoder.IRQ_MATCH - 位置カウンタが match 値と一致したときにトリガーします。高速シグナルの場合、コールバックで取得される実際の位置カウンタ値は、トリガー値と異なる場合があります。
Encoder.IRQ_ROLL_OVER - 位置カウンタが最大値から最小値にロールオーバーしたときにトリガーします。
Encoder.IRQ_ROLL_UNDER - 位置カウンタが最小値から最大値にロールアンダーしたときにトリガーします。
コールバック関数 handler は、Encoder オブジェクトである単一の引数を受け取ります。すべてのイベントは同じコールバックを共有します。コールバックをトリガーするイベントは、irq.flags() メソッドで識別できます。引数 hard は、コールバックがハード割り込みとして呼び出されるか、通常のスケジュールされた関数として呼び出されるかを指定します。ハード割り込みは常にレイテンシが短いですが、メモリを割り当ててはならないという制限があります。通常のスケジュールされた関数は使用できるものに制限はありませんが、デバイスの負荷によっては実行が遅れる場合があります。負荷が低い場合、レイテンシの差はわずかです。
デフォルトの引数値は、trigger=0, handler=None, hard=False です。handler=None を指定して呼び出した場合、コールバックは無効になります。
位置の match イベントは、位置と一致値が同一である限りトリガーされます。そのため、位置の match によるコールバックは一度だけ実行され、位置が変更された場合は再度有効にする必要があります。有効にするには
Encoder.irq()orirq().trigger()でトリガーを再定義します。ESP32の場合、Encoder の割り込みは PCNT unit で処理します。(MIMXRT でサポート)