Concepts

Node

A node is a single ESP32 based product. It has an associated identifier (node_id) and a set of credentials provided by the claiming service. Users can give a friendly name to the node. A single node can expose multiple devices.

Node attributes

These are optional, custom metadata for a given node, something like a serial number.

Devices

A device is a logical user-controllable entity like a Switch, Lightbulb, Thermostat, Temperature Sensor, etc. A simple node will generally have a single device. However, an ESP32 can also have multiple devices like say 2 switches on a single board, or it can act as a bridge for other devices like say BLE sensors. Each device must have a unique name within the node, and optionally, a type.

Device Attributes

Similar to node attributes, these are additional, user-defined, read-only name-value pairs which act as metadata for the device. These can be something like firmware version, serial number, etc. These will be especially useful when there are multiple devices bridged to the node (Eg. Wi-Fi to wired network/BLE/Zigbee, etc.).

Parameters

These are control and monitoring parameters of a device. Eg. On/Off power state, brightness, current/target temperature, etc. All such parameters must have a unique name within the device. These parameters can also have additional fields like value, type, bounds, UI Information, etc. The parameters values can be boolean, integer, float or string.

Services

A service is an entity very similar to device in terms of the structure, with the main difference that it is meant for operations that may not necessarily be need to be user visible. A typical example of this is OTA Firmware Upgrade Service, which can have parameters like url, status, etc.