Endpoint Filter

What is endpoint filter
What you can do with endpoint filter using Kaa

What is endpoint filter

Endpoint filter is a mechanism used to select specific endpoints (devices) from the entire set of registered endpoints in the Kaa platform. This filtering is based on certain conditions.

Endpoint filters can be configured to target endpoints based on various attributes such as device type, location, firmware version, custom properties, or any other metadata associated with the endpoint.

Endpoint filters are application-specific. Each filter has an application-wide unique ID assigned at the moment of the filter creation. Endpoint filters are based on MongoDB views.

Filters can be specified using powerful queries which can reference values of:

endpoint metadata;
endpoint application version.

Whenever an endpoint filter is created, Kaa performs an asynchronous recalculation of filter matches for all the application’s endpoints. Whenever an endpoint application version or endpoint metadata is updated, the filter matches/mismatches for that endpoint is re-evaluated.

Kaa provides REST API for managing endpoint filters and receiving lists of matching endpoints.

Filter states

Due to asynchronous nature, filters have two states: ACTIVE and PENDING.

When endpoint filters are created, they are in PENDING state until endpoint matching process is finished. If a filter is in this state, endpoint search by the filter is disabled.

After endpoint matching is completed, filters change state to ACTIVE. This state means a filter has been activated and is fully functional.

Filter limitations

There are several limitations related to endpoint filtering process:

Multiple metadata key values cannot be used in the same predicate criterion because MongoDB does not support such queries. $where operator can be used for such filtration. For example, the following predicate is not valid: metadata.foo > metadata.bar
On one side of a predicate, the single criterion must be a constant; on the other—metadata key or application version
Arithmetic operations like plus, minus, divide, multiply are not natively supported by mongo query engine
Only MongoDB query operations and functions are supported

Filter queries example

Assume the endpoint registered in application version c8u2bklah5mkbalggie0-v1 and has the following metadata:

{
  "name": "Smart meter 1",
  "serial": "CNF-77C-Sk-B1200e-Xt7",
  "city": "Kyiv",
  "model": "Qubino Smart Meter 3-Phase",
  "type": "electric",
  "lat": 50.4504,
  "lon": 30.5245
}

Filter by application version only

{
  "application_version": "c8u2bklah5mkbalggie0-v1"
}

Filter by city metadata key having value Kyiv

{
  "metadata": {
    "$elemMatch": {
      "key": "city",
      "value": "Kyiv"
    }
  }
}

Filter by city metadata key having value Kyiv and application version c8u2bklah5mkbalggie0-v1

{
  "$and": [
    {
      "application_version": "c8u2bklah5mkbalggie0-v1"
    },
    {
      "metadata": {
        "$elemMatch": {
          "key": "city",
          "value": "Kyiv"
        }
      }
    }
  ]
}

To create endpoint filter, go to Device management -> Endpoint filters, and click “Add filter” button.

Endpoint filter dashboard

and create the filter specifying the filter query.

Create filter

What you can do with endpoint filter using Kaa

View the matching endpoints

From the page of the created filter you can vew all the matching endpoints in the Matching endpoints widget table.

Filter page

List matching endpoints via REST API

You can query list of matching endpoints with the help of endpoint filter REST API. Example of querying matching endpoints by the filter with ID 3febb1a7-f0a5-4f9c-a24d-40010111b62d from Kaa Cloud in the c8u2bklah5mkbalggie0 application.

Initialize $ACCESS_TOKEN with the access token, and $APPLICATION with your application name.

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://cloud.kaaiot.com/epr/api/v1/endpoints?applicationName=$APPLICATION&filterId=3febb1a7-f0a5-4f9c-a24d-40010111b62d

Send command to matching endpoints

Imagine you want to start over-the-air update only for those endpoints that match the filter (which are in Kyiv in our case). For that, use Command execution widget.

Start ota

Send configuration to matching endpoints

Refer to REST API.