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. You can give a friendly name to the node. A single node can expose to multiple devices.

Node Attributes

Node Attributes are optional and custom metadata for a given node, something like a serial number.

Devices

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

Device Attributes

Similar to node attributes, device attributes are additional, user-defined, and read-only name-value pairs that act as metadata for the device. They can include information such as firmware version, serial number. These attributes are particularly useful when there are multiple devices bridged to the node, such as Wi-Fi to wired network, BLE, Zigbee, etc.

Parameters

Parameters refers to control and monitoring parameters of a device, such as the ON/OFF power state, brightness, current/target temperature, etc. All such parameters must have a unique name within the device. They 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 that is very similar to a device in terms of its structure, with the main difference being that it is designed for operations that may not necessarily need to be visible to the user. A typical example of this is the OTA Firmware Upgrade Service, which can have parameters like url, status, etc.