Skip to main content

Overview

Connect RainMaker devices to your app, control them in real time, and manage their lifecycle—from first provisioning through automation, sharing, and firmware updates.

note

The userInstance used throughout this section refers to an ESPRMUser instance obtained after User Sign in.

What This Module Does ?​

Device Management covers everything after sign-in and before group organization: discovering and onboarding hardware, listing and controlling nodes, real-time sync, automations, OTA, sharing, and metadata.

Use this section when your app needs to onboard devices, show and control the user's hardware, react to state changes, push firmware, share access, or query historical data.

Use other sections instead for authentication, groups, or SDK setup — see Getting Started, User Management, and Group Management.

Expected outcome: You can provision devices into the user's account, read and write parameters on nodes, and use the guides below for each capability.

Common Workflows​

Control an existing device​

Shortest path from signed-in user to changing a parameter:

const { nodes } = await userInstance.getUserNodes();
const node = nodes[0];
const nodeConfig = node.nodeConfig ?? (await node.getNodeConfig());

const light = nodeConfig.devices.find((d) => d.type === "esp.device.light");
const powerParam = light.params.find((p) => p.name === "Power");

await powerParam.setValue(true);

To add a new device, start with Provisioning.

Provisioning​

GoalGuide
Full onboarding flow (discover → connect → provision)Provisioning
Secure user–node mapping (default in SDK v2.3.0+)Challenge-Response Provisioning
Filter BLE devices by customer ID (white-label apps)BLE Device Search
Low-level provisioning APIsESPDevice Reference

Claiming​

GoalGuide
Register unclaimed devices with the cloud firstAssisted Claiming

Node Management​

GoalGuide
List, inspect, or remove nodesNode Management

Control​

GoalGuide
Update device parameters (lights, switches, sensors)Device Control
Update service parameters (schedules, timezone, etc.)Service Control
Update several nodes or parameters at onceBatch Operations
Prefer local network over cloud for faster controlTransport Order

Time Series​

GoalGuide
Query historical config parameter dataTime Series Data
Query time series outside node configCustom Parameter Time Series

Automations​

GoalGuide
Create automations (triggers, daylight, weather)Automation
Update, enable, or delete automationsAutomation Management

Updates​

GoalGuide
Unified update manager with channel priority (SDK v2.2.2+)Subscription Channels
Listen for local discovery and node updatesEvents and Subscriptions

Sharing, OTA & Utils​

GoalGuide
Share or transfer nodes with other usersNode Sharing
Push firmware updatesOTA Updates
Set node timezoneTimezone Management
Attach tags or custom metadataNode Metadata & Tags

Advanced Concepts​

Node hierarchy​

Every provisioned device is a node (ESPRMNode). Each node contains devices (controllable things) and services (system capabilities), each with parameters:

ESPRMNode
├── ESPRMNodeConfig
│   ├── ESPRMDevice[]        → controllable things (light, switch, sensor)
│   │   └── ESPRMDeviceParam[] → readable/writable values (Power, Brightness)
│   └── ESPRMService[]       → system capabilities (Schedule, Time, OTA)
│       └── ESPRMServiceParam[] → service-level values (timezone, schedules)

See the interactive tree in Node Management.

Provisioning vs claiming vs control​

  • Claiming — registers the device with RainMaker cloud and installs certificates
  • Provisioning — maps the device to the user and configures Wi-Fi
  • Control — reads/writes parameters on an already-provisioned node

Transport selection​

By default, parameter updates use the cloud. For local network communication, configure Transport Order and local discovery.

Best Practices​

  1. Start with provisioning, then control — complete onboarding before building control UI
  2. Use getPrimaryParam() when a device has one main control — see Device Control
  3. Prefer batch updates when changing multiple parameters or nodes — see Batch Operations
  4. Subscribe to updates early — register listeners before actions that expect callbacks
  5. Use ESPDevice docs only for onboarding — see ESPDevice Reference for low-level provisioning APIs

On this page