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.

  • A Node belongs to exactly one Group at a time. Associating it with a new Group removes it from the old one automatically.
  • 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.

A Group is the home. Rooms map onto Subgroups. In the phone app, a Subgroup used for bulk control is labelled a control group.

Sharing and access​

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.

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 add or remove Nodes, and can never re-share.

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. They must delete the Group directly.

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.

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.

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.

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.
  • It is the Node's responsbility to subscribe to the appropriate topics pertaining to the group and subgroups it is part of for remote control and group control to work. So also, the Node should publish updates on the appropriate topic for reporting status updates.

What the admin 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.

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.
  • 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.