The Hub Listener is a queue-triggered function responsible for validating, transforming and storing the (numerical) sensor data and (non-numerical) actuator data.
¶ Setup
¶ Sensor data format
¶ Snippet
{
"deviceId": "",
"sensorId": "",
"sensorName": "",
"metric": "",
"metricKind": "",
"unit": "",
"timestamp": "",
"value": "",
"interval": "",
}
Properties
-
deviceId - string (required) - The unique identifier of the device. (Balena Id).
-
sensorId - string (required) - The unique identifier of the data stream in the Cofybox system. This property is used to identify which sensor the data belongs to. If no matching sensor-entity is found in the cloud platform, it will automatically be created.
-
SensorName - string (optional) - The human readable name of the data stream in the Cofybox system. This is used as a display name in the cloud platform. If no name is provided the sensorId will be used.
-
metric - string (required) - Identifies what is being measured.
Valid values:GridElectricityImport- Grid energy import (electricity delivered to the building)GridElectricityExport- Grid energy export (electricity flowing away from the building)GridElectricityPower- Grid electricity powerGridElectricityCurrent- Grid electricity currentGridElectricityVoltage- Grid electricity voltageEvElectricityImport- Electric vehicle energy importEvElectricityExport- Electric vehicle energy exportEvElectricityPower- Electric vehicle electricity powerEvElectricityCurrent- Electric vehicle electricity currentEvElectricityVoltage- Electric vehicle electricity voltageHpElectricityConsumption- Heat pump energy consumptionHpElectricityPower- Heat pump electricity powerHpElectricityCurrent- Heat pump electricity currentHpElectricityVoltage- Heat pump electricity voltagePvElectricityProduction- Photovoltaic energy productionPvElectricityPower- Photovoltaic electricity powerPvElectricityCurrent- Photovoltaic electricity currentPvElectricityVoltage- Photovoltaic electricity voltageHeaterElectricityConsumption- Heater energy consumptionHeaterElectricityPower- Heater electricity powerHeaterElectricityCurrent- Heater electricity currentHeaterElectricityVoltage- Heater electricity voltageBatteryElectricityImport- Battery energy importBatteryElectricityExport- Battery energy exportBatteryElectricityPower- Battery electricity powerBatteryElectricityCurrent- Battery electricity currentBatteryElectricityVoltage- Battery electricity voltageBatteryElectricitySoc- Battery electricity state of charge (Soc)BatteryElectricityCharge- Battery electricity chargingBatteryElectricityDecharge- Battery electricity dischargingBatteryElectricityCharging- Battery electricity charging statusIndoorTemperature- Indoor temperatureIndoorTemperatureSetPoint- Indoor temperature set pointOutdoorTemperature- Outdoor temperatureDHWTankTemperature- Domestic hot water tank temperatureMiscellaneous- Miscellaneous categoryState- State of the device or system
-
unit - string (required) - The unit in which the sensor data is expressed. Can be
W,kW,kWh,Wh,V,A,l,m³,kg,km,°C,%,count,none -
metricKind - string (required) - Describes how to interpret the values relative to each other. Valid values:
cumulative- The value constantly increases over time. The value can periodically restart from zero when the maximum possible value of the counter is exceeded.total- The value measures the change to the next recording. Timestamp indicates the start of the measuring window.delta- The value measures the change since it was last recorded. Timestamp indicates the end of the measuring window.gauge- The value measures a specific instant in time. For example, metrics measuring temperature.actuator- The value indicates a state. Can be 0 or 1.
-
timestamp - int (required) - The timestamp of the measurement or the end of the measurement window. The timestamp should be in unix format.
-
value - double | int (required) - The value of the measurement.
-
interval - string (optional) - Indecates the time interval between two datapoints. It tells the hub listener in which table the data should be stored and to which intervals it should be downsampled. Default is 5 minutes. Valid values:
PT5M,PT15M,PT1H,P1D,P1M.
¶ Storage
There is an Azure Storage table for each resolution. Every partition corresponds with one time series and every row contains one data point.
The sensorId of the Service Bus message is used as the partitionKey.
The rowKey is calculated from a reversed timestamp.
¶ Downsampling
The series downsampler is invoked after data is stored to the table storage. The invoking process indicates which period should be recalculated for which resolution. The downsampler queries the correct table, aggregates the data to the requested resolution and saves it the table storage.
This process is repeated until the periods affected by the new datapoint are recalculated for all the defined resolutions.
Aggregation rules are different for different metricKinds.
cumulative
Save the value at the first timestamp of the grouping.
A count of datapoints in the grouping is also stored as context information.
total
Save the sum of the values in the grouping at the first timestamp of the grouping.
A count of datapoints in the grouping is also stored as context information.
delta
Save the sum of the values in the grouping at the last timestamp of the grouping.
A count of datapoints in the grouping is also stored as context information.
gauge
Save the minimum, maximum and mean of the values in the grouping at the first timestamp of the grouping.
A count and sum of datapoints in the grouping is also stored as context information.
¶ Actuator data format
¶ Snippet
{
"deviceId": "",
"sensorId": "",
"sensorName": "",
"metricKind": "",
"timestamp": "",
"value": "",
}
Properties
- deviceId - string (required) - The unique identifier of the device. (Balena Id).
- sensorId - string (required) - The unique identifier of the data stream in the Cofybox system. This property is used to identify which sensor the data belongs to. If no matching sensor-entity is found in the cloud platform, it will automatically be created.
- SensorName - string (optional) - The human readable name of the data stream in the Cofybox system. This is used as a display name in the cloud platform. If no name is provided the sensorId will be used.
- metricKind - string (required) - Describes how to interpret the values. Valid values:
actuator- The value indicates a state.
- timestamp - int (required) - The timestamp of the state change. The timestamp should be in unix format.
- _value - string - The value of the state on the moment it changed.
¶ Storage
There is single Azure Storage table for actuator values. Every partition corresponds with one time series and every row contains one data point.
The sensorId of the Service Bus message is used as the partitionKey.
The rowKey is calculated from a reversed timestamp.