> For the complete documentation index, see [llms.txt](https://cavedu.gitbook.io/linkit-7697/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cavedu.gitbook.io/linkit-7697/linkit-7697-arduinoide/kai-fa-zhi-nan/timer.md).

# Timer

為了讓 Arduino 開發者也能使用 timer 功能，LinkIt 7697 Arduino BSP 提供 LTimer 類別將原生 LinkIt SDK 的 timer 功能開放出來。實際應用請參考 IDE 中的 **File / Examples / LTimer / BlinkLED** 範例，該範例透過使用兩個 timer，分別控制板上 LED 與外部 LED (連接至 P6 腳位如下圖)，使其各以 500ms 與 250ms 的間隔閃爍。接下來將說明該範例是如何構成、以及各 API 所對應的功能。

![](/files/jABAsBnVTijbeaFY7pYi)

### 產生 Timer 實體 <a href="#timer-chan-sheng-timer-shi-ti" id="timer-chan-sheng-timer-shi-ti"></a>

首先加入 LTimer 類別的 header file：

```
#include "LTimer.h"
```

開發者在程式裡最多可同時使用兩個 timer，這兩個 timer 對應的 enum ID 為 *LTIMER\_0* 和 *LTIMER\_1*。使用 timer 前要先產生出 timer 的實體，以下程式碼會產生出 *LTIMER\_0* 與 *LTIMER\_1* 的兩個 timer 實體：

```
LTimer timer0(LTIMER_0);
LTimer timer1(LTIMER_1);
```

### 初始化 <a href="#timer-chu-shi-hua" id="timer-chu-shi-hua"></a>

建立 timer 實體後，接下來要進行初始化的動作。在 Arduino 的 setup() 函式裡，呼叫 timer 的 *.begin()* 函式來進行初始化：

```
timer0.begin();
timer1.begin();
```

### 啟動 Timer <a href="#timer-qi-dong-timer" id="timer-qi-dong-timer"></a>

初始化完成後，就可以呼叫 *.start()* 函式來啟動 timer。啟動 timer 需要四個參數：

```
LTimerStatus start(
  uint32_t timeoutMS,
  LTimerMode timerMode,
  ltimer_callback_t callbackFunc,
  void *userData
);
```

參數的說明如下：

* **\[IN]** *timeoutMS*：Timer 倒數的時間，單位為微秒 (millisecond)。
* **\[IN]** *timerMode*：運作模式。可設定為僅運作一次 (*LTIMER\_ONESHOT\_MODE*) 或是反覆重啟 (*LTIMER\_REPEAT\_MODE*)。在運作一次的模式下，當 timer 倒數完後，callback 函式僅會被呼叫一次；而在反覆重啟模式下，callback 函式每 *timeoutMS* 微秒就會被呼叫一次，直到 timer 被停止或是釋放。
* **\[IN]** *callbackFunc*：當 timer 倒數完成後會呼叫的 callback 函式。
* **\[IN]** *userData*：當 callback 函式被呼叫時伴隨帶入的資料結構。

Callback 函式的原型宣告如下：

```
typedef void (*ltimer_callback_t)(void *user_data);
```

其中的 *user\_data* 輸入參數即是啟動 timer 時帶入 *.start()* 函式裡的 *userData* 參數。

### 中止 Timer <a href="#timer-zhong-zhi-timer" id="timer-zhong-zhi-timer"></a>

在運作一次的模式下，因為 timer 只會倒數一次，所以不需做額外動作將 timer 停止。不過在反覆重啟的模式下，開發者可能因應用情境會有將 timer 停下來的需求。藉由呼叫 *.stop()* 函式即可中止 timer 的運作。若之後還要繼續 timer，再呼叫一次 *.start()* 就可以恢復 timer 運行。

### 釋放資源 <a href="#timer-shi-fang-zi-yuan" id="timer-shi-fang-zi-yuan"></a>

當程式確定不再需要 timer 時，可呼叫 *.end()* 函式以釋放配置給 timer 的資源。

### 範例程式 <a href="#timer-fan-li-cheng-shi" id="timer-fan-li-cheng-shi"></a>

```
#include "Arduino.h"
#include "LTimer.h"

int led0 = 7;
int led1 = 6;
int val0 = 0;
int val1 = 0;

// instantiation
LTimer timer0(LTIMER_0);
LTimer timer1(LTIMER_1);

// callback function for timer0
void _callback0(void *usr_data)
{
  val0 = !val0;
  digitalWrite(led0, val0);
}

// callback function for timer1
void _callback1(void *usr_data)
{
  val1 = !val1;
  digitalWrite(led1, val1);
}

void setup() {
  pinMode(led0, OUTPUT);
  pinMode(led1, OUTPUT);
  Serial.begin(115200);

  // initialization
  timer0.begin();
  timer1.begin();

  // start the execution
  timer0.start(500, LTIMER_REPEAT_MODE, _callback0, NULL);
  timer1.start(250, LTIMER_REPEAT_MODE, _callback1, NULL);
}

void loop() {
}
```