# tmr module

| Status | Last Update | API Version |
| ------ | ------ | ------ |
| Active | 2020-1-18 | V1.00.00 |

## Description
This is timer API, usually used in event-driven applications.

Typically, 3 steps should be taken in place to use a timer:

1.  Call tmr.new() to get a timer instance.
2.  Call instance:setup() to setup the timer.
3. Call instance:start() to start the timer.
4. If needed, call instance:remove().
5.  See example code on the bottom of this page to get a clear look.

## tmr.new()

### Description

Create a new timer object.

### Parameters

nil

### Return value

| Name   | Type  | Range     | Usage            |
| ------ | ----- | --------- | ---------------- |
| <instance> | timer |  | timer instance |

### Example call

```lua
tim1 = tmr.new()
```



## timer:setup()

### Description

Set the timer with given parameters.

### Parameters

| Name                     | Type   | Range                                               | Usage                                                        |
| ------------------------ | ------ | --------------------------------------------------- | ------------------------------------------------------------ |
| <FirstTriggerTime> | number | 0~(2^32-1)                                          | Set the first trigger time (in ms) after timer:start() is called. |
| <Period>           | number | 0~(2^32-1)                                          | Set the period of the the timer, if it is in mode `tmr.ONESHOT`, this parameter is ignored. |
| <Mode>             | number | `tmr.ONESHOT` `tmr.MANUAL_RELOAD` `tmr.AUTO_RELOAD` | Set the mode of the timer: If `tmr.ONESHOT` is present, the timer is expired only once, it's `FirstTriggerTime` mili-seconds after `timer:start()` call. If `tmr.MANUAL_RELOAD` is present, the timer expires `FirstTriggerTime` mili-seconds after `timer:start()` call for the first time, and user should call `timer:reload()` to manually reload the timer, the next expire will happen `Period` miliseconds after the reload. If `tmr.AUTO_RELOAD` is set, the timer expires `FirstTriggerTime` mili-seconds after `timer:start()` call for the first time, and expires periodically every `Period` miliseconds. |
| <Callback>           | function |                                                     | Set the callback when the timer expires, the timer instance is passed to the callback as the first argument. |

### Return Value
nil

### Example call

```lua
cnt3 = 0

function Auto_Timer_Callback(timer_self) 
  cnt3 = cnt3 + 1

  if cnt3 < 10 then 
    print('Auto-reload timer fired.','cnt3 =',cnt3,'t =',sys.gTick())
  else
    os.exit(0)
  end
end

tim = tmr.new()
tim:setup(1000,1000,tmr.AUTO_RELOAD,Auto_Timer_Callback)
tim:start()
```



## timer:remove()

### Description

Remove a timer and release its resources.

### Parameters

nil

### Return value

nil

### Example call

```lua
tim:remove()
```



## timer:suspend()

### Description

Suspend a timer.

### Parameters

nil

### Return value

nil

### Example call

```lua
tim:suspend()
```



## timer:getCallback()

### Description

Get  callback function of an existing timer.

### Parameters

nil

### Return value

nil

### Example call

```lua
cb = tim:getCallback()
```



## Example Code

```lua
--[[This is a demo for timer APIs. The output will be on the terminal.
Notice that the timer is ONLY triggered AFTER THE SCRIPT EXITED and entered the EVENT LOOP. Therefore, if you want to use this API, your whole programme should be event-driven.
    Detailed Documentation:
    Version: 191111
    Author:  yanke928]]

cnt1=0
cnt2=0
cnt3=0

function OneShot_Timer_Callback(timer_self) 
  cnt1 = cnt1 + 1
  print('Oneshot timer fired. Starting tim2.','cnt1 =',cnt1,'t =',sys.gTick())
  tim2:start()
end

function ManualReload_Timer_Callback(timer_self) 
  cnt2 = cnt2 + 1

  if cnt2 < 5 then
    print('Manual-reload timer fired, reloading.','cnt2 =',cnt2,'t =',sys.gTick())
    timer_self:reload()
  else 
    print('Manual-reload timer fired, starting tim3','cnt2 =',cnt2,'t =',sys.gTick())
    tim3:start()
  end
end

function Auto_Timer_Callback(timer_self) 
  cnt3 = cnt3 + 1

  if cnt3 < 10 then 
    print('Auto-reload timer fired.','cnt3 =',cnt3,'t =',sys.gTick())
  else
    print('Demo is over')
    os.exit(0)
  end
end

tim1 = tmr.new()
tim1:setup(1000,1000,tmr.ONESHOT,OneShot_Timer_Callback)
--{startDelay} {interval} {mode} {callback}
tim1:start()

tim2 = tmr.new()
tim2:setup(1000,1000,tmr.MANUAL_RELOAD,ManualReload_Timer_Callback)

tim3 = tmr.new()
tim3:setup(1000,1000,tmr.AUTO_RELOAD,Auto_Timer_Callback)


```