node-red-contrib-controltimer

node-red-contrib-controltimer

Overview

The node-red-contrib-controltimer is a versatile Node-RED timer node that supports both looping and delay behavior. It allows interaction through action messages, enabling actions such as starting, resetting, stopping, pausing, and continuing the timer. This node has two outputs: the first one emits a message when the timer is triggered (either the delay expires or the interval is reached), while the second one emits a message when the running timer is stopped or paused.

The timer can be explicitly reset by using the RESET action, causing it to restart the countdown from the beginning. Alternatively, if the Reset timer on reception of START action option is enabled, sending a START action will also reset the timer. Moreover, when the Reset timer on reception of unknown message option is enabled, the timer will be reset upon receiving an unknown message.

Both looping and delay behavior timers can be paused and later resumed. When resumed, they will continue counting down from the remaining duration.

To aid in debugging or gain an overview of the timer's progress, you can enable the Is running timer progress visible option. This will display the timer's progress as a percentage of the total duration in the node's status area.

Additionally, you have the flexibility to disable specific actions for the node. For example, you can disable the RESET, PAUSE, and CONTINUE actions. In such cases, when the node receives any of the aforementioned actions, it will treat them as unknown messages.

Override configuration

Initiate the timer with overridden configuration by using the START command. Include the properties timerType, timerDuration, and timerDurationUnit in the message to override them. The timer's control functionalities (pausing, continuing, resetting) also work while in override mode.

Note that the reconfigured values are ephemeral and not saved to the node's configuration. They remain active until the timer is manually stopped or completes its cycle. Once the timer is stopped or completes, it will revert back to the values specified in the node's configuration.

When you override the configuration of a node, the information displayed on the node itself will not be updated. However, the Controltimer will run based on the configuration you have provided. To confirm that the controltimer is running according to your sent configuration, check the timer progress status below the node.

{
    payload: 'START',
    timerType: 'delay', // 'delay', 'loop'
    timerDuration: 3000,
    timerDurationUnit: 'millisecond', // 'millisecond', 'second', 'minute', 'hour'
}

Example flow diagram

Copy-Paste this flow to Node-RED to test it out yourself.

[
    {
        "id": "afd749500f2d393d",
        "type": "tab",
        "label": "ControlTimer Example",
        "disabled": false,
        "info": ""
    },
    {
        "id": "79276f6f06e96f24",
        "type": "inject",
        "z": "afd749500f2d393d",
        "name": "",
        "props": [
            {
                "p": "payload"
            }
        ],
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "topic": "",
        "payload": "START",
        "payloadType": "str",
        "x": 110,
        "y": 40,
        "wires": [["44e6d3eefa84eb4d"]]
    },
    {
        "id": "1ae1e3ee2f5250a6",
        "type": "debug",
        "z": "afd749500f2d393d",
        "name": "TIMER TRIGGERED",
        "active": true,
        "tosidebar": true,
        "console": false,
        "tostatus": false,
        "complete": "true",
        "targetType": "full",
        "statusVal": "",
        "statusType": "auto",
        "x": 680,
        "y": 140,
        "wires": []
    },
    {
        "id": "9711419041494ee9",
        "type": "inject",
        "z": "afd749500f2d393d",
        "name": "",
        "props": [
            {
                "p": "payload"
            }
        ],
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "topic": "",
        "payload": "STOP",
        "payloadType": "str",
        "x": 110,
        "y": 80,
        "wires": [["44e6d3eefa84eb4d"]]
    },
    {
        "id": "2db5a47c85a55778",
        "type": "inject",
        "z": "afd749500f2d393d",
        "name": "",
        "props": [
            {
                "p": "payload"
            }
        ],
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "topic": "",
        "payload": "RESET",
        "payloadType": "str",
        "x": 110,
        "y": 120,
        "wires": [["44e6d3eefa84eb4d"]]
    },
    {
        "id": "52882ab466bde0a2",
        "type": "inject",
        "z": "afd749500f2d393d",
        "name": "",
        "props": [
            {
                "p": "payload"
            }
        ],
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "topic": "",
        "payload": "PAUSE",
        "payloadType": "str",
        "x": 110,
        "y": 160,
        "wires": [["44e6d3eefa84eb4d"]]
    },
    {
        "id": "5acb4a13897dfe33",
        "type": "inject",
        "z": "afd749500f2d393d",
        "name": "CONTINUE",
        "props": [
            {
                "p": "payload"
            }
        ],
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "topic": "",
        "payload": "CONTINUE",
        "payloadType": "str",
        "x": 130,
        "y": 200,
        "wires": [["44e6d3eefa84eb4d"]]
    },
    {
        "id": "5c9aea117d0cb988",
        "type": "debug",
        "z": "afd749500f2d393d",
        "name": "TIMER HALTED",
        "active": true,
        "tosidebar": true,
        "console": false,
        "tostatus": false,
        "complete": "true",
        "targetType": "full",
        "statusVal": "",
        "statusType": "auto",
        "x": 660,
        "y": 180,
        "wires": []
    },
    {
        "id": "bbd756d4850041fa",
        "type": "inject",
        "z": "afd749500f2d393d",
        "name": "",
        "props": [
            {
                "p": "payload"
            }
        ],
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "topic": "",
        "payload": "UNKNOWN1",
        "payloadType": "str",
        "x": 130,
        "y": 240,
        "wires": [["44e6d3eefa84eb4d"]]
    },
    {
        "id": "76203a31872dca18",
        "type": "inject",
        "z": "afd749500f2d393d",
        "name": "UNKNOWN2",
        "props": [
            {
                "p": "unknown",
                "v": "UNKNOWN2",
                "vt": "str"
            }
        ],
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "topic": "",
        "x": 130,
        "y": 280,
        "wires": [["44e6d3eefa84eb4d"]]
    },
    {
        "id": "01f89a1a0cfa1eb2",
        "type": "inject",
        "z": "afd749500f2d393d",
        "name": "START (3000ms delay)",
        "props": [
            {
                "p": "payload"
            },
            {
                "p": "timerType",
                "v": "delay",
                "vt": "str"
            },
            {
                "p": "timerDuration",
                "v": "3000",
                "vt": "num"
            },
            {
                "p": "timerDurationUnit",
                "v": "millisecond",
                "vt": "str"
            }
        ],
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "topic": "",
        "payload": "START",
        "payloadType": "str",
        "x": 160,
        "y": 320,
        "wires": [["44e6d3eefa84eb4d"]]
    },
    {
        "id": "c96f33f73a45a2a0",
        "type": "inject",
        "z": "afd749500f2d393d",
        "name": "START (3000ms loop)",
        "props": [
            {
                "p": "payload"
            },
            {
                "p": "timerType",
                "v": "loop",
                "vt": "str"
            },
            {
                "p": "timerDuration",
                "v": "3000",
                "vt": "num"
            },
            {
                "p": "timerDurationUnit",
                "v": "millisecond",
                "vt": "str"
            }
        ],
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "topic": "",
        "payload": "START",
        "payloadType": "str",
        "x": 160,
        "y": 360,
        "wires": [["44e6d3eefa84eb4d"]]
    },
    {
        "id": "44e6d3eefa84eb4d",
        "type": "controltimer",
        "z": "afd749500f2d393d",
        "name": "",
        "timerType": "delay",
        "timerDurationUnit": "minute",
        "timerDurationType": "num",
        "timerDuration": 1,
        "timerLoopTimeoutUnit": "second",
        "timerLoopTimeoutType": "num",
        "timerLoopTimeout": 0,
        "loopTimeoutMessageType": "str",
        "loopTimeoutMessage": "LOOP_TIMEOUT",
        "timerMaxLoopIterationsType": "num",
        "timerMaxLoopIterations": 0,
        "loopMaxIterationsMessageType": "str",
        "loopMaxIterationsMessage": "MAX_LOOP_ITERATIONS",
        "isRunningTimerProgressVisible": true,
        "outputReceivedMessageOnTimerTrigger": true,
        "outputReceivedMessageOnTimerHalt": false,
        "startTimerOnReceivalOfUnknownMessage": false,
        "resetTimerOnReceivalOfUnknownMessage": false,
        "resetTimerOnReceivalOfStartAction": false,
        "continueTimerOnReceivalOfStartAction": false,
        "isDebugModeEnabled": false,
        "timerTriggeredMessageType": "str",
        "timerTriggeredMessage": "TIMER_TRIGGERED",
        "timerHaltedMessageType": "str",
        "timerHaltedMessage": "TIMER_HALTED",
        "isStartActionEnabled": true,
        "isStopActionEnabled": true,
        "isResetActionEnabled": true,
        "isPauseActionEnabled": true,
        "isContinueActionEnabled": true,
        "actionPropertyNameType": "str",
        "actionPropertyName": "payload",
        "startActionNameType": "str",
        "startActionName": "START",
        "stopActionNameType": "str",
        "stopActionName": "STOP",
        "resetActionNameType": "str",
        "resetActionName": "RESET",
        "pauseActionNameType": "str",
        "pauseActionName": "PAUSE",
        "continueActionNameType": "str",
        "continueActionName": "CONTINUE",
        "x": 440,
        "y": 200,
        "wires": [["1ae1e3ee2f5250a6"], ["5c9aea117d0cb988"]]
    }
]

Installation

Change directory to your node red installation:

$ npm install --save node-red-contrib-controltimer

Configuration

Option	Description	DEFAULT
Timer type	Defines the timer behaviour. Available options are Delay and Loop.	Delay
Timer duration unit	Defines the timer duration unit. Available options are Milliseconds, Seconds, Minutes and Hours.	Seconds
Timer duration	Defines the timer duration in specified (Timer duration unit) units.	5
Loop timeout unit	Defines timer loop timeout unit. Available options are Milliseconds, Seconds, Minutes and Hours.	Seconds
Loop timeout	Defines the timer loop timeout in specified (Loop timeout unit) units. 0 means no timeout.	0
Loop timeout message	Defines message that is emitted via timer-halted output upon timeout.	LOOP_TIMEOUT
Loop max iterations	Defines timer loop max iterations limit. 0 means no limit.	0
Loop max iterations message	Defines message that is emitted via timer-halted output upon max iterations are reached.	MAX_LOOP_ITERATIONS
Is running timer progress visible	If true it will display the timer's progress in node's status area as percentages. A good option for debugging long running tasks.	false
Output received message on timer trigger	If true it will emit the message the node received when timer triggers. If false it will emit an empty message.	true
Output received message on timer halt	If true it will emit the message the node received when timer is halted. If false it will emit an empty message.	true
Start timer on receival of unknown message	If true the timer is started upon receival of unknown* message	false
Reset timer on receival of unknown message	If true the timer is reset upon receival of unknown* message	false
Reset timer on receival of START action	If true the timer is reset upon receival of START action.	false
Continue timer on receival of START action	If true the timer is continued upon receival of START action.	false
Is debug mode enabled	If true node will log errors into debug console	false
Timer triggered message	Defines message that is emitted via timer-triggered output when timer is triggered and if Output received message on timer trigger is not enabled.	TIMER_TRIGGERED
Timer triggered message	Defines message that is emitted via timer-halted output when timer is halted and if Output received message on timer halt is not enabled.	TIMER_HALTED
Is start action enabled	If true node is permitted to receive Start actions	true
Is stop action enabled	If true node is permitted to receive Stop actions	true
Is reset action enabled	If true node is permitted to receive Reset actions	true
Is pause action enabled	If true node is permitted to receive Pause actions	true
Is continue action enabled	If true node is permitted to receive Continue actions	true
Action property name	Defines the property on a received message on which the action string to interact with timer can be found.	payload
Start action name	Defines the action string that will START the timer.	START
Stop action name	Defines the action string that will STOP the timer.	STOP
Reset action name	Defines the action string that will RESET the timer.	RESET
Pause action name	Defines the action string that will PAUSE the timer.	PAUSE
Continue action name	Defines the action string that will CONTINUE the paused timer.	CONTINUE

* An unknown message refers to a message with a payload that is not part of the defined and enabled set of action strings. For example, it could be a message without a defined Action property name or a message with a Action property name value that does not match any of the enabled action names. If a disabled action, such as the PAUSE action, is received, it is considered an unknown message according to the settings.

Future icon by Icons8