Create and Manage Fabrics

This guide covers listing RainMaker groups, converting a group to a Matter fabric, loading fabric details for commissioning, and other fabric management APIs.

Get groups

Retrieve groups and Matter fabrics with a single getGroups() call. Matter-enabled groups are returned as ESPRMFabric instances; regular RainMaker groups are ESPRMGroup:

const response = await userInstance.getGroups({
  withFabricDetails: true,
  withNodeDetails: true,
});

const fabrics = response.groups.filter((g) => g.isMatter);
const regularGroups = response.groups.filter((g) => !g.isMatter);

console.log("Groups:", regularGroups.length);
console.log("Fabrics:", fabrics.length);

Use pagination via resultCount and fetchNext when the account has many groups.

To list only Matter fabrics, pass fabricOnly: true:

const { groups: fabrics } = await userInstance.getGroups({
  fabricOnly: true,
  withFabricDetails: true,
  withNodeDetails: true,
});

Optional withMatterNodeList: true includes Matter node ID mappings in the group API response when you need RainMaker ↔ Matter ID pairs without a separate nodes call.

Convert a group to fabric

If users already organize devices in RainMaker groups, enable Matter on an existing group instead of creating a parallel fabric. Conversion preserves group membership, sharing, and metadata (name/description).

Only non-Matter groups (!group.isMatter) are valid sources. Groups that are already Matter fabrics must not call convertToFabric. Pick a regular group from Get groups:

const fabric = await regularGroup.convertToFabric();

Expected outcome: The group becomes a Matter fabric (ESPRMFabric instance) with fabric CA provisioning on the backend.

Use createFabric when there is no existing group to upgrade.

Prepare a fabric for commissioning

Commissioning and CSR flows expect fabric CA details to be loaded on the ESPRMFabric instance. Call getFabricDetails() before startCommissioning:

await fabric.getFabricDetails();

Use the fabric returned from convertToFabric, createFabric, or resolved from Get a specific fabric.

Expected outcome: Fabric CA material is available so native commissioning and issueNodeNoC can proceed without extra round trips.

After conversion, optionally issueUserNoC so the current user has a fabric user certificate, then commission devices into the fabric.

Create a fabric

Use userInstance when the user should get a new Matter-enabled home and no existing group should be upgraded:

try {
  const fabric = await userInstance.createFabric({
    name: "My Smart Home Fabric",
    description: "Main fabric for smart home devices",
    type: "home",
  });

  const fabricDetails = await fabric.getFabricDetails();
  console.log("Fabric ready:", fabricDetails);
} catch (error) {
  console.error("Failed to create fabric:", error);
}

Expected outcome: A new fabric exists with a group ID and fabric ID; getFabricDetails() returns CA-related material needed for commissioning.

Get a specific fabric

Fetch a Matter fabric by its RainMaker group ID with getFabricById():

const fabric = await userInstance.getFabricById("<FABRIC_GROUP_ID>", {
  withFabricDetails: true,
  withNodeDetails: true,
});

Use the group ID returned from createFabric, convertToFabric, or the groups list. Optional query flags (withFabricDetails, withNodeDetails, withMatterNodeList) match those on getGroups().

Fabric details and nodes

Fabric metadata

const details = await fabric.getFabricDetails();

Nodes on the fabric (typed)

const nodes = await fabric.getNodesWithDetails();
// Pure Matter nodes → ESPRMMatterNode
// RainMaker nodes   → ESPRMNode

getNodesWithDetails() transforms API node_details into SDK node instances, including Matter endpoint devices and cluster params on ESPRMMatterNode. See Matter Nodes.

Single node by RainMaker node ID

const node = await userInstance.getNodeDetails("<RAINMAKER_NODE_ID>");
// Returns ESPRMMatterNode when the node is Matter-enabled

Common workflows

Task	Steps
Upgrade existing home	getGroups() → pick regular group → convertToFabric() → getFabricDetails() → commission device
First-time Matter home	createFabric → getFabricDetails() → commission device
Pick existing fabric	getFabricById(groupId) → getFabricDetails() → commission
Show home picker	getGroups with withNodeDetails: true → filter isMatter
Add user to fabric ACL	Issue user NoC

Error handling

Situation	What to do
Fabric not found	Verify group ID; getFabricById throws if the ID is not a Matter fabric
Group already Matter	Do not call convertToFabric; use the fabric directly
Missing fabric details	Call getFabricDetails() before commissioning
Validation errors	Check ESPRMMatterFabricError message codes

Get groups​

Convert a group to fabric​

Prepare a fabric for commissioning​

Create a fabric​

Get a specific fabric​

Fabric details and nodes​

Fabric metadata​

Nodes on the fabric (typed)​

Single node by RainMaker node ID​

Common workflows​

Error handling​