Event filtering

Brain events can be filtered by their topic string. Receiving Brain events will involve topic filters to select which types of events will be received, regardless of which method is used to receive the event. This is called "subscribing" to a topic filter. Most applications only need a subset of all available event types. When developing an application which utilizes Brain events, it is recommended to only subscribe to event types of interest for that particular application to reduce server load and processing overhead.

Topic format

Every event is related to a single record in one of the resources on the Brain REST API. The topic string format reflects this, as it always starts with a resource and record ID. The topic string contains several segments delimited with a forward slash:

resource/id/action/argument_1/argument_2/argument...

• resource is one of the Brain REST API resources in plural, for example "items", "locations", "spots" or "presences", etc...
• id is a hexadecimal API record identifier, for example "5b757aca7503c44581d7a9a0".
• action is a short phrase, usually a past tense verb, indicating the type of event that occurred, for example "created", "deleted" or "moved-to".
• arguments can be any number of additional segments depending on the resource and action of the event.

See the examples below:

items/efcd9d43d66d4a7fd8070521/moved-to/a53c0feb209635ce8e650583/85bfc2277a028d19e0aab248

In this example, the first part of the topic means that the item with ID efcd9d43d66d4a7fd8070521 moved to a new location.

For this type of event, the arguments mean that it moved to the location with ID a53c0feb209635ce8e650583, and it was at the location with ID 85bfc2277a028d19e0aab248 before it moved.

presences/666b0237b51d9e4ae5e45efe/created/5ea955eb31546c0353e6862b/5ee8bbdefd3cb505cb24e16e/near

In this example, the first part of the topic means that a presence with ID 666b0237b51d9e4ae5e45efe was created. In other words, the tag became in read range of a Smartspot reader.

For this type of event, the arguments mean that the presence is created for an item with ID 5ea955eb31546c0353e6862b at Smartspot location with ID 5ee8bbdefd3cb505cb24e16e and the proximity is near.

Please refer to article Event topic reference for a full specification of all resources, their actions and arguments.

Filter format

Topic filters are topic strings where some or all segments may be replaced by wildcards. The supported topic filtering wildcards are those defined in the MQTT messaging protocol:

• A + sign matches any value for that segment.
• A # sign matches any number of segments (including zero) with any value. May only occur as the last character of the filter. It is recommended to always end a filter with # for forward compatibility, because new arguments may be added in future Brain versions.

For example, the filter items/+/moved-to/# would match any "item moved" event, such as the one in the topic example given earlier. Some other examples:

spots/+/connected/# would match "Smartspot connected to the Brain" events.

items/# would match any item event.