- Essentials
- How groups work
- Usage scenarios
- How to create a group?
- How to add devices to the group?
- How to assign a group?
- Groups access
- Groups API
- Troubleshooting
Essentials
Groups help organize devices. Plugins, streams, and calculators assigned to a group apply to all devices in the group. ACL access to a group grants respective permissions to all devices in the group.
How groups work
Groups do not move the devices anywhere. Therefore, you can access any individual device as before via API or in the flespi panel. Groups are just a handy wrapper to address a subset of devices.
Usage scenarios
Initially, groups were designed to facilitate the operation of large accounts with hundreds and thousands of devices. Having devices logically structured into groups makes it easier to assign them to streams, plugins, and calculators. However, there are some more specific use cases:
Load balancing streams
If the message flow through a stream is too intensive, the destination platform may be unable to handle it in real time which may lead to delays. To address this issue, you can create several streams of the same type and assign complementing subsets of devices to them. This is easier achieved with groups — you simply assign one group to one stream and the other group to another stream (and so on if you need to split the load to more than two streams).
Managing permissions
If you need to grant permissions to a particular subset of devices, you can add these devices to a group and create an ACL token for that group specifying the allowed access methods.
Adding a static field to device messages
If you assign a group of devices to the item-fields plugin, the same static field with the specified value will be added to messages from all devices in the group.
Getting configuration of multiple devices
You may use groups to get configuration for a specific set of devices via API.
The result will look like this:
Using groups in devices API
You may list all groups to which device belong to or select only devices in a particular group for any operation withing devices REST API.
Examples:
- To list all groups device is in: GET /gw/devices/all?fields=groups
- To send a command to all members of a group (by name): POST /gw/devices/groups.name=group1/commands
- To send a command to all members of a group (by ID): POST /gw/devices/groups.id=1/commands
- To send a command to all devices that are not in any group: POST /gw/devices/groups=[]/commands
How to create a group?
Log in to the flespi panel
Navigate to Telematics hub -> Groups and click the "+" button in the bottom right corner to add a new group:
Give the new group a meaningful name and click Save
How to add devices to the group?
Open the group card.
Navigate to the Devices tab
Click the “+” button to add devices to the group
How to assign a group?
Go to the target stream, plugin, or calculator.
Navigate to the Groups tab
Click the “+” button to assign a group of devices to the current stream, plugin, or calculator.
Groups access
You can grant access to the specific groups by creating a proper ACL token to gw/groups and listing the desired group ids or selecting ALL.
Important! If you want to be able to give access to devices in the specific groups, you need to grant access to gw/devices/in-groups.
Groups API
To perform any operations with the groups, use the groups API.
Troubleshooting
In case of any issues, check the Logs tab on the group screen:
