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 firmware | Type | Works well with |
|---|---|---|
doc["temperature"] = 21.5; | number | Graph, Gauge, Bar graph, Text, Slider |
doc["ledOn"] = false; | true/false | Switch, Text |
doc["status"] = "Armed"; | text | Text |
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 pointA 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.