Skip to content
dcontrol

Timer

This is the timer plugin documentation.

The timer plugin only has a couple of input (to) addresses:

  • reset: reset the timer to 0, useful for e.g. watchdog applications
  • start: starts the timer
  • stop: stop the timer

The type and value for all three of these inputs can be anything that can be evaluated to be truthy of falsy, so pretty much anything.

The timer plugin only has one output (from) signal: The timeout of the timer. Therefore, the address and type fields in the mapping are of no importance to the plugin, although it makes sense to set this to timeout. On int8, int16 and bool types the maximum value will be sent (see table below for the exact values), for float types 1.0 is sent, and for STRING types the address is copied as the value, so that it can be used as input to other plugins (see example data request for an example). If you’d like to send a value of 1 to an int8 or int16 receiver, you can set the type of the timer to float, and the type of the receiver to int8 or int16 respectively which will convert the floating point 1.0 to an integer with a value of 1. There are two special cases: if you use the epoch or epochMs address, the current time & date since epoch (unix universal coordinated time) in seconds or milliseconds respectively will be sent. In single shot mode, the received value will be transmitted unchanged.

Supported data types

  • bool
  • int
  • double
  • string
Data typeboolint8int16floatstring
Timer output (from)
timer::timeout⤴ (true)⤴ (255)⤴ (65535)⤴ (1.0)⤴ (address)
Timer input (to)
timer::reset
1
⤶⤶⤶⤶⤶
timer::start
1
⤶⤶⤶⤶⤶
timer::stop
1
⤶⤶⤶⤶⤶
  1. truthy / falsy

Configuration options

The minimal device config when using the default options would be:

settings.yml
devices:
  - type: timer
    name: timer1

This will set a timer (with the name of timer1) that will fire every second and will start immediately.

A complete config would look like this:

settings.yml
devices:
  - type: timer
    name: timer1
    options:
      interval: 50
      state: started

where

type

is always “timer” as this is the name of this plugin.

name

unique arbitrary name.

options/interval

this is the interval at which the timer will trigger. The default unit is milliseconds, but can be specified as milliseconds 100ms, seconds 12s, minutes 15m or hours 1h. (default: 1 second, the minimum is 10ms)

options/state

initial state of the timer. Can be started or stopped. (default: started, except for single shot timers for which the state will be forced to stopped)

options/type

type of the timer. Can be single, singleshot or single shot for a timer that triggers only once, or continuous, loop or watchdog for a timer that continuously fires (this is the default).

Examples

Watchdog send

In this watchdog example the timer triggers every second and sends a boolean true to the receiver.

settings.yml
devices:
  - type: timer
    name: watchdog
    options:
      interval: 1s
  - type: modbusTCP
    name: mb
    options:
      ip: 10.0.0.1


mappings:
  - name: watchdog
    from: { name: watchdog, address: watchdog, type: bool }
    to: { name: mb, address: 10, type: bool }

Watchdog receive

In this example an external plugin (a nion in this case) must reset the watchdog within the 2 seconds (watchdog at the sender would be configured at 1s intervals allowing for some timing variations). When the watchdog expires, a signal is emitted to another device (a modbusTCP output in this case) signalling that the first device has become unresponsive. The modbus devices might for example be triggering a power relay, resetting the nion when the watchdog expires.

settings.yml
devices:
  - type: timer
    name: watchdog
    options:
      interval: 2s
  - type: nion
    name: node1
    options:
      ip: 10.0.0.1
  - type: modbusTCP
    name: mb
    options:
      ip: 10.0.0.2


mappings:
  - name: watchdog-reset
    from: { name: node1, address: watchdog, type: bool }
    to: { name: watchdog, address: reset, type: bool }
  - name: watchdog-expired
    from: { name: watchdog, address: expired, type: bool }
    to: { name: mb, address: 0, type: bool }

Regular request for data

Some devices that might use generic plugins such as the UDP or OSC plugin might need to be polled for data. This can be done by using the timer plugin.

In this scenario we’ll wire up the following setup:


Timer Web -> :3303 <- :3303 UDP 10.0.0.1 device 10.0.0.2 Δt = 1s

The timer periodically sends -every second- a trigger to the UDP instance with a request for data. The response is sent from the device back to the UDP instance and send trough to a websocket connection.

The device responds with a string data_0 (where 0 is a floating point) value when it receives a request get data input 1. The value is then send to the websocket on address device.

In this case the address on the Timer is set to “input 1”, and used in the udp plugin to complete the request string. Note that this wasn’t really necessary, and we could have ignored the address field in the Timer instance and have set the complete string in the UDP instance’ address. But this is an example after all.

settings.yml
devices:
  - type: timer
    name: Timer
    options:
      interval: 1s


  - type: udp
    name: UDP
    options:
      ip: 10.0.0.1
      port: 5000
      terminate: true
      clients:
        - device:
          ip: 10.0.0.2
          port: 3303


  - type: websocket
    name: Web


mappings:
  - name: trigger
    from: { name: Timer, address: input 1, type: string }
    to: { name: UDP, address: 'get data %s', type: string }
  - name: device-to-websocket
    from: { name: UDP, address: data_, type: float }
    to: { name: Web, address: device, type: float }

Epoch

To send the epoch time to a receiver, you can use the following example as a reference:

settings.yml
devices:
  - type: timer
    name: t0


  - type: websocket
    name: websock


mappings:
  - name: epoch
    from: { name: t0, address: epoch, type: float }
    to: { name: websock, address: Time, type: float }
  - name: epochMs
    from: { name: t0, address: epochMs, type: float }
    to: { name: websock, address: timeMs, type: float }

Delayed action

Let’s say that we want to delay the action between a trigger input and output. For this we’ll set up a timer in single shot mode and wire it between the transmitter and receiver of the event.

In the following example we’ll use an udp message as input trigger, which we’ll delay and send to a websocket client. The value transmitted by the udp plugin will be resent by the timer plugin.


UDP delay Web Δt = 1s
settings.yml
devices:
  - type: timer
    name: delay
    options:
      interval: 1s
      type: single


  - type: udp
    name: UDP
    port: 5000
    options:
      ip: 10.0.0.1
      allow_all_clients: true


  - type: websocket
    name: Web


mappings:
  - name: udp-to-timer
    from: { name: UDP, address: trigger_, type: int8 }
    to: { name: delay, address: start, type: int8 }
  - name: timer-to-websocket
    from: { name: delay, address: timeout, type: int8 }
    to: { name: Web, address: trigger, type: int8 }

Metrics

The following metrics are exported by the timer plugin. They are prefixed / namespaced with timer_, and all of them have the label {instance:"plugin_name"} where plugin_name is the name specified in the settings.yml file with the name attribute.

Metric Name Metric Type Notes
General
connection_state Gauge The connection state of the Timer.
Timer state
start_count Counter The total number of times the timer has been started.
stop_count Counter The total number of times the timer has been stopped.
reset_count Counter The total number of times the timer has been reset.
timeout_count Counter The total number of times the timer has reached its timeout.