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 power
  - `GridElectricityCurrent` - Grid electricity current
  - `GridElectricityVoltage` - Grid electricity voltage
  - `EvElectricityImport` - Electric vehicle energy import
  - `EvElectricityExport` - Electric vehicle energy export
  - `EvElectricityPower` - Electric vehicle electricity power
  - `EvElectricityCurrent` - Electric vehicle electricity current
  - `EvElectricityVoltage` - Electric vehicle electricity voltage
  - `HpElectricityConsumption` - Heat pump energy consumption
  - `HpElectricityPower` - Heat pump electricity power
  - `HpElectricityCurrent` - Heat pump electricity current
  - `HpElectricityVoltage` - Heat pump electricity voltage
  - `PvElectricityProduction` - Photovoltaic energy production
  - `PvElectricityPower` - Photovoltaic electricity power
  - `PvElectricityCurrent` - Photovoltaic electricity current
  - `PvElectricityVoltage` - Photovoltaic electricity voltage
  - `HeaterElectricityConsumption` - Heater energy consumption
  - `HeaterElectricityPower` - Heater electricity power
  - `HeaterElectricityCurrent` - Heater electricity current
  - `HeaterElectricityVoltage` - Heater electricity voltage
  - `BatteryElectricityImport` - Battery energy import
  - `BatteryElectricityExport` - Battery energy export
  - `BatteryElectricityPower` - Battery electricity power
  - `BatteryElectricityCurrent` - Battery electricity current
  - `BatteryElectricityVoltage` - Battery electricity voltage
  - `BatteryElectricitySoc` - Battery electricity state of charge (Soc)
  - `BatteryElectricityCharge` - Battery electricity charging
  - `BatteryElectricityDecharge` - Battery electricity discharging
  - `BatteryElectricityCharging` - Battery electricity charging status
  - `IndoorTemperature` - Indoor temperature
  - `IndoorTemperatureSetPoint` - Indoor temperature set point
  - `OutdoorTemperature` - Outdoor temperature
  - `DHWTankTemperature` - Domestic hot water tank temperature
  - `Miscellaneous` - Miscellaneous category
  - `State` - 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.