Group Sharing & Node Group

about

ESP Rainmaker Node Groups is a feature that enables users to organize and manage IoT devices efficiently.

What is a Node Group?
A Node Group is a logical collection of nodes. These groups help users organize the nodes based on location (e.g., “Living Room Devices”), function (e.g., “All Lights”), or metadata (e.g., “Model: X123”).

• Groups can be static (nodes explicitly listed) or dynamic (based on node model/type/firmware).
• Hierarchical grouping is supported: groups can have sub-groups up to 3 levels deep.

What is Group Sharing?
Group Sharing allows users to collaborate with others by sharing node groups. It enables multi-user collaboration on the same physical nodes of the same group. You can share with:

• Primary access — full control (can update/delete/share further).
• Secondary access — limited control (can view, use basic operations).

The feature provides:

• Hierarchical organization of nodes into groups.
• Dynamic node grouping based on node attributes such as node type, model, or firmware version.
• Node control & sharing capabilities between users.
• Matter fabric support for Matter-enabled devices (nodes).
• Admin and user-level node group management.

---

Use Case

Node Groups solve several key challenges in IoT device (node) management:

Use Cases	Description
Organization	Helps users organize multiple nodes logically (e.g., by room, function, or location)
Bulk Operations	Enables performing operations on multiple nodes simultaneously
Access Control	Facilitates sharing node access with other users with different permission levels
Dynamic Management	Allows automatic grouping of nodes based on their attributes
Matter Integration	Supports Matter protocol devices (nodes) alongside Rainmaker device (nodes)
OTA Management	Enables efficient firmware updates for groups of nodes

---

Entities Involved

Users

Admin Users

Can create and manage admin node groups.

End Users

Can create and manage user node groups.

• Primary User

  1. Owner of the devi group.
  2. Has full control over sharing settings.
  3. Can add/remove secondary users.
  4. Can modify sharing permissions.

• Secondary User

  1. Recipient of shared access
  2. Limited permissions based on role
  3. Can view and/or control shared nodes
  4. Cannot modify sharing settings

---

Node

An IoT Node registered on ESP Rainmaker, identified by unique node IDs.

1. Rainmaker Nodes: Standard ESP Rainmaker nodes.
2. Matter Nodes: Matter protocol-enabled nodes.

---

Groups

1. Admin Node Group: Node group created by the admin users.
2. User Node Group: Node group created by the end users.
3. Matter Fabric: Matter fabric can be created by end users using the node group APIs and it can contain matter as well as rainmaker nodes.
4. Dynamic Groups
   • Group Query Based Groups: Only Admins can create these groups by providing either or all of the node_type, node_model and node_fw_version. These groups will then take the existing nodes according to their node config values and admin can use this dynamic groups for sending OTA jobs.
   • Regroup: Regroup operation is applicable to only group_query based groups. If a group is created based on a group_query and some nodes' type, model or firmware version is changed, then the regroup option removes nodes which no longer satisfy the group_query and adds newly added/updated nodes which match the group_query.

---

Usage Guide

Group Sharing API Usage

Share Groups: PUT /v1/user/node_group/sharing

1. Share as Primary User

   

   Purpose - Share groups with another user as a primary user, giving them full control.

   1. The recipient becomes a primary user of the shared groups
   2. They get full control over the nodes in these groups
   3. They can further share these groups with others

2. Share as Secondary User

   

   Purpose - Share groups with view-only access.

   1. The recipient becomes a secondary user
   2. They can only view and monitor nodes
   3. Cannot modify nodes settings or share further

3. Transfer Primary Ownership

   

   Purpose - Transfer complete ownership of groups.

   1. Current user loses primary access
   2. Recipient becomes the new primary user
   3. Current user loses all access to the group

4. Transfer and Retain Secondary Access

   

   Purpose - Transfer ownership while maintaining view access.

   1. Current user becomes secondary user
   2. Recipient becomes primary user
   3. Current user retains view-only access

---

Get Sharing Details GET /v1/user/node_group/sharing

Query Type	Method	Endpoint	Description
i. Basic Query	GET	/v1/user/node_group/sharing	Returns all groups the user has access to (both primary and secondary).
ii. Query with Group ID	GET	/v1/user/node_group/sharing?group_id=group_id1	Returns sharing details for a specific group.
iii. Query with Subgroups	GET	/v1/user/node_group/sharing?sub_groups=true	Returns sharing details including all subgroups.
iv. Query with Parent Groups	GET	/v1/user/node_group/sharing?parent_groups=true	Returns sharing details including parent groups.
v. Query with Metadata	GET	/v1/user/node_group/sharing?metadata=true	Returns sharing details including metadata set during sharing.

---

Manage Sharing Requests

• Get Sharing Requests GET v1/user/node_group/sharing/requests

  This API allows the primary and secondary users to get the sharing requests.

  Parameters

  1. request_id: Get specific request.
  2. primary_user: This is a boolean flag, which is used to denote whether to get the requests raised by Primary user(true) or received by secondary users (false). Default value for this flag is false.
  3. start_request_id: used in pagination.
  4. start_user_name: used in pagination along with start_request_id
  5. num_records: used to specify the no of records that must be returned. Default value is 10. The valid values are in the range of 1 to 10. If invalid value is given, default value is used.

• Accept/Decline Request PUT /v1/user/node_group/sharing/requests

  Used to accept or decline a group sharing requests.

• Delete Sharing Request
  DELETE /v1/user/node_group/sharing/requests?request_id=request_id1

  Removes a pending sharing request.

---

Delete Node Group DELETE /v1/user/node_group

This API will delete user node group/matter fabric if user is primary.It allows the users to leave from their own groups/matter fabric. It also allows primary users to remove the sharing for other users.

Parameters

1. group_id (required)
2. leave (boolean):
   • Primary/secondary users can specify this parameter to leave the group.
   • If the user is the only primary user of the group then the user cannot leave the group. Delete the group instead.
   • If there are multiple primary users of the group, then the user can leave the group using the query param
   • For secondary users, it will be true by default if nothing is specified.
3. remove_sharing (boolean): remove_sharing should be used with user_name.
   • Used to remove sharing of the user_name specified.
   • Secondary users cannot perform this operation.
   • Username for which sharing needs to be removed and the requesting username cannot be the same. Please use 'leave' instead.
   • A cannot unshare groups that were shared via parent group.
   • remove_sharing and leave are not allowed together.
4. user_name (string): user_name of the user for which sharing needs to be removed.

---

Assumptions

• Each group has at least one Primary User.
• Maximum 100 nodes can be added per group in a single request.
• Matter devices (nodes) can only be added to Matter fabrics.
• Dynamic groups automatically update when node attributes change.
• Only admins can create dynamic groups.
• Dynamic groups cannot have subgroups.
• Dynamic groups are mutually exclusive with static groups.