Data

Data includes both the measured values (metrics) and the conditions/state of the device. The ThingsHub provides four tools to work with and organize data: Data Tables, Dashboards, Integrations, and the built-in message broker.

Storing, monitoring, & analyzing device telemetry data

Data tables. Store, organize, and inspect data from multiple devices in a single place.
- By default, device data is only stored temporarily in the thingsHub. To store data for a longer term, you will need to create a data table.
- Data tables are used to store and monitor data from multiple devices that have been grouped according to a shared characteristic called a label.
- The stored data can then be used to visualize the data in Dashboards. Data stored in data tables can also be exported, such as CSV files exported to an external SFTP server.
- To view existing an existing table's data, go to Data > Data Tables and select the table's Edit button.
Integrations: Forward data from one or multiple devices to external systems.
- Integrations can be created for different target systems and protocols.
- Like for Data Tables, which data to forward is selected based on the devices' labels.
Dashboards. Visualize, analyze and monitor data from one or multiple devices.
- Information from the Data Table is also used to present data in the visualizer dashboard. The Data Table can also be used on the Dashboards page for visualization and alerting.

Subscribing to data via the built-in message broker

The thingsHub provides a built-in, MQTT-based message broker, to which you can subscribe to receive live sensor data.

Accessing the built-in message broker

The message broker is accessible via a websocket interface. To access this interface, use the following connection information:

Parameter	Description
Host	Your tenant’s URL, e.g. https://your-company.eu1.thingshub.com
Port	443 (currently, only MQTT over websocket is supported)
Schema	Secure websocket (WSS)
Path	/mqtt
Username	Use your thingsHub username
Password	Use your thingsHub password
Topic	One of the topic names documented below
Keep Alive	< 60s

The below table provides topic descriptions:

Topic	Description
`thingshub/devices/:device-id/data`	Updates to the device’s data table
`thingshub/devices/:device-id/state`	Updates to the Device’s state
`thingshub/devices/:device-id/uplink`	Raw device uplinks (with metadata)
`:mqtt-integration`	Data from the devices

For descriptions of the message formats, see the section Native Output Format below.

Examples for basic topic subscriptions

To subscribe to all devices’ data updates using a single subscription, use MQTT's wildcard operator, e.g.thingshub/devices/#/updates to receive all uplinks.
To subscribe to the device my-device’s data updates, use thingshub/devices/my-device/updates.
To subscribe to state updates for all devices using a single subscription, use thingshub/devices/#/state.
If you want to subscribe to a subset of devices instead of only a single one or all of them, create a built-in MQTT broker integration, then subscribe to the topic shown in that integration.

Native Data Format

The built-in MQTT broker, the external MQTT-broker, and the websocket integration all use the thingsHub’s native data format in its messages. This format exists for updates and state messages and is documented below for each.

Uplinks

CODE

{
    "bandwidth": <bandwidth in kHz as an integer, e.g. 125>,
    "bit_rate": <bit rate as an integer>,
    "coding_rate": "<coding rate, the fraction of non-redundant bits to the total number of bits as a string, e.g. 4/5>",
    "data_rate": "<spreading factor, bandwidth and coding rate a string, e.g. SF7 BW125 4/5>",
    "dev_eui": "<64-bit as hex value string, e.g. 0001020304050607>",
    "f_cnt_up": <uplink frame counter as integer, e.g. 21144>,
    "f_port": <integer: frame port, e.g. 125>,
    "frequency": <radio frequency in kHz^-6 as integer, e.g. 867100000>,
    "modulation": "<modulation scheme as string, e.g. LORA>",
    "network_server_time": "<RFC-3339 timestamp as string, e.g. 2006-01-02T15:04:05Z",
    "raw_payload": "<the raw payload as a hex-encoded string, e.g. 110a000c0055393ba15468>",
    "receptions": [{
        "gateway": "",
        "rssi": -69,
        "snr": 9.2,
        "time": "2019-02-27T15:23:37.311Z"
    }],
    "rssi": -69,
    "snr": null,
    "spread_factor": 7,
    "time": "2019-02-27T15:23:37.311Z",
    "uplink_metadata": {
        "id": "4-70b3d5e75e00470c-5",
        "name": "",
        "driver": "",
        "labels": null,
        "state": {
            "desired": {
                 
            },
            "reported": {
                "RawPayload": "110a000c0055393ba15468"
            }
        },
        "last_data_received": {
            "received_at": "2019-02-27T15:23:37.56722709Z",
            "raw": "110a000c0055393ba15468"
        },
        "connectivity": {
            "connections": [{
                "network_server_id": 4,
                "network_device_id": "70B3D5E75E00470C",
                "network_server": {
                    "id": 4,
                    "name": "Loriot over insecure TLS"
                }
            }]
        }
    }
}

State

CODE

{
    "RawPayload": "110a000c0055393ba15468",
    "update_metadata": {
        "id": "4-70b3d5e75e00470c-5",
        "name": "",
        "driver": "",
        "labels": null,
        "state": {
            "desired": {
                 
            },
            "reported": {
                "RawPayload": "110a000c0055393ba15468"
            }
        },
        "last_data_received": {
            "received_at": "2019-02-27T15:23:37.56722709Z",
            "raw": "110a000c0055393ba15468"
        },
        "connectivity": {
            "connections": [{
                "network_server_id": 4,
                "network_device_id": "70B3D5E75E00470C",
                "network_server": {
                    "id": 4,
                    "name": "Loriot over insecure TLS"
                }
            }]
        }
    }
}

Exporting data to external downstream servers and IT systems

See Integrations