4.4. Device Groups

Device Groups are a technique for identifying a particular set of Devices/Sensors. A Device Group can be used to explicitly filter which Devices your Pipeline will receive BLE Advertisement events for, or to define which Devices should trigger Device Status events (presence, absence, or battery level).

A default Device Group exists that contains all devices Edge Connect can see.

4.4.1. Defining Device Groups

Device Groups are defined in the Edge Connect Configuration document. Any number of Device Groups can be defined.

Two types of Device Groups are currently supported: static or persistent. Either one is based on an include and exclude list of MAC Addresses, with the peristent type storing discovered/removed devices on disk in order to persist across reboots. Static device groups are best suited for a pre-configured set of devices in the configuration file, while persistent groups are better for dynamic provisioning.

Static Device Group Documentation

Persistent Device Group Documentation

4.4.2. Targeting Device Groups in Pipelines

Pipelines have a groups configuration parameter. If this parameter is set, the Pipeline will only receive events if at least one of the Device Groups match the Device that generated the event. If the parameter is left empty, the Pipeline will receive events from the default Device Group, which is all devices.

4.4.3. Device Status Events

Status Events are emitted from each Device Group when the presence of a Device changes. These events can be subscribed to by creating a Pipeline with the eventType parameter set to deviceStatus. If events only from a particular Device Group are desired, the groups parameter can be set to target Device Status events from particular Group(s).

In order to receive batteryLevel events for a device group, you must set batteryEvents to true on the device group configuration and define a connection sequence that contains a readBatteryLevel action.

Device Status events include these fields:

{
    "property": "string; the property that is being reported, currently either presence or batteryLevel",
    "propertyStatus": "string; either OK, WARN, or FAIL",
    "propertyValue": "percentage of batteryLevel, or boolean for presence",
    "lastAdvertisement": "ble advertisement (see filter output docs)",
    "lastSeenTimestamp": "golang time.Time",
    "present": "deprecated: boolean - true if device arrives, false if it is absent",
    "timestamp": "golang time.Time, the time of the event",
    "deviceGroup": "string - the Device Group ID that generated this event",
    "mac":"string"
}

4.4.4. Discovery of Devices

It is also possible to add/remove Devices to/from a Group at runtime using a discoverDevice or removeDevice Filter. In this way, you can use a Filter Pipeline to to Discover the Devices that should be in a Group, adding any Devices that reach the discoverDevice Filter in your Pipeline. If these discovered devices should persist across reboots, you should use the persistent group type.