Skip to main content

Group control

group.setParams() sends one parameter payload to every node in a group at once, over a single group-control MQTT topic. It is how an app turns off every light in a home without iterating nodes and issuing a write each.

await home.setParams({
  Light: { Power: false },
});

Returns Promise<ESPAPIResponse>. The payload takes the same shape as a single-node write (a map of device or service names to their parameter maps) so the same object works for either. See Device control.

Scope​

The scope depends on which instance you call it on, and optionally on options.subgroupId:

Called onWithTargets
Root groupno optionsEvery node in the group
Root groupsubgroupIdThat subgroup only
SubgroupanythingThat subgroup

A subgroup instance always targets itself, using its parent's MQTT namespace. options.subgroupId is only read on a root group:

await home.setParams({ Light: { Power: false } }, {
  subgroupId: livingRoom.groupId,
});
The option type is not exported yet

ESPRMNeoGroupSetParamsOptions is exported from the package, but the equivalent option types for several other methods are not. Where an options object has no importable type, pass an inline literal. See Types.

What a group write does not do​

Group control is a broadcast, not a fan-out of individual writes. Three consequences worth designing around:

  • Devices are addressed by name. A payload keyed Light reaches every node that has a device called Light and is ignored by the rest. Nodes with differently named devices need their own call.
  • There is no per-node result. The response confirms the broadcast was published, not that any particular node applied it. Nodes that were offline simply miss it.
  • It always uses the cloud topic. Unlike a single-node write, a group write has one route, so it needs an MQTT adaptor and a connected session.

For a guaranteed per-node outcome, write to each node with node.setParams() instead.

Confirming what happened​

Because the response says nothing about individual nodes, read the result from the nodes themselves. Each node applies incoming shadow updates to its own parameters, so subscribing to nodeUpdates gives you the actual state as devices report it:

import { ESPRMNeoEventType } from "@espressif/rainmaker-neo-base-sdk";

user.subscribe(ESPRMNeoEventType.nodeUpdates, (update) => {
  console.log(update.nodeId, update.payload);
});

await home.setParams({ Light: { Power: false } });

See Live updates.