Datastreams and keys
A datastream is one channel of data on a template: what people call it, the key the device writes it under, and how its values are shown.
Fields
| Field | What it does |
|---|---|
| Name | What people see on dashboards, in alerts and in the assistant's answers. Use words a colleague would understand: Supply temperature, Pump running. |
| Key | The short name the device code writes readings to and receives commands on, such as temperature. Unique within the template. |
| Data type | How values are read. See below. |
| Units | Shown beside every value, such as °C, bar or kWh. |
| Decimal places | 0 to 3. How many decimals widgets show. |
| Min and Max | The expected range. Gauges and level bars are drawn between them. |
| Default value | Shown before the first reading arrives. |
Keys
The name is for people and can be anything: Supply temperature (°C). The key is for code: short, exact, and the same in every device built from the template.
- Lower case: a letter first, then letters, digits or
_. - Up to 11 characters, which fits every supported board.
- Unique within the template.
- Not one of the words a device report uses for itself:
evt,ts,signal,rssi,uptime,fw.
| Good keys | Why not |
|---|---|
temperature, supply_temp, pump, flow_rate, door | Supply Temp (space, capitals), 2nd_pump (starts with a digit), supply_temperature (longer than 11) |
Changing a key later means changing the device code too, so choose it before the first device goes out.
Use keys in code
Write readings to the key and register a handler for each key that receives commands. The code then reads like the equipment it runs.
void onPump(String key, String value) {
digitalWrite(5, value == "1" ? HIGH : LOW);
}
void setup() {
MaxwellTrack.onWrite("pump", onPump);
MaxwellTrack.begin(DEVICE_ID, AUTH_TOKEN, WIFI_SSID, WIFI_PASS);
}
void loop() {
MaxwellTrack.run();
// ...on a timer:
MaxwellTrack.write("supply_temp", 61.4);
MaxwellTrack.write("return_temp", 48.9);
}Data types
| Type | Example | Use it for |
|---|---|---|
| Integer | 42 | Counts, percentages, on and off as 0 and 1 |
| Double | 21.5 | Temperatures, pressures, voltages, flow |
| Boolean | true | Flags such as door open |
| String | "defrosting" | Modes and status text |
| Geolocation | Positions shown on map widgets | |
| JSON | {"phase": 2} | Several related values kept together |
Datastreams belong to the template, so adding one gives it to every device made from that template. Devices that never write the new key simply show no value for it.
Numbered keys
Templates made earlier may use numbered keys such as V0 or D2. They keep working exactly as before, in the code, on dashboards and in automations.
Something unclear or out of date on this page? Tell support.
