Introduction to Brain events

The Brain REST API enables applications to query information from the Brain, such as the items known to the system and where they are currently located by the Brain localization service. After querying relevant information, most applications will want to know when something changes. For example when an item moves to a new location, or when an item is no longer present at any location. For this purpose, the Brain has a concept of events, and various ways to receive the events relevant for a particular application.

Event anatomy

A Brain event consists of an event topic and event payload. The topic is a single string that can be used for filtering events. The payload contains more information about the event in JSON format and cannot be used for filtering.

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.

Example of an event:

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

Payload: {"item_move_count":88,"item_label":"Kettle","location_label":"Kitchen","time":"2018-08-29T09:53:48.301Z"}

In the above 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. Additionally, the payload data provides the move counter for this item, the item's label, the new location's label, and the time when the event occurred (in ISO 8601 format).

Available events and their arguments are listed in the Event topic reference.

Filtering events by topic is explained in Filtering events.

Receiving events

The Brain provides three different methods for an application to receive events: REST API polling, webhooks and SocketIO. These methods fit different needs depending on your type of application. Most applications will use only one of these methods, though it is possible to use several if desired. The following table gives an overview of key characteristics.

	(1) Push/pull	(2) Brain TCP role	(3) Web browser compatible	(4) Buffered	(5) Requires library	(6) Underlying protocol(s)
REST API polling	Pull	Server	Yes	Yes	No	HTTP
Webhooks	Push	Client	No	Yes	No	HTTP
SocketIO	Push	Server	Yes	No	Yes	HTTP, WebSocket

1. Push/pull: With pull delivery the application has to ask for new events. With push delivery the application immediately receives new events when they occur.
2. Brain TCP role: Whether the Brain acts as TCP client (application accepts connection) or server (application establishes connection).
3. Web browser compatible: Can be used directly from a web page with JavaScript.
4. Buffered: With buffered event delivery, the Brain will (temporarily) store event data, which can still be retrieved for a configurable period after the event has occurred. However, the types of events that need to be buffered must be configured in advance.
5. Requires library: Whether implementation requires a (third party) library other than HTTP and JSON functionality.
6. Underlying protocol(s): The application layer network prococol(s) involved.

All methods for receiving events support secure connections (TLS) assuming the Brain is configured with TLS support.

REST API polling

The Brain can be configured to store events of interest. Applications can then retrieve the stored events through the Brain REST API. Events can be received continuously by checking for new events periodically (for example, every five seconds). This method has the simplest requirements; it works with just a HTTP client. However, it is also the slowest, since there will always be some delay between polling requests. There will also be a continuous request overhead even if no events occur for some time.

The following diagram illustrates the process of REST API polling. Initially there are no new events for the application to process. The application queries for new events again after a delay. Now there are new events which the application will process and then update its latest event pointer and query again, et cetera.

See the REST API polling guide for more information about receiving events using this method.

Webhooks

In addition to just storing events of interest, the Brain can also be configured to automatically deliver these events to a remote web server as soon as they occur. This is called a webhook. When working with webhooks, the application will act as an HTTP server to which the Brain will send HTTP requests with event data as soon as events occur. This results in less latency and overhead compared to polling, but requires the application to have a central server and accept incoming connections from the outside world.

The following diagram illustrates webhook event delivery.

Brain webhooks are modeled after the RESTHooks specification.

See the Webhooks guide for more information about receiving events using this method.

SocketIO

The Brain has a socket.io v1.x server for on-the-fly event delivery through a continuously open connection. After the application completes the socket.io handshake and communicates which kinds of events it would like to receive, events will be pushed through the socket.io connection as soon as they occur, until the connection is terminated.

The SocketIO event interface is primarily intended for JavaScript based browser applications that need live updates from a Brain, but can potentially be used from any platform with a socket.io v1.x client library.

The following diagram illustrates SocketIO event delivery.

See the SocketIO guide for more information about receiving events using this method.