65. Daily Limit Tracking¶

The goal of this recipe is to track the amount an accumulating property goes over a specific threshold, or limit, on a daily basis. For example, imagine you have an energy meter and are tracking the amount of energy consumed on a wattHours property. You need to be able to track the amount of energy consumed on each day, but only after 1 kWh has been consumed. Put another way, you want to track how much energy is consumed over a 1 kWh limit, each day.

Conceptually, let's say we want to add a wh_overLimit accumulating property to our meter datum stream. The data looks like this (note the Over Today column is just for display and not actually included on the datum stream):

65.1 Overview¶

To satisfy our goal, SolarNode must be able to "remember" the previous value seen on the wattHours and wh_overLimit properties, as well as the value seen on the wattHours property at the start of the day.

With the help of expresions making use of Local State entities, SolarNode can track when a datum is captured on a new day, to facilitate resetting the "start of day" energy reading. Then a Virtual Meter can be used to track the "over limit" energy accumulation.

For each datum that is evaluated, SolarNode will execute the following logic to maintain the "start of day" energy reading:

1. if the datum is starting a new day or there is no recorded "start of day" energy reading,
2. then the "start of day" energy reading Local State should be set to this datum's wattHours value

Then a Virtual Meter will be used with an expression to track the amount of "daily over limit" energy.

The overall steps of this recipe are:

• add a Parameter Expression filter PEX - Day Period to track day periods and "start of day" energy readings as parameters
• add a Virtual Meter filter VM - Day Over Limit to calculate the wh_overLimit property
• add both of these added filters to the Main filter chain

65.2 Parameter Expression¶

Parameters created by the Parameter Expression filter are variables available to subsequent filters within the filter processing pipeline. They do not become datum properties, and thus act like temporary variables. We will use a Parameter Expression to create a day_changed parameter that will be true when a new day has started or false otherwise. Another expression will be used to create a wattHours_startOfDay parameter that will be set to the wattHours property value seen on the first datum seen on each day.

In order to know if the current day is new, we need to be able to compare it to the day the previous datum fell within. To do this, we'll calculate the start of the current day as a Unix epoch seconds number, and save that on a day-timestamp Local State entity. We can use the result of the changeLocalState() function to tell us when the day-timestamp has changed, thus signaling that a new day has begun.

Then, using the day_changed parameter we can maintain a separate wattHours_startOfDay parameter in a wh-startofday Local State entity.

Create a Parameter Expression filter component:

1. Go to the Settings > Datum Filters page.
2. Scroll down to the User Datum Filters section.
3. Click the Manage button next to the Parameter Expression Datum Filter item.
4. Click the + Add new Parameter Expression Datum Filter button.

Configure the component with the following settings:

Add two new Expression settings by clicking on the + button next to Expressions twice, then configure these expression settings:

changeLocalState('day-timestamp', epochSecs(startOfDay()))

1
2
3

day_changed || !hasLocalState('wh-startofday')
? saveLocalState('wh-startofday', wattHours)
: localState('wh-startofday', wattHours)

The component settings should look like this:

65.3 Virtual Meter¶

Traditionally the Virtual Meter filter is used to derive an accumulating meter-style reading property from an instantaneous property. For example you could derive an accumulating wattHours property from an instantaneous watts property. The filter allows you to use expressions to calculate the accumulated output, however, so we can actually use this filter for a variety of use cases. What makes it compelling to use for this recipe is that a Virtual Meter automatically tracks the previous "input" value for you and provides that as a previousInput variable, as well as the current accumulated output value as a previousReading variable.

We can use these features of a Virtual Meter to derive our accumulating wh_overLimit property out of the accumulating wattHours property, along with the wattHours_startOfDay parameter we set up in the previous section.

Create a Virtual Meter filter component:

1. Go to the Settings > Datum Filters page.
2. Scroll down to the User Datum Filters section.
3. Click the Manage button next to the Virtual Meter Datum Filter item.
4. Click the + Add new Virtual Meter Datum Filter button.

Configure the component with the following settings:

Add a new Virtual Meters setting by clicking on the + button next to Virtual Meters, then configure these settings:

Add a new Expressions setting by clicking on the + button next to Expressions, then configure these settings:

Here is the expression to configure:

1
2
3
4

has('wattHours_startOfDay') && (currInput - wattHours_startOfDay - 1000) > 0
? prevReading + ((currInput - wattHours_startOfDay - 1000)
                  - max(0, prevInput - wattHours_startOfDay - 1000))
: prevReading

The component settings should look like this:

65.4 Monitoring the Local State¶

Once you have this recipe deployed, you can use the Local State management page to monitor their values. You should see entities like the following:

The values will change over time, as datum are processed and the expressions configured for this recipe perform their work.

65.5 Parting thoughts¶

This recipe can easily be adapted to handle other time periods like 15 minutes, 4 hours, 1 month, and so on. The time period just needs to evenly multiply into its next-higher time period, like minutes into hours, hours into days, and so on.

To do this you would adjust the expressions in this recipe to use the desired time periods, and adjust the names used appropriately. For example to use a 4-hour period, this configuraiton would be used:

changeLocalState('report-period-timestamp', epochSecs(dateFloor(nowTz(), 'PT4H')))

reportPeriod_changed || !hasLocalState('wh-startof-report-period')
? saveLocalState('wh-startof-report-period', wattHours)
: localState('wh-startof-report-period', wattHours)

has('reportPeriod_changed') && (currInput - wattHours_startOfReportPeriod - 1000) > 0
? prevReading + ((currInput - wattHours_startOfReportPeriod - 1000)
                - max(0, prevInput - wattHours_startOfReportPeriod - 1000))
: prevReading