class Timer -- 控制內部計時器

計時器可用於各式各樣的任務。目前僅實作了最簡單的情況：週期性地呼叫一個函式。

每個計時器包含一個以特定速率向上計數的計數器。其計數速率為周邊裝置時脈頻率（以 Hz 為單位）除以計時器預分頻器（prescaler）。當計數器達到計時器週期時，會觸發一個事件，並將計數器重設回零。透過 callback 方法，計時器事件可以呼叫一個 Python 函式。

以固定頻率切換 LED 的範例用法:

tim = pyb.Timer(4)              # create a timer object using timer 4
tim.init(freq=2)                # trigger at 2Hz
tim.callback(lambda t:pyb.LED(1).toggle())

使用具名函式作為 callback 的範例:

def tick(timer):                # we will receive the timer object when being called
    print(timer.counter())      # show current timer's counter value
tim = pyb.Timer(4, freq=1)      # create a timer object using timer 4 - trigger at 1Hz
tim.callback(tick)              # set the callback to our tick function

更多範例:

tim = pyb.Timer(4, freq=100)    # freq in Hz
tim = pyb.Timer(4, prescaler=0, period=99)
tim.counter()                   # get counter (can also set)
tim.prescaler(2)                # set prescaler (can also get)
tim.period(199)                 # set period (can also get)
tim.callback(lambda t: ...)     # set callback for update interrupt (t=tim instance)
tim.callback(None)              # clear callback

注意： Timer(1) 用於相機。同樣地，Timer(5) 控制伺服馬達驅動器，而 Timer(6) 則用於定時的 ADC/DAC 讀寫。建議在您的程式中使用其他計時器。

注意： 在 callback（中斷）期間無法配置記憶體，因此在 callback 內引發的例外無法提供太多資訊。關於如何規避此限制，請參閱 micropython.alloc_emergency_exception_buf()。

建構子

class pyb.Timer(id: int, *args, **kwargs)

以給定的 id 建構一個新的計時器物件。若提供了額外的參數，計時器會以 init(...) 進行初始化。有效的 id 值集合取決於所使用 OpenMV Cam 上的 STM32 MCU；請查閱 STM32 參考手冊以了解可用的通用計時器與進階控制計時器。

方法

init(*, freq: int | float | None = None, prescaler: int | None = None, period: int | None = None, mode: int = Timer.UP, div: int = 1, callback: Callable[[Timer], None] | None = None, deadtime: int = 0, brk: int = Timer.BRK_OFF, hard: bool = True) → None

初始化計時器。初始化方式必須是透過頻率（以 Hz 為單位），或是透過預分頻器與週期:

tim.init(freq=100)                  # set the timer to trigger at 100Hz
tim.init(prescaler=83, period=999)  # set the prescaler and period directly

關鍵字引數：

  • freq --- 指定計時器的週期頻率。您也可以將其視為計時器完成一個完整週期的頻率。

  • prescaler [0-0xffff] - 指定要載入計時器預分頻器暫存器（PSC）的值。計時器時脈來源會除以 (prescaler + 1) 以導出計時器時脈。時脈來源來自計時器所屬的 APB 匯流排，並且是 依 MCU 而定。在 STM32 上，APB1 上的計時器通常以 2 * pclk1 計時，而 APB2 上的計時器則以 2 * pclk2 計時；可使用 pyb.freq() 讀取目前的匯流排頻率，並查閱您 OpenMV Cam 的 MCU 對應之 STM32 參考手冊。

  • period 對於計時器 1、3、4 與 6-15 為 [0-0xffff]。對於計時器 2 與 5 為 [0-0x3fffffff]。指定要載入計時器自動重載暫存器（ARR）的值。此值決定計時器的週期（即計數器何時循環）。計時器計數器將在 period + 1 個計時器時脈週期後翻轉歸位。

  • mode 可以是下列之一：

    • Timer.UP - 將計時器設定為從 0 計數到 ARR（預設值）

    • Timer.DOWN - 將計時器設定為從 ARR 倒數到 0。

    • Timer.CENTER - 將計時器設定為從 0 計數到 ARR，然後再倒數回 0。

  • div 可以是 1、2 或 4 之一。將計時器時脈分頻以決定數位濾波器所使用的取樣時脈。

  • callback - 同 Timer.callback()

  • deadtime - 指定互補通道之間轉態時的「死區」或非作用時間（兩個通道在此期間皆為非作用狀態）。deadtime 可以是介於 0 到 1008 之間的整數，但有以下限制：0-128 以 1 為間隔遞增；128-256 以 2 為間隔遞增；256-512 以 8 為間隔遞增；512-1008 以 16 為間隔遞增。deadtime 以 source_freq 除以 div 後的時脈刻度（tick）為計量單位。deadtime 僅在計時器 1 與 8 上可用。

  • brk - 指定當 BRK_IN 輸入被觸發時，是否使用中斷（break）模式來終止 PWM 的輸出。此引數的值決定是否啟用 break 以及其極性，可以是 Timer.BRK_OFF、Timer.BRK_LOW 或 Timer.BRK_HIGH 之一。若要選擇 BRK_IN 接腳，請以 mode=Pin.ALT, alt=Pin.AFn_TIMx 建構一個 Pin 物件。在替代功能（alt）模式下，可使用該接腳的 GPIO 輸入功能 - pull=、value() 與 irq()。

  • hard 可以是下列之一：

    • True - callback 將在硬體中斷（hard interrupt）情境下執行，可將延遲與抖動降至最低，但須遵守 撰寫中斷處理常式 中所述的限制，包括無法在堆積（heap）上進行配置。

    • False - callback 將被排程為軟體中斷（soft interrupt），允許其進行配置，但也可能引入垃圾回收的延遲與抖動。

    此選項的預設值為 True。

您必須指定 freq，或同時指定 period 與 prescaler 兩者。

deinit() → None

取消初始化計時器。

停用 callback（以及相關的 irq）。

停用任何通道 callback（以及相關的 irq）。停止計時器，並停用計時器周邊裝置。

callback(fun: Callable[[Timer], None] | None) → None

設定當計時器觸發時要呼叫的函式。fun 會收到 1 個引數，即計時器物件。若 fun 為 None，則 callback 將被停用。

channel(channel: int, mode: int | None = None, *args, **kwargs) → TimerChannel | None

若只傳入通道編號，則會回傳先前已初始化的通道物件（若無先前的通道則回傳 None）。

否則，會初始化並回傳一個 TimerChannel 物件。

每個通道都可以被設定為執行 pwm、輸出比較（output compare）或輸入捕捉（input capture）。所有通道共用同一個底層計時器，這表示它們共用相同的計時器時脈。

關鍵字引數：

  • mode 可以是下列之一：

    • Timer.PWM --- 將計時器設定為 PWM 模式（高態作用）。

    • Timer.PWM_INVERTED --- 將計時器設定為 PWM 模式（低態作用）。

    • Timer.OC_TIMING --- 表示不驅動任何接腳。

    • Timer.OC_ACTIVE --- 當發生比較相符時，接腳將被設為作用狀態（作用狀態由極性決定）

    • Timer.OC_INACTIVE --- 當發生比較相符時，接腳將被設為非作用狀態。

    • Timer.OC_TOGGLE --- 當發生比較相符時，接腳將被切換。

    • Timer.OC_FORCED_ACTIVE --- 接腳被強制設為作用狀態（忽略比較相符）。

    • Timer.OC_FORCED_INACTIVE --- 接腳被強制設為非作用狀態（忽略比較相符）。

    • Timer.IC --- 將計時器設定為輸入捕捉模式。

    • Timer.ENC_A --- 將計時器設定為編碼器模式。計數器僅在 CH1 變化時才改變。

    • Timer.ENC_B --- 將計時器設定為編碼器模式。計數器僅在 CH2 變化時才改變。

    • Timer.ENC_AB --- 將計時器設定為編碼器模式。當 CH1 或 CH2 變化時計數器即改變。

  • callback - 同 TimerChannel.callback()

  • pin 為 None（預設）或一個 Pin 物件。若有指定（且非 None），這將使所指定接腳的替代功能被設定給此計時器通道。若該接腳不支援此計時器通道的任何替代功能，將會引發錯誤。

Timer.PWM 模式的關鍵字引數：

  • pulse_width - 決定要使用的初始脈衝寬度值。

  • pulse_width_percent - 決定要使用的初始脈衝寬度百分比。

Timer.OC 模式的關鍵字引數：

  • compare - 決定比較暫存器的初始值。

  • polarity 可以是下列之一：

    • Timer.HIGH - 輸出為高態作用

    • Timer.LOW - 輸出為低態作用

Timer.IC 模式的選用關鍵字引數：

  • polarity 可以是下列之一：

    • Timer.RISING - 在上升緣捕捉。

    • Timer.FALLING - 在下降緣捕捉。

    • Timer.BOTH - 在兩種邊緣皆捕捉。

請注意，捕捉僅在主通道上有效，在互補通道上無效。

Timer.ENC 模式的注意事項：

  • 需要 2 個接腳，因此其中一個或兩個接腳都需要使用 Pin API 設定為使用適當的計時器 AF。

  • 使用 timer.counter() 方法讀取編碼器值。

  • 僅在 CH1 與 CH2 上有效（在 CH1N 或 CH2N 上無效）

  • 設定編碼器模式時，通道編號會被忽略。

PWM 範例 -- 在每一款 STM32 OpenMV Cam 上，TIM4 的通道 1 與通道 2 分別連接到排針接腳 P7 與 P8:

timer = pyb.Timer(4, freq=1000)
ch1 = timer.channel(1, pyb.Timer.PWM, pin=pyb.Pin.board.P7,
                    pulse_width=8000)
ch2 = timer.channel(2, pyb.Timer.PWM, pin=pyb.Pin.board.P8,
                    pulse_width=16000)
counter(value: int | None = None) → int | None

取得或設定計時器計數器。

freq(value: int | float | None = None) → int | float | None

取得或設定計時器的頻率（若設定，會同時改變預分頻器與週期）。

period(value: int | None = None) → int | None

取得或設定計時器的週期。

prescaler(value: int | None = None) → int | None

取得或設定計時器的預分頻器。

source_freq() → int

取得計時器時脈來源的頻率。

常數

計數模式常數（init() 的 mode 引數）：

UP: int

從 0 向上計數到 ARR（預設模式）。

DOWN: int

從 ARR 倒數到 0。

CENTER: int

從 0 向上計數到 ARR，然後再倒數回 0。

中斷模式常數（init() 的 brk 引數）：

BRK_OFF: int

停用中斷輸入。

BRK_LOW: int

中斷輸入為低態作用。

BRK_HIGH: int

中斷輸入為高態作用。

通道模式常數（channel() 的 mode 引數）：

PWM: int

將通道設定為 PWM 輸出（高態作用）。

PWM_INVERTED: int

將通道設定為 PWM 輸出（低態作用）。

OC_TIMING: int

輸出比較計時模式；不驅動任何接腳。

OC_ACTIVE: int

輸出比較作用模式；當比較相符時接腳被設為作用狀態。

OC_INACTIVE: int

輸出比較非作用模式；當比較相符時接腳被設為非作用狀態。

OC_TOGGLE: int

輸出比較切換模式；當比較相符時接腳切換。

OC_FORCED_ACTIVE: int

輸出比較強制作用模式；接腳被強制設為作用狀態，且比較相符被忽略。

OC_FORCED_INACTIVE: int

輸出比較強制非作用模式；接腳被強制設為非作用狀態，且比較相符被忽略。

IC: int

將通道設定為輸入捕捉模式。

ENC_A: int

編碼器模式：計數器僅在 CH1 變化時才改變。

ENC_B: int

編碼器模式：計數器僅在 CH2 變化時才改變。

ENC_AB: int

編碼器模式：當 CH1 或 CH2 變化時計數器即改變。

輸出比較極性（OC 模式下 channel() 的 polarity 引數）：

HIGH: int

輸出為高態作用。

LOW: int

輸出為低態作用。

輸入捕捉極性（IC 模式下 channel() 的 polarity 引數）：

RISING: int

在上升緣捕捉。

FALLING: int

在下降緣捕捉。

BOTH: int

在任一邊緣捕捉。