Counting and adding up.
Description
This event handler is used to provide counters and accumulators. The 'Counter' may be incremented or decremented by an amount on a trigger event. When thresholds are reached events may be sent. The contents of counters may be sent on a trigger event and the value may be reset by another trigger event.
This event handler maintains a state table in memory that is updated by configured events, when this table is updated then the action defintions are checked to see whether an update to the state table should cause an action to be performed. In the future this state table may be totally or partially persisted through an WebBrick Gateway restart.
Configuration
The configuration for this handler is split into to two parts
- The first is our normal set of event source and type filters along with the main actions that
can be performed, increment, decrement, newEvent and reset.
The action element contains zero or more of each of the following elements.
- newEvent
- increment
- decrement
- reset
There then will be 1 or more counter elements. Each element has the following attributes.
- name - mandatory, must be unique.
- minimum - lowest value for counter, may be used as reset value if not given.
- maximum - highest value for counter, may be used as reset value if not given.
- type - either int (integer counter) or float (accumulator)
The elements are processed in the order increment, decrement, reset, newEvent so that new events get the value after the processing steps. If you want the value before reset specify the newEvent as part of reset processing and not independantly. Generally it is expected that you will not want to see the running count of a fast changing counter.
Logging
This handler uses the logging stream 'EventHandlers.Counters'.Debug
At startup the configured counter elements will be logged.Example 1
This example is counting the number of times the entry door has been opened. It uses the default counter type. Once an hour it sends the count and resets the value.
<?xml version="1.0" encoding="utf-8"?>
<eventInterfaces>
<eventInterface module='EventHandlers.Counters' name='Counters'>
<!-- All counters must be declared -->
<counter name="entryCount"/>
<eventtype type="http://id.webbrick.co.uk/events/webbrick/TD">
<eventsource source="webbrick/21/TD/0" >
<event>
<increment name="entryCount" />
</event>
</eventsource>
</eventtype>
<eventtype type="http://id.webbrick.co.uk/events/time/hour">
<eventsource source="time/hour" >
<event>
<reset name="entryCount">
<newEvent type="test/entryCount" source="test/entryCount">
<copy_other_data val="entryCount" />
</newEvent>
</reset>
</event>
</eventsource>
</eventtype>
</eventInterface>
</eventInterfaces>
Example 2
This example is measuring power consumption using a metering device that triggers for each 0.5W or power used. It specifies the by attribute for the increment and uses the counter of float.
<?xml version="1.0" encoding="utf-8"?>
<eventInterfaces>
<eventInterface module='EventHandlers.Counters' name='Counters'>
<!-- All counters must be declared -->
<counter name="powerUse" type="float"/>
<eventtype type="http://id.webbrick.co.uk/events/webbrick/TD">
<eventsource source="webbrick/21/TD/1" >
<event>
<increment name="powerUse" by="0.5"/>
</event>
</eventsource>
</eventtype>
<eventtype type="http://id.webbrick.co.uk/events/time/minute">
<eventsource source="time/minute" >
<event>
<reset name="powerUse">
<newEvent type="test/power/this/minute" source="test/power/this/minute">
<copy_other_data val="powerUse" />
</newEvent>
</reset>
</event>
</eventsource>
</eventtype>
</eventInterface>
</eventInterfaces>
Example 3
This example just aims to show all possible configurations attributes.
<?xml version="1.0" encoding="utf-8"?>
<eventInterfaces>
<eventInterface module='EventHandlers.Counters' name='Counters'>
<eventtype type="http://id.webbrick.co.uk/events/time/minute">
<eventsource source="time/minute" >
<event>
<!-- all three are optional -->
<increment name="count1" limit="1000" by="" resetvalue="0">
<!-- if limit is reached then send newEvent and clear -->
<newEvent type="test/1" source="test/1">
<copy_other_data val="count1" />
</newEvent>
</increment>
<decrement name="count1" resetvalue="0" by="2">
<!-- if 0 is reached then send newEvent and set to resetvalue -->
<newEvent type="test/1" source="test/1">
<copy_other_data val="count1" />
</newEvent>
</decrement>
<newEvent type="test/1" source="test/1">
<!-- used to send a counter -->
<copy_other_data val="count1" />
</newEvent>
<reset name="count1" resetvalue="0" >
<!-- send newEvent and set to resetvalue -->
<newEvent type="test/1" source="test/1">
<copy_other_data val="count1" />
</newEvent>
</reset>
</event>
</eventsource>
</eventtype>
<!-- All counters must be declared -->
<counter name="count1" minimum="0" maximum="2147483647" type="int|float"/>
</eventInterface>
</eventInterfaces>