Skip to main content

ESPCDFGroup

ESPCDFGroup represents a home, room, fabric, or other node collection in CDF. Use it when you need to load members, manage membership, or create scenes, schedules, and automations scoped to that group.

Groups arrive in GroupStore after user.getGroups() or group.getSubGroups(). Obtain them from groupStore.getGroupById or groupStore.groupsList — do not construct them in UI code.

Mutating methods use runAndEmit; synchronizers update GroupStore, NodeStore, and child domain stores on success.

Properties​

PropertyTypeDescription
identifierstringAdaptor that constructed this entity
id / namestringBackend identifiers
nodeIdsstring[]Member node IDs
nodeDetailsESPCDFNode[] | undefinedCached node instances when provided
subGroupsESPCDFGroup[] | undefinedNested groups
type / parentIdoptionalHierarchy semantics (e.g. home, room)
isMatterboolean | undefinedMatter fabric context
fabricIdoptionalMatter fabric identifier
operationsESPCDFGroupOperationSDK-facing operations (not observed)
_rawanyOriginal SDK group; adaptor layer only
eventsESPCDFOperationEventEmitterOperation lifecycle for synchronizers

Common Workflows​

Get a group from the store​

import { initCDF } from "@espressif/rainmaker-base-cdf";

const espCDF = await initCDF({ sdkAdaptorRegistry });
const group = espCDF.groupStore.getGroupById("group-id");

if (!group) {
  // Group not loaded yet — call user.getGroups() first
}

Load nodes in a group​

getNodes populates NodeStore via GroupStoreSynchronizer.

const nodes = await group.getNodes();
// espCDF.nodeStore.nodesList now includes returned nodes

Update group info and membership​

await group.updateGroupInfo({ groupName: "Living Room" } as any);
await group.updateMetadata({ location: "downstairs" } as any);

await group.addNodes(["new-node-id"]);
await group.removeNodes(["old-node-id"]);

Create and list scenes​

const rows = await group.getSceneCapableDevices();

const scene = await group.createScene({
  id: "scene-movie",
  name: "Movie Night",
  nodes: ["node-1"],
  actions: { "node-1": { Light: { Power: true, Brightness: 30 } } },
});

await group.getScenes();
const scenes = espCDF.sceneStore.sceneList;

Create and list schedules​

const rows = await group.getScheduleCapableDevices();

const schedule = await group.createSchedule({
  id: "sch-morning",
  name: "Morning",
  nodes: ["node-1"],
  triggers: [{ m: 420, d: 127 }],
  action: { "node-1": { Light: { Power: true } } },
  enabled: true,
});

await group.getSchedules();

Create and list automations​

const { data: automations } = await group.getAutomations();

const automation = await group.createAutomation({
  name: "Lights at sunset",
  enabled: true,
  eventType: "daylight",
  events: [{ check: { name: "sunset" } }],
  eventOperator: "any",
  actions: [{ nodeId: "node-1", action: { Light: { Power: true } } }],
  location: { latitude: 18.5, longitude: 73.9 },
});

Sharing and ownership​

await group.share({ username: "guest@example.com" } as any);
const info = await group.getSharingInfo({} as any);
await group.removeSharingFor("guest@example.com");
await group.transfer({ newOwner: "other@example.com" } as any);

Leave or delete a group​

// Secondary user leaves shared group
await group.leave();

// Primary user deletes the group
await group.delete();

Error Handling​

Adaptor-specific operations such as getSceneCapableDevices throw if the active adaptor does not implement them:

try {
  await group.getSceneCapableDevices();
} catch (e) {
  showErrorBanner("Scenes are not supported for this SDK");
}

runAndEmit methods re-throw on failure while still emitting a failure event for synchronizer logging.

Subgroups​

const subGroups = await group.getSubGroups();
const child = await group.createSubGroup({ name: "Bedroom", type: "room" } as any);

Matter fabric helpers​

When isMatter is true and the adaptor implements the operations:

const noc = await group.issueUserNoC();
await group.startCommissioning({} as any);

On this page