Groups — organize devices and simplify mass assignments

Use groups of devices to add more structure to your account and easily assign multiple devices to streams, plugins, and calculators.

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

stream load balancing

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.

flespi group acl token

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.

group item fields plugin

Getting configuration of multiple devices

You may use groups to get configuration for a specific set of devices via API.

get configuration for group of devices

The result will look like this:

configuration for group of devices

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?

  1. Log in to the flespi panel

  2. Navigate to Telematics hub -> Groups and click the "+" button in the bottom right corner to add a new group:
    create new group

  3. Give the new group a meaningful name and click Save

How to add devices to the group?

  1. Open the group card.

  2. Navigate to the Devices tab

  3. Click the “+” button to add devices to the group

add devices to group

How to assign a group?

  1. Go to the target stream, plugin, or calculator.

  2. Navigate to the Groups tab

  3. Click the “+” button to assign a group of devices to the current stream, plugin, or calculator.

assign group to stream

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.

acl token for groups

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.

acl token to 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:

group logs