Skip to main content

Device Control

Update device parameters—turn on a light, adjust brightness, toggle a switch—from your app.

note

userInstance — ESPRMUser from User sign in.

What This Module Does ?​

Device control changes the state of physical hardware on a provisioned node. Each node has devices (e.g., lights, fans) with parameters (e.g., Power, Brightness) that you update via setValue().

Use this when you need to turn devices on/off, adjust settings, or use a device's primary control parameter.

Use Service Control for schedules, timezone, and other service parameters. Use Batch Operations to update multiple parameters or nodes at once.

Expected outcome: The SDK sends the update; if the node is online, the device state changes.

Common Workflows​

Turn on a light​

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);
  1. Get the node — getUserNodes() or getNodeDetails(nodeId)
  2. Access nodeConfig — on the node, or getNodeConfig()
  3. Find the device — by name or type (e.g., "esp.device.light")
  4. Find the parameter — by name or type (e.g., "esp.param.power")
  5. Call setValue(newValue)

Use the primary parameter​

const nodeConfig = node.nodeConfig ?? (await node.getNodeConfig());
const device = nodeConfig.devices[0];

const primaryParam = device.getPrimaryParam();
if (primaryParam) {
  await primaryParam.setValue(true);
}

Find parameters by type​

const powerParam = device.params.find((p) => p.type === "esp.param.power");
if (powerParam) {
  await powerParam.setValue(true);
}

Error Handling​

try {
  const { nodes } = await userInstance.getUserNodes();
  const node = nodes.find((n) => n.id === targetNodeId);
  if (!node) return;

  const nodeConfig = node.nodeConfig ?? (await node.getNodeConfig());
  const device = nodeConfig.devices.find((d) => d.type === "esp.device.light");
  const param = device?.params.find((p) => p.name === "Power");
  if (!param) return;

  await param.setValue(true);
} catch (error) {
  console.error("Failed to update device parameter:", error);
}

Guard each hierarchy step—nodes, devices, and parameters may not exist for every account or firmware.

Advanced Concepts​

Mental model​

Find the parameter → set its value → the device responds.

How updates reach the device​

With local transport configured, the SDK may route updates directly when the node is on the same network.

Parameter value types​

Values match the RainMaker parameter type—booleans for power, numbers for brightness, strings for modes. The SDK handles serialization.

Best Practices​

  1. Cache node config when building control UI
  2. Use getPrimaryParam() for the main toggle
  3. Match by type when parameter names differ across models
  4. Subscribe to node updates — see Events and Subscriptions
  5. Batch related changes with setMultipleParams() — see Node Management

On this page