Entities

Entities

An entity is a single named value your device reports. Entities are what dashboard elements point at — every graph, gauge, switch and text box shows one.

Where entities come from

You don’t create entities anywhere in the interface. They come straight from your firmware: every key in the object you fill in sendStatus becomes an entity.

.sendStatus = [](JsonDoc doc) {
    doc["temperature"] = 21.5;
    doc["humidity"]    = 48;
    doc["ledOn"]       = false;
    doc["status"]      = "Armed";
},

That device has four entities: temperature, humidity, ledOn and status. Open its dashboard, add an element, and those four names are in the entity dropdown.

Add a key to sendStatus and it appears in the list the next time the device reports. Remove one and it stops being offered. Nothing to configure on the platform side.

Types and what they’re good for

The type of the value decides which elements make sense:

Value in firmwareTypeWorks well with
doc["temperature"] = 21.5;numberGraph, Gauge, Bar graph, Text, Slider
doc["ledOn"] = false;true/falseSwitch, Text
doc["status"] = "Armed";textText

Nothing stops you putting a text entity on a gauge — it just won’t show anything useful.

Naming

Names are yours to choose, but a few things help:

  • Keep them stable. Renaming a key in firmware doesn’t rename it on existing dashboard elements; they’ll simply stop finding their value.
  • Short names read better in a narrow dashboard column.
  • Use the same name across similar devices, so a dashboard you export from one can be imported into another.

connectionHistory

Every device has one entity you didn’t create: connectionHistory. It records when the device was online and offline, and is useful on a graph for spotting a device that keeps dropping out.

Entities that change from the platform

Some elements write back. A Switch or a Slider bound to an entity sends the new value down to the device, where your entityChanged callback receives it:

.entityChanged = [](JsonDoc doc) {
    // fired when someone moves a slider or flips a switch
},

doc["user"] says who did it, the same as for commands.

A switch doesn’t move on its own say-so — it shows what the device last reported. A flip goes down to the device, and the switch settles when the device next reports its status:

If sendStatus doesn’t include the new value, that next report puts the switch back where it was — the usual cause of a switch that “won’t stay on”.

So an entity can be read-only (a sensor reading) or two-way (something you control), depending on which element you point at it.

Live values and history

While a dashboard is open, values arrive live — most elements show whatever the device last reported and update as it changes.

Keeping history is separate. A device stores a data point only when it reports its status with saving switched on, which your firmware controls:

sc.sendStatusWithSocket(true);   // report and store this point

A Graph draws that stored history, so a device that never saves will show a live value but an empty graph. Call it when a reading actually changes rather than on every loop — you’ll get a readable graph instead of thousands of identical points.