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/arguments

• resource is one of the Brain REST API resources in plural, for example "items" or "locations".
• 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 type of event. Not all types of events have argument segments.

For example:

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.

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.