Datastreams

We will use websocat to for simple demonstrations. For an example Python script, see sending messages.

Prerequisites

Authentication (see authentication)
A valid topic (see topic structure).

Gridsense can only store data in the SenML format. However, you may still send data in any format you wish, and have it be parsed by a rule and transformed into a valid SenML array. See create complex data flows with rules for a step-by-step tutorial.

For example, you may send data as plain JSON, then have it go through a rule that parses that JSON data and transforms it into valid SenML array.

In the examples below, we will be sending data that is already structured in SenML.

# Connect to a specific channel
$ websocat wss://api.gridsense.cloud/ws/m/<organization>/c/<channel>?authorization=<device secret>

# Send messages by simply typing them into the terminal:
[{"bn": "org/lighting/SmartLight/", "n": "brightness", "u": "lm", "v": 100}] # hit enter to send

Constraints

For each message object in the SenML array:

A unique n field must be present.
Only one value field must be present (only one of v, vs, vb, vd).
The fields bn, u, and t are optional.

Sending data is the first of two steps to store your data in Gridsense. For the sent data to actually be stored and usable across the different Gridsense services, you will need to set up a rule. See create complex data flows with rules for a step-by-step tutorial.

Send batched data to Gridsense

In some cases, it might be necessary to send multiple pieces of data at the same time.

# Connect to a specific channel
$ websocat wss://api.gridsense.cloud/ws/m/<organization>/c/<channel>?authorization=<device secret>

# Send messages by simply typing them into the terminal:
[{"bn": "org/lighting/SmartLight/", "n": "brightness", "u": "lm", "v": 100}, {"n": "power", "u": "W", "v": 150}]

The same constraints mentioned in the above section also apply here. See constraints.

One example where this is useful is when sending the location data of a device, which is used by the Route Map widget to display real-time location updates on an interactive map.

When setting up the widget, you will need to provide the names (bn + n fields of the SenML objects) of both the latitude and longitude values.

Route Map widget settings

In this case, you could send the device's location data like so:

$ websocat wss://api.gridsense.cloud/ws/m/<organization>/c/<channel>?authorization=<device secret>

[{"bn": "urn:dev:location:gps:", "n": "longitude", "u": "lon", "v": 31.50161}, {"n": "latitude", "u": "lat", "v": 34.46672}]

Then, in the Route Map widget settings, you would fill out the fields "Longitude value name" and "Latitude value name" with "urn:dev:location:gps:longitude" and "urn:dev:location:gps:longitude" respectively.

Get live data from Gridsense

You can get real-time updates by simply connecting to a channel (and a subtopic):

# Connect to a specific channel. This allows us to both listen to and send messages.
$ websocat wss://api.gridsense.cloud/ws/m/<organization>/c/<channel>?authorization=<device secret>

# New messages will be shown here in the terminal.

You may also use MQTT wildcards like # and + in the topic:

# Connect to a specific channel. This allows us to both listen to and send messages.
$ websocat wss://api.gridsense.cloud/ws/m/<organization>/c/<channel>/%23?authorization=<device secret>

# New messages will be shown here in the terminal.

Notice that the # character must be percent-encoded, which is what the %23 in the example above refers to.

If you're not seeing incoming data, make sure you have set up a rule to process and store incoming data to that specific channel. See create complex data flows with rules for a step-by-step tutorial.

Troubleshooting

My device is sending valid, well-structured SenML data but it's not being stored, displayed in widgets, read by other devices, listed under the channel's messages, etc

Make sure you have set up a rule to save the incoming data. See create complex data flows with rules.