Device Types

Device Types are a technique for identifying a particular type of Device/Sensor. A Device Type is used to explicitly identify the type of device seen within a BLE Advertisement and other types of events.

Defining Device Types

Device Types are defined in the Edge Connect configuration. Any number of Device Types can be defined. Any key present within an advertisement may be used to match an event to Device Type.

Each type of device is defined within the devices:{ types:[]} section of the Edge Connect configuration. A device type requires an id and a matcher. The matcher definition informs Edge Connect of how to identify an event as that type of device. Device types may also include accessible properties which behave similarly to metadata but are simpler to access within filters and actions.

Example device type:

{
    "devices":{
        "types": [
            {
                "id": "rs40",
                "match": {
                    "serviceData.fd95": ""
                }
            }
        ]
    }
}

The above example defines a device type for an rs40 which is a Rigado Occupancy sensor. An advertisement will be identified as this type of device if it contains a serviceData section with a UUID of fd95.

The general guideline is to provide an all lowercase single word device ID or multiple lowercase words separated by .. The matcher used to identify a device must be as specific as possible to avoid misidentification.

Device Type behaviors

When Edge Connect starts, all device types are registered within an internal registry. When any advertisement type event contains data which matches the matcher defined for the device type, a deviceDetected event is generated. This event can be captured by a pipeline which can then perform additional actions, if necessary, when a new device of an appropriate type is detected.

📘

Note: deviceDetected events only occur once per boot of Edge Connect for each device

Example:

{
    "pipelines": {
        "rs40Detected": {
            "eventType":"deviceDetected",
            "filters":[
                {
                    "matcher": { 
                        "match": {
                            "deviceType":"rs40"
                        }
                    }
                }
            ]
        }
    }
}

Further events containing a device with a known type can access the device information using the template function Device (i.e {{ Device.Type }}). See Templating for details on the available fields of Device. Access to the Device function requires an event with identifying device data such as mac or deviceId.

Targeting Device Types in Pipelines

Executing a Pipeline for only a certain type of device is achieved by setting the deviceTypes field of the Pipeline configuration. This field takes an array of Device Type IDs:

{
    "pipelines": {
        "rs40Detected": {
            "eventType":"advertisement",
            "types":["rs40"],
            "filters":[
                {
                    "inject": {
                        "keyPairs": {
                            "seen": true,
                        }
                    }
                }
            ]
        }
    }
}

Alternatively, upon receiving a device detected event, the device could be added to a device group. Then, pipelines which operate based on the device's advertisement data can specify this device group. This ensures that only the appropriate types of device advertisements are delivered to the pipeline.

In addition to deviceDetected events, the following events will occur as follows:

• deviceAssigned when any device is added to or removed from a device group.
• deviceHealth when health information about the device changes. Currently, this event is only triggered by the change in state of a device's presence.

Device Type Events

As discussed, when a new advertisement matching any defined device type is observed, a deviceDetected event occurs. All of the following events contain, among other things, the special key deviceType. Validating that this key matches the type of device a behavior
(pipeline, filter, etc) is interested in should always be considered.

These events have the following format:

{
    "mac":"32427aad00fc",
    "presence":"Unknown",
    "lastRssi":-33,
    "lastSeen":"2021-06-08T15:53:21.065286708Z",
    "advIvl":0,
    "health":"Unknown",
    "deviceId":"32427aad00fc",
    "smoothRssi":-33,
    "firstSeen":"2021-06-08T15:53:21.065286708Z",
    "lastAdv":{
        "services":["4f8="],
        "serviceData":{
            "ffe1":["oQFfABYAGQ=="]
        },
        "mac":"32427aad00fc",
        "addressType":1,
        "eventType":3,
        "connectable":false,
        "rssi":-33,
        "flags":"Ag=="
    },
    "assigned":false,
    "deviceType":"minew-s1"
}

Device health events have the following format:

{
    "assigned":true,
    "deviceType":"minew-s1",
    "smoothRssi":-32,
    "lastSeen":"2021-06-08T15:52:54.605252418Z",
    "advIvl":15698,
    "lastRssi":-38,
    "firstSeen":"2021-06-08T15:51:20.415835922Z",
    "lastAdv": {
        "flags":"Ag==",
        "mac":"32427aad0074",
        "addressType":1,
        "eventType":3,
        "connectable":false,
        "rssi":-38,
        "services":["4f8="],
        "serviceData": {
            "ffe1":["oQFfABYAGQ=="]
        }
    },
    "health":"OK",
    "deviceId":"32427aad0074",
    "mac":"32427aad0074",
    "presence":"OK",
    "groups":["validatedDevices"]
}

Device assignment events have the following format:

{
    "mac":"32427aad011b",
    "deviceType":"rs40",
    "lastRssi":-40,
    "firstSeen":"2021-06-08T15:51:12.216959664Z",
    "lastAdv": {
        "serviceData": {
            "fd95":["oUIAYlUKewECAwQFBgcICQo="]
        },
        "mac":"32427aad011b",
        "addressType":1,
        "eventType":3,
        "connectable":false,
        "rssi":-40,
        "flags":"Ag==",
        "services":["lf0="]
    },
    "assigned":true,
    "deviceId":"32427aad011b",
    "groups":["validatedDevices"],
    "smoothRssi":-35,
    "lastSeen":"2021-06-08T15:51:47.539083677Z",
    "advIvl":17661,
    "health":"OK",
    "presence":"OK"
}