Entity

A device/entity is the core unit in ODevice. It represents a physical or logical thing (pump, sensor, greenhouse) with named properties and stateless actions.

Purpose

Model one IoT thing with its data schema, current state, and operations. Entities map to "devices" in the UI.

Canonical model:

Entity
├─ Properties  (state: Number, Boolean, Enum, String, Location)
└─ Actions     (stateless operations: reset, calibrate, start, stop)

Signature

Device(
    id: str,            # unique identifier, e.g. "pump-01"
    name: str,          # human-readable name, e.g. "Main Pump"
    properties: dict,   # { "pressure": Number(...), ... }
    type: str | None,   # optional type tag, defaults to slugified name
)

Actions

pump.action("reset", label="Reset Pump", icon="reset", severity="danger", confirm="Sure?")

@pump.on_action("reset")
async def do_reset():
    ...

Actions are buttons (no state, no value), sent via POST /actions.

Minimal example

from odevice import App, Device, Number

device = Device(id="d1", name="Sensor", properties={"temp": Number()})
app = App("Demo")
app.add(device)

Complete example

pump = Device(
    id="pump-01",
    type="pump",
    name="Main Pump",
    properties={
        "pressure": Number(unit="bar", min=0, max=10, view="gauge"),
        "power": Boolean(writable=True),
    },
)
pump.action("reset", label="Reset Pump")
app.add(pump)

Constraints

• id must be unique within an App
• properties keys must be valid identifiers
• type defaults to name.lower().replace(" ", "-")

Common mistakes

• Reusing the same id for two devices → raises ValueError
• Forgetting app.add(device) → device not exposed in manifest
• Registering on_action before calling device.action() → raises ValueError

Generated schema

{
  "id": "pump-01",
  "type": "pump",
  "name": "Main Pump",
  "properties": { "...": "..." },
  "actions": [ { "id": "reset", "label": "Reset Pump", "severity": "normal" } ]
}