class Encoder -- 正交解码器¶

Encoder 类封装了配置为正交解码器的 i.MX RT QENC 硬件模块。它跟踪来自旋转编码器的两相信号（phase_a / phase_b），根据相位关系递增或递减 32 位位置计数器，并可与可选的 index / reset 输入结合使用以实现绝对参考。

仅在 OpenMV Cam RT1062（mimxrt 移植）上可用。在基于 STM32 的 OpenMV cam 上，请改用配置为编码器模式（Timer.ENC_AB）的 pyb.Timer。在 OpenMV Cam AE3（alif 移植）上不提供。

用法示例:

from machine import Pin, Encoder

enc = Encoder(0, Pin("P0", Pin.IN), Pin("P1", Pin.IN), phases=4)
enc.value(0)
# ... rotate the encoder ...
print("position:", enc.value())

构造函数¶

构造（或获取）由 id 标识的 QENC 编码器模块的单例。init() 也接受相同的参数，用于重新配置现有实例。

phase_a / phase_b 是两个正交输入引脚。

phases（仅限关键字）选择解码粒度。QENC 支持 1（每对脉冲计一个边沿）、2（相位 A 的两个边沿）或 4（“4 倍解码”—— 两个相位的每个边沿都被计数）。默认值为 1。

filter_ns（仅限关键字）—— 最小输入稳定时间（以纳秒为单位）。驱动会使用小于或等于该值的最长硬件滤波器。0（默认值）表示禁用滤波。

max / min（仅限关键字）—— 位置计数器的取模范围。当计数器越过 max 时，会回绕到 min，并且循环计数器递增（反向移动时则递减）。将两者都传入 0 可禁用该范围。

index（仅限关键字）—— 一个 Pin，其上升沿会将位置计数器重新加载为 min 并根据方向更新循环计数器；典型用途是旋转编码器上的 Z 通道标记。

reset（仅限关键字）—— 一个 Pin，其上升沿会将位置计数器重新加载为起始值（而不改变循环计数器）。

match（仅限关键字）—— 触发 IRQ_MATCH 中断的位置值。传入 None 可禁用。

match_pin（仅限关键字）—— 一个 Pin，当位置计数器等于 match 时被驱动为高电平，否则为低电平。

方法¶

init(phase_a: Pin | None = None, phase_b: Pin | None = None, *, phases: int = 1, filter_ns: int = 0, max: int | None = None, min: int = 0, index: Pin | None = None, reset: Pin | None = None, match: int | None = None, match_pin: Pin | None = None) → None¶: 使用给定参数重新初始化编码器，并重置其位置计数器和循环计数器。接受与构造函数相同的关键字参数。

deinit() → None¶: 停止编码器，禁用所有挂起的中断，并释放 QENC 硬件资源。软复位会自动反初始化所有 Encoder 实例。

value() → int¶

value(value: int, /) → int

获取或设置带符号的位置计数器。

不带参数时，返回当前位置。

带单个 value 参数时，原子地将位置计数器设置为 value 并返回之前的计数值。常见用法 enc.value(0) 会在测量窗口开始时重置计数器。

cycles() → int¶

cycles(value: int, /) → int

获取或设置循环计数器，这是一个带符号的 16 位整数，用于跟踪位置计数器越过 max / min 的次数。

不带参数时，返回当前循环计数值。

带单个 value 参数时，将循环计数器设置为 value（而不改动位置计数器）并返回之前的计数值。

irq(handler: Callable[[Encoder], None] | None = None, trigger: int = 0, hard: bool = False) → None¶

注册一个回调，当某个受支持的 QENC 事件触发时被调用。处理程序接收 Encoder 对象作为其唯一参数；可在处理程序内部通过 irq.flags() 识别具体事件。

trigger 是由一个或多个 IRQ_* 常量组成的位掩码：

IRQ_RESET —— reset 引脚被置位。

IRQ_INDEX —— index 引脚被置位。

IRQ_MATCH —— 位置计数器达到 match。匹配为单次触发，必须通过重新安装 IRQ 来重新使能。

IRQ_ROLL_OVER —— 位置计数器从 max 回绕到 min。

IRQ_ROLL_UNDER —— 位置计数器从 min 回绕到 max。

hard=True 会注册一个硬中断处理程序（延迟更低，但处理程序不得分配内存）。默认是调度回调。传入 handler=None 可禁用中断。

常量¶

IRQ_RESET: int¶: reset 引脚事件的 irq() 触发标志。

IRQ_INDEX: int¶: index 引脚事件的 irq() 触发标志。

IRQ_MATCH: int¶: 位置匹配事件的 irq() 触发标志。

IRQ_ROLL_OVER: int¶: 计数器上溢（max -> min）的 irq() 触发标志。

IRQ_ROLL_UNDER: int¶: 计数器下溢（min -> max）的 irq() 触发标志。