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/updates

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

{
    "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"
                }
            }]
        }
    }
}
CODE

State

{
    "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"
                }
            }]
        }
    }
}
CODE

Exporting data to external downstream servers and IT systems