node-red-contrib-hourglass

node-red-contrib-hourglass is a highly versatile stopwatch node to measure time differences as a duration between a start and an end instant of time.
Measuring can be stopped (paused) and restarted (resumed) many times including a split time option. A reset function presets the time count value to zero. These are the typical functionalities of a stopwatch.

Additionally an alarm functionality is implemented which emits a special msg at a definable instant of time. Several alarms may be used.

Also, the node persists all required information between restarts of Node-RED to the file system, so you don't need to worry about recovery of your data.

One common case of using this node is calculation of the time when some device is working (operating hour counters 'OHC'). In addition, it also can alert you when it's time to do some maintenance work or change life-limited parts.
Another typical use case is the measuring of time durations (e.g. signal pulse widths, process durations, motion sensor presence times, etc.).
!node-appearance
Fig. 1: Node appearance

Installation

$3

* Via Manage Palette -> Search for "node-red-contrib-hourglass"

$3

* go to the Node-RED installation folder, e.g.: ~/.node-red
* run npm install node-red-contrib-hourglass

Usage

$3

!node-settings
Fig. 2: Node properties

Node configuration is quite simple. You only have to set the language to localize the output elapsed.human(see below) and the node's status message (see Fig. 1: "a few seconds"). If you do not use this, you can omit the node configuration.

$3

The time measuring covers the functionality of a typical stopwatch.

#### Inputs for time measuring function

Every input msg should have a command property, otherwise an error is issued (see Error handling). Supported commands are:
- start - starts (or resumes) time measuring
- stop - stops (or pauses) time measuring
- pause - pauses time measuring. Synonym of stop
- resume - resumes time measuring. Synonym of start
- toggle - switches over between running and stopped time measuring
- reset - resets measured value to 00:00. In the case of a running time measuring the value continues to count from 00:00
- status - reports the actual status of the measured value. Output properties see section Output. This command is typically used for split times or to read out the time values after a stopped measuring.

Remark: Alarm commands are described in the alarm section.

An example for an input msg object is as follows:



Fig. 3: Input msg object (example start command)



#### Output properties for time measuring function
The node-red-contrib-hourglass node contains the following output properties within its sent msg objects:
* command - give the last received command
* started - gives the status of the time measuring, specifies whether measuring is actually active
* elapsed - gives time values as an own sub-object (details see below)

In the basic mode the node only emits a msg at a status command.
An extended mode exists, where the output msg is send at every command (see Extended status message mode).



Fig. 4: Output msg object


The output property elapsed contains a sub-object with the following properties:
* elapsed.human - human representation of elapsed time (like '2 days'). These strings are localized.
* elapsed.millis - time in milliseconds, specifies the time elapsed since measuring was started.
* elapsed.time - has sub-properties of days/hours/minutes/seconds/milliseconds for elapsed time.

In the output example shown in the previous Fig. 4, these msg object properties contain a stopped state ("started: false"), a last command as a status command and the elapsed time of about 74 seconds.

The basic timer operation is shown in the following figure: In the node internally there is a counter which is controlled via the several commands. The value given in the elapsed object is changed by the status command.



Fig. 5: Basic timer operation



#### Extended status message mode
In some cases it is more convenient to get the elapsed time value directly with an according command, without an extra status command. Therefore, the extended status message mode exists.
Using this mode, the output msg is emitted in the case of every valid command, i.e. not only at the status command.

This mode is selected by using the command property msg.status set to true in a command msg. If the command msg contains no status property, the basic mode is active (for compatibility, acts as before).



Fig. 6: Input msg object in extended status message mode (example stop command)

An inject node for manually testing this mode could look like this:


Fig. 7: Input inject node configuration for extended status message mode

The extended status message mode timer operation is shown in the following figure: In the node internally there is a counter which is controlled via the several commands. The value given in the elapsed object is changed by every command. See differences to Fig. 5.



Fig. 8: Extended status message mode operation

Possible use cases for this mode are:
Measuring a pulse width, only using a start and a stop command. The stop* command gives the result.
Measuring directly consecutive time durations where every duration shall have its own duration value (i.e. each duration measuring start at time counter '0'). This can be achieved using the reset* while the time measuring keeps running.
Add several time pieces to measured total times. This can be achieved by using the toggle* command to start/stop the measuring. At every toggle you get the actual total sum time.

$3

The alarm functionality covers the ability to set/remove several alarms. Generally there are no limitations of the number of active alarms within the node.
The time reference of the alarms relates to the node internal timer value, i.e. there is no relationship to the system time (e.g. UTC time). The internal time counts with the according start/stop commands.
For an explanation see Fig. 9: The programmed timer values are compared to the node internal counter value to determine the alarm time.



Fig. 9: Basic alarm handling



#### Inputs for alarm handling
Alarms are controlled via input msg objects. Supported commands are:
- alarm - adds a new alarm to the node (NOTE: Alarms are not persisted and recovered after restart of Node-RED).
- remove-alarms - cancels and removes all alarms


Input properties for this command are:

payload - text representation of the time when alarm should be triggered. Possible formats are:
- 8:00 - for hours with minutes
- 9:30:30 - for hours with minutes and seconds
- 7.00:00:00 - for days with time
- P1Y2M3DT3H5M42S - for years/month/days/hours/minutes/seconds
- for more options you could check moment.js docs

Especially the last option is very flexible, a few examples:
- P1Y2M3DT3H5M42S: 1 year, 2 months, 30 days, 3 hours, 5 minutes, 42 seconds
- PT8H15M: 8 hours, 15 minutes
- PT1M: 1 minute
- P1M: 1 month

recurrent - optional, use true to send alarm event periodically, default period is the same as alarm time specified by
payload property

period - optional, to specify period of recurrent event if it differs from the alarm time (the same format is used)


#### Outputs for alarm handling

The output msg.payload when an alarm is fired is the same as the msg.payload that was used to add the alarm plus extra properties used in the status command.
The following Fig. 10 shows an example of an output of a cyclic 5 seconds alarm with identification "PT5S".



Fig. 10: msg output of alarm object

$3

The nodes status shows
* an active time count with a green dot (see Fig. 11, left node) and the message of the actual elapsed time,
* the dot also could be red if all alerts are overdue or yellow if some (not all) of alerts are overdue
* a paused/stopped timer with a grey circle (see Fig. 11, right node) with the message of the actual elapsed time.
an alarm with a blue dot and a message "Alarm ... message "*


Fig. 11: Hourglass node status

Error handling

The node emits the following error messages, which may be catched via the catch node.
Errors are signaled via an error message with a payload string giving the error cause.

The following error messages may occur:
- "Not running" - occurs if the node is in stopped state and an input command stop or pause is received
- "Already running" - occurs if the node is in running state and an input command start or resume is received
- "Unknown command: "command" - occurs when an unknown (invalid) command is received
- "Alarm "alarm time" already exists" - occurs when an alarm is already set at the desired alarm time
- "Overdue alarm" - occurs if an alarm is set, but the nodes internal time is already ahead the alarm time

The errors may be caught with the catch node.

Examples

*
Remark: Example flows are present in the examples subdirectory. In Node-RED they can be imported via the import function and then selecting Examples in the vertical tab menue.
*

$3

This example shows how to use the basic commands start, stop, reset and status.



HourglassBasicFlow.json

Fig. 12: Hourglass basic example

$3

This example shows how to use the alarm and remove-alarms command: You can activate three different alarm types, start, stop, reset the timer and clear all timers. In the debug nodes you can evaluate the structure and contents of sent output msg (at the node status and also in the debug window).
In the example, the last elapsed timer was the 5 seconds cyclic timer ("PT5S").

Remark (refer also to Fig. 9): Without starting the timer via the command start no timer is able to elapse.



HourglassAlarmFlow.json

Fig. 13: Hourglass alarm example