Skip to main content

Groups & Group Control

A Group is the container a Node lives in — think of it as a home. Everything a user does in ESP RainMaker Neo happens inside a Group: a Node has no user-visible existence until it joins one, and access is granted per Group rather than per Node.

Groups also make bulk control possible. Instead of sending one message per Node, the app publishes once to a Group and every Node in it acts at the same time.

The model: two levels, no more​

Neo supports exactly two levels — a main Group and its Subgroups. There are no Subgroups inside Subgroups.

  • A Node belongs to exactly one Group at a time. Associating it with a new Group removes it from the old one automatically.
  • Within that Group, a Node can belong to up to three Subgroups at once.
  • A Group ID is 6 characters: a lowercase letter followed by five lowercase letters or digits. A Subgroup ID is 3 lowercase letters or digits. Both are minted by the cloud.

"Home" is not a separate entity in Neo — a Group is the home. Rooms map onto Subgroups. In the phone app, a Subgroup used for bulk control is labelled a control group; it is the same Subgroup, not a second concept.

What the user sees​

Users create a Group, then add Nodes to it during provisioning. Adding a Node to a Subgroup is done from the Device Settings screen — open a Device, tap the settings gear, then Add to control group.

The Device screen, with the settings gear in the top right

Device Settings, with Add to control group

Sharing and access​

Sharing is by user code — a short, memorable code the recipient reads off their own profile and passes to the Group owner out of band. Email addresses are not used, because on Apple sign-in they can be private-relay addresses, and user IDs are too long to say out loud.

A share creates a request that the recipient must accept or reject. Requests expire after 24 hours.

Three access types exist, and what they allow is worth knowing before you share:

Primary — full control. Create and delete Subgroups, add and remove Nodes, rename anything, delete the Group, and share or unshare it. The Group creator gets this.

Secondary — can create and delete Subgroups and rename things, but cannot add or remove Nodes, cannot delete the Group, and cannot share it onward.

Subgroup access — scoped to named Subgroups only. Can rename those Subgroups and list the Nodes in them. Cannot create or delete Subgroups, cannot add or remove Nodes, and can never re-share. Sharing a Subgroup always grants this level; any requested access type is ignored.

Two consequences that surprise people:

  • Access types cannot be edited. To change someone from secondary to primary, share again at the new level.
  • Leaving deletes nothing. When a user is removed from a Group, the Schedules, Automations, tags and time-series data on those Nodes stay put, because the platform does not track who created them. Remaining users can clean up what they do not want.

The last primary user cannot be removed — a Group must always have at least one owner.

Group Control: one publish, many Devices​

Group Control lets the app send a single message that every Node in a Group or Subgroup receives at the same time, fanned out by the MQTT broker rather than by the app looping over Nodes.

The important difference from ordinary control is how the message is addressed. A normal single-Node control names the Device: {"<deviceId>": {"<paramId>": <value>}}. A Group Control message names the Device type instead:

{
  "esp.device.light": { "params": { "esp.param.power": true, "esp.param.brightness": 75 } },
  "esp.device.fan":   { "params": { "esp.param.power": false } }
}

Each receiving Node applies the payload only to its own Devices whose type matches a top-level key, and silently ignores keys that match nothing. So one publish can turn on every light and turn off every fan across a mixed Group, and a Node with neither does nothing.

Delivery scope follows the sender's access. A user with Group-level access may publish to the whole-Group topic or to any Subgroup topic. A user with Subgroup access only may publish to their own Subgroup's topic — not to the whole Group, and not to a sibling Subgroup.

Group Control is described in full, including the topic layout, in the Group control spec.

Admin Node Groups are a different thing​

The dashboard has a Node Groups page, and it is not the same feature. Admin Node Groups are AWS IoT Thing Groups: a manufacturer's own way of organising a fleet, set at Node registration time (optionally under a parent Group, giving a hierarchy) and used for things like targeting an OTA rollout.

The difference in one line each:

  • Group — created by a user, holds the Nodes they own or were shared, drives the app UI and all user APIs.
  • Admin Node Group — created by the operator, holds Nodes by manufacturing or fleet criteria, visible only in the dashboard.

A Node is normally in both, independently. Renaming or deleting one has no effect on the other.

What the firmware must do​

Very little. Group membership arrives from the cloud and the SDK handles the subscriptions.

  • The Node receives its Group and Subgroup IDs from the cloud in a getGroupInfo message and subscribes to the matching control topics. This is pushed whenever membership changes, and the Node can ask for it at startup.
  • Group Control messages are dispatched by Device type, so your Devices must carry standard types (esp.device.light, esp.device.fan, …) to be addressable at all. See Standard types.
  • Persist the current subscription list in NVS so a rebooting Node does not miss commands while it waits for the cloud.

What the operator must do​

Nothing to enable Groups — they are the base access model, not an option. The operator-side work is around Admin Node Groups:

  • Decide the Admin Node Group naming and hierarchy before bulk registration, since groups are assigned as Nodes are registered.
  • Use the Node Groups page in the dashboard to inspect membership, edit descriptions and walk the parent/child hierarchy.
Node subscriptions are capped by AWS IoT

Each MQTT connection is limited to 50 subscriptions. A Node in several Subgroups subscribes to one topic per Subgroup, which is why the three-Subgroup ceiling exists. Plan Subgroup layout with that budget in mind — see Operations for the applicable AWS IoT quotas.

Limits and caveats​

Two levels only. Main Group and Subgroups. Deeper hierarchies must be modelled some other way.

One Group per Node, three Subgroups per Node. Both are hard.

Deleting a Group requires it to be empty — no Subgroups and no user Nodes, or the request is rejected. Nodes are never deleted by deleting a Group; deleting a Subgroup leaves its Nodes in the parent Group.

Group Control has no acknowledgement. A single publish goes out and matching Nodes act. There is no per-Node success or failure report, and no queuing for Nodes that were offline when the command was sent. Use single-Node control when you need confirmation.

Group and Subgroup names must simply be non-empty. No character set, length limit or uniqueness rule is specified, so two Groups may share a name.

Member lists are filtered by your own access. A primary user sees everyone; a secondary user sees only the primary owners; a Subgroup-only user cannot list Group members at all.

Name validation and per-user Group limits unconfirmed

The Group specification states only that a name cannot be empty, and gives no maximum number of Groups per user, Subgroups per Group, Nodes per Group, or users a Group can be shared with. None of these are documented as enforced — if your design depends on such limits, verify against your deployment.