Time Series Data

In RainMaker, any dynamic value is reported as a parameter update. The new value overwrites the older value in the cloud backend and the phone apps and other clients can read only this latest value. Any historical information of the value and their timestamps are lost. This is sufficient for most use cases like outlets, lights, etc. where only the instantaneous value is important. However, certain parameters like energy consumption and temperature sensor readings require some historical data, which can be visualized as a graph by the end users. For such use cases, RainMaker has a concept of time series data.

Variants

The RainMaker Time Series Data has 2 variants:

• Full featured time series data : Supports raw values as well as latest, min, max, count, average and sum for a given time window. These additional options are called as "aggregates" in the API.
• Simple time series data: Supports only raw values. Typically useful for keeping a timestamped track of events. This is cost efficient and should be used if raw values are sufficient for the use case.

Simple time series data was introduced in RainMaker backend v2.0.1 and does not required AWS Timestream service.

Usage

To use time series data, just include PROP_FLAG_TIME_SERIES (full featured time series) or PROP_FLAG_SIMPLE_TIME_SERIES (simple time series) flag in the properties while creating a RainMaker parameter.

Eg.

esp_rmaker_param_t *param = esp_rmaker_param_create("Temperature", ESP_RMAKER_PARAM_TEMPERATURE,
             esp_rmaker_float(15.5), PROP_FLAG_READ | PROP_FLAG_TIME_SERIES);
esp_rmaker_param_t *param = esp_rmaker_param_create("Mode", ESP_RMAKER_PARAM_MODE,
             esp_rmaker_int(1), PROP_FLAG_READ | PROP_FLAG_SIMPLE_TIME_SERIES);

After adding these parameters to devices, the corresponding node configuration will show them as below (note the properties):

[
    {
        "name": "Temperature",
        "type": "esp.param.temperature",
        "data_type": "float",
        "properties": [
            "read",
            "time_series"
        ]
    },
    {
        "name": "Mode",
        "type": "esp.param.mode",
        "data_type": "int",
        "properties": [
            "read",
            "simple_ts"
        ]
    }
]

Thereafter, using esp_rmaker_param_update_and_report() will update both, the instantaneous value as well as the time series value of the parameter.

Specifications

Both the time series data variants use special MQTT topics and data formats for reporting the data.

Full featured time series data

This allows reporting multiple parameters and their multiple records in a single MQTT message.

• Topic node/<node_id>/tsdata
• Operation: PUBLISH
• Data:

{
    "ts_data_version": "2021-09-13",
    "ts_data": [
        {
            "name": "<param_name>",
            "dt": "<int/float/bool/string>",
            "records": [
                {
                    "t": <epoch_timestamp>,
                    "v": <value>
                },
                {
                    more records...
                }
            ]
        },
        {
            more parameters...
        }
    ]
}

• Example:

{
    "ts_data_version": "2021-09-13",
    "ts_data": [
        {
            "name": "Temperature Sensor.Temperature",
            "dt": "float",
            "records": [
                {
                    "t": 1699468430,
                    "v": 26.5
                }
            ]
        }
    ]
}

Simple time series data

This allows reporting only a single parameter's single data point in an MQTT message.

• Topic node/<node_id>/simple_tsdata
• Operation: PUBLISH
• Data:

{
    "name": "<param_name>",
    "dt": "<int/float/bool/string>",
    "t": <epoch_timestamp>,
    "v": <value>
}

• Example:

{
    "name": "Temperature Sensor.Temperature",
    "dt": "float",
    "t": 1704189730,
    "v": 25.5
}

Note that the parameter names in the examples are a combination of device name and parameter name. This is just for the phone apps to link to appropriate parameter in the node configuration. However, at a specification level, time series data is independent of other RainMaker concepts like device, parameters, etc. allowing to use this independently, if required.