Skip to main content

Manage Groups

Create, update, delete groups; add or remove nodes; and manage subgroups.

note

userInstance — sign-in. group — from getGroupById, getGroupByName, or getGroups().

What This Module Does ?​

Manage the lifecycle and membership of node groups: create groups, rename them, add/remove nodes, create subgroups, leave or delete.

Use user-level APIs (createGroup) to create. Use group-level APIs (addNodes, updateGroupInfo, delete) on an ESPRMGroup instance.

Use Get Groups to list groups first. Use Share Groups for access control.

Expected outcome: Group structure in the cloud matches your app's organization (rooms, floors, etc.).

Common Workflows​

Create a group​

const newGroup = await userInstance.createGroup({
  name: "Living Room Devices",
  nodeIds: ["node_id_1", "node_id_2"],
  description: "All devices in the living room",
  customData: { room: "living_room", floor: 1 },
});

Update group info​

await group.updateGroupInfo({
  name: "Updated Group Name",
  description: "Updated description",
});

Add and remove nodes​

await group.addNodes(["node_id_3", "node_id_4"]);
await group.removeNodes(["node_id_1"]);

List nodes in a group​

const nodeIds = await group.getNodesList();
const nodes = await group.getNodesWithDetails();

Create a subgroup​

const subGroup = await group.createSubGroup({
  name: "Desk Lights",
  nodeIds: ["node_id_5"],
});
const subGroups = await group.getSubGroups();

Leave or delete​

await group.leave(); // current user leaves
await group.delete(); // delete entire group

Error Handling​

try {
  await group.addNodes(nodeIds);
} catch (error) {
  console.error("Failed to update group membership:", error);
}

Verify node IDs exist on the user's account before adding.

Best Practices​

  1. Create with initial nodeIds when you already know membership
  2. Use getNodesWithDetails for rich device UI inside a group
  3. Confirm before delete — removal affects all members
  4. Subgroups for hierarchical homes, not deep arbitrary nesting without UX need

On this page