- Basic architecture
- Configuring Kaa
The Kaa event subsystem enables messages delivery across the endpoints (EP). Events can be thought of as commands or structured chunks of data. For example, an event from a smartphone application can toggle the lights in the room.
Structure of the data carried by events is defined by an Event Class (EC) data schema configured on the Kaa server and built into Kaa SDK. ECs are grouped into Event Class Families (ECF) by the topic. Kaa allows delivering events among EPs that belong to the same or different applications. As of Kaa r0.6, endpoints must be associated with the same user in order to be able to send events to each other. Please review the events system design reference for more background.
From this guide you will learn how to use Kaa events functionality for enabling communication across the endpoints.
The following diagram illustrates basic entities and data flows in scope of the event management:
- Events are generated based on the event class schema created by the developer for the event class family
- The event class family can be used by one or multiple applications, thus the event can be shared between applications
- Several applications belonging to the same user share events between each other according to the application mapping and through the Kaa server
This section provides guidance on how to configure ECFs in Kaa.
In this guide, we will use the following ECF that allows you to remotely control a thermostat using your cell phone.
Our sample ECF contains three events:
ChangeTemperatureCommand. We will create the following two applications in this guide: Controller and Thermostat. It is logical that Controller should be able to send the
ThermostatInfoRequest event (act as a source) and receive the
ThermostatInfoResponse event (act as a sink), while Thermostat should be able to send the
ThermostatInfoResponse event and receive the
ThermostatInfo event. Based on such logic of our application, we will create the following application mapping for our sample ECF:
During the SDK generation, the Control server generates the event object model and extends APIs to support methods for sending events and registering event listeners. An application SDK can support multiple ECFs. However, it cannot simultaneously support multiple versions of the same ECF.
This section provides code samples which illustrate practical usage of events in Kaa. The event subsystem API varies depending on the target SDK platform, but the general approach is the same.
Attach endpoint to user
To enable sending/receiving events to/from endpoints, at first the client should attach the endpoint to the user as shown in the following screenshot.
Specific endpoint may not be able to attach itself independently. E.g. in case if endpoint doesn't have an user token. Another endpoint that already attached can assist in attachment process of the new endpoint. Below are examples of assisted attachment.
Get ECF factory and create ECF object
To access the Kaa event functionality, the client should implement the two following blocks of code.
Get ECF factory from Kaa
Get specific ECF object from ECF factory
To send one or more events, the client should proceed as described in this section.
Get endpoint addresses
Execute the asynchronous findEventListeners method to request a list of the endpoints supporting all specified EC FQNs (FQN stands for fully qualified name).
Send one event to all endpoints
To send an event to all endpoints which were previously located by the findEventListeners method, execute the sendEventToAll method upon the specific ECF object.
Send one event to one endpoint
To send an event to a single endpoint which was previously located by the findEventListeners method, execute the sendEvent method upon the specific ECF object and this endpoint.
Send batch of events to endpoint(s)
To send a batch of events at once to a single or all endpoints, execute the following code.
To start listening to incoming events, execute the addListener method upon the specific ECF object.