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.).
Fig. 1: Node appearance
In Node-RED (preferred)
- Via Manage Palette -> Search for "node-red-contrib-hourglass"
In a shell
- go to the Node-RED installation folder, e.g.:
npm install node-red-contrib-hourglass
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.
Time measuring function
The time measuring covers the functionality of a typical stopwatch.
Inputs for time measuring function
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
node-red-contrib-hourglass node contains the following output properties within its sent
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
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.
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
period - optional, to specify period of recurrent event if it differs from the alarm time (the same format is used)
Outputs for alarm handling
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".
msg output of alarm object
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 "
Hourglass node status
The node emits the following error messages, which may be catched via the
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
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.
Basic time measuring example (start, stop, reset, status)
This example shows how to use the basic commands start, stop, reset and status.
Hourglass basic example
Alarm handling example
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.
Hourglass alarm example