Device management overview
Device management is everything between a signed-in user and working hardware: onboarding a device into your ESP RainMaker Neo deployment, then reading and controlling it. This section covers both halves; provisioning, which turns a device into a node, and the node APIs that follow.
Use it once you have a user from User management. Organising nodes into homes and rooms is Group management.
The two halves
Provisioning works on ESPDevice, which represents hardware before it has a node ID; the app reaches it over BLE or SoftAP, proves it belongs to the user, and hands it Wi-Fi credentials. Start at Provisioning.
Everything after works on ESPRMNeoNode, the object an app spends most of its time with: configuration, devices and services, connectivity, and the transports it is reachable over. You get nodes from a group, never by constructing them:
const nodes = await home.getNodes();
const node = await home.getNode("<node-id>");
See Manage groups for the caching options both take.
The hierarchy
A node carries devices and services; each carries parameters. Parameters are what you read and write.
A device is something the user recognises; a light, a fan, a switch. A service is node-level machinery the user does not think of as a device, such as time and timezone. The distinction matters because they are reached through different properties and their parameter classes differ slightly.
What a node carries
| Property | Contents |
|---|---|
nodeId | Identifier used in every node call |
groupId | Root group this node was read through |
subgroupIds | Every subgroup membership under that group |
devices | ESPRMNeoDevice instances |
services | ESPRMNeoService instances |
config | Configuration snapshot |
connectivityStatus | isConnected and lastConnectionTimestamp |
availableTransports | Transports usable right now |
transportOrder | Priority order for this node |
config.devices and config.services are the same instances as devices and services, not copies; reading either gets you the live objects.
Finding a device or a parameter
Match by name for a device you know, or by type when names vary across models:
const light = node.devices.find((d) => d.name === "Light");
const power = light?.params.find((p) => p.id === "Power");
await power?.setValue(true);
Every device also exposes primaryParam, the parameter the firmware nominated as the main control, falling back to the first parameter when none was nominated. It is the right target for a single toggle in a list row:
await light?.primaryParam?.setValue(true);
Guard each step. A node from one account or firmware version may not have the device or parameter your UI assumes.
Parent references are weak
Devices, services and parameters hold a weak reference to their node, and reach it through getNode():
const parent = light?.getNode();
This keeps the graph from leaking, but it means a parameter can outlive its node. If you hold a parameter after dropping the node, setValue() throws ESPAPICallValidationError with code MISSING_NODE_REF. Keep the node alive for as long as you keep anything under it.
Where to go next
| You want to | Read |
|---|---|
| Onboard a device | Provisioning |
| Give a device its certificate | Assisted claiming |
| Read or refresh configuration | Node configuration |
| Turn something on | Device control |
| Set a timezone | Service control |
| Choose local or cloud | Transports |
| React to device changes | Live updates |
| Act on a timetable | Schedules |
| Act on a condition | Triggers |
| Chart history | Time series |
Related
- Node configuration — reading and refreshing config
- Device control — writing parameters
- Manage groups — how nodes are fetched
- Terminology — node, device, parameter defined
- Node–cloud communication — reported versus desired state