Kaa concepts

This page is for new Kaa users. It describes main Kaa entities and concepts.

If you don’t feel like reading, here is a 3 minutes video that covers the key terms such as Kaa endpoint, client, application and application version.

Endpoints

In Kaa lingo, endpoints (EP) represent the things element of the IoT equation. An endpoint is any terminal device that you want to manage with the Kaa platform. An endpoint can either be a physical device or a software emulation thereof.

To be precise, endpoint can be lesser unit than a device which means that a physical device can include multiple endpoints. For example, you want to manage a thermostat with the Kaa platform, so that the air conditioning will automatically turn on and off at certain temperature.

You can manage your thermostat in one of the following ways:

  • Whole thermostat unit acts as a single endpoint exchanging data (readings of temperature, etc.) with Kaa server.
  • Thermostat components (temperature and humidity sensors, on/off switch, etc.) act as individual endpoints.

Diagram showing device containing endpoints

Endpoint ID

Endpoint ID is used to uniquely identify an endpoint within a Kaa platform instance. An endpoint ID is a UUID that is automatically generated by the Kaa at the moment of creating a new endpoint (e.g. b1857120-9e72-4886-b3c2-b1bddccbf475). Endpoint ID cannot be changed once created.

All endpoint data, such as metadata attributes, collected time series data points, commands, etc., is associated with a specific endpoint ID. Whenever you retrieve or manage endpoint-related data in Kaa (mainly via REST API or NATS), you will see endpoint IDs.

Endpoint token

Endpoint tokens are used for endpoint identification during the endpoint communication with the Kaa platform. Tokens are unique in scope of application and assigned to exactly one endpoint. When a message arrives to the Kaa platform, endpoint token is resolved into an endpoint ID.

Each message sent to the platform must have an endpoint token so that the platform could identify the endpoint, on behalf of which the message was sent. In the case of the Kaa Protocol over MQTT, endpoint token goes inside the MQTT topic.

Endpoint tokens are any non-empty strings that do not contain the following reserved characters: +, #, /, and .. Typically, tokens are pseudo-random strings automatically generated by Kaa (e.g. JTjdbENzHh), but for convenience you can also provision your endpoint tokens (e.g. device serial number, MAC address, etc.).

Decoupling of endpoint tokens and endpoint IDs allows you to suspend, revoke, reactivate, and re-issue endpoint tokens without impacting the endpoint ID. To communicate with the Kaa platform, your devices or gateways do not need to know endpoint IDs,—just tokens.

Kaa client

To have your devices (endpoints) exchange data with the Kaa servers, you need a client.

Kaa client is a piece of software that recognizes your endpoints and sends their data to Kaa servers, as well as receives data from Kaa servers. You can use your client to represent as many endpoints to your Kaa platform as you need.

Your Kaa client can be any software application that supports an IoT protocol (MQTT, CoAP, etc.) to exchange data with Kaa servers.

Application

Application is the concept in Kaa that helps you manage different types of endpoints and define functionality they support.

For example, you want to manage a smart house containing fridges and coffee machines. In this case you can set up two different applications: one for your fridges and the other one for your coffee machines. This means that all your fridges will be represented as a set of endpoints in one application while all the coffee machines will live in the other application.

Applications can have versions. Use versions to evolve your devices by adding or retiring features.

Kaa supports running multiple versions simultaneously. This means that you can develop new functionality for your endpoints without disturbing your existing ones.

Diagram showing different application structures

Read more about Kaa applications and versions in the architecture overview.

Kaa services

The Kaa platform design is based on microservices. In Kaa context, the microservices comprising the Kaa platform are simply called Kaa services, or even simpler—services.

Kaa service is a set of server software functionality packaged in a Docker image. To use a stack of services as one integrated platform, you need to deploy them in a cluster. The same service can run in a cluster with different configurations—service instances.

In other words, a service is a software module offering some piece of functionality for a practical purpose like security, data collection, data transport and storage, device communication and management, etc. Think of the services as the building blocks that you stack up together to form your Kaa solution. You don’t need all types of blocks at once, but only the right ones to do the job.

Diagram showing services as platform building blocks

For example, you want to start off with simply collecting data from your device and visualizing it on a dashboard—then you will only need to install Kaa services for data collection and vizualization. Say, you then realized that you also want to store your data and have some access management functionality—no problem, just add the respective Kaa services to your deployment. Think of software plug-ins that you simply download and install as needed—same with Kaa services, you download and install them in your platform for additional functionality.

You can include different number of services of different types in the platform, depending on the use case and your expectations. This means that the scale, complexity, and functionality of your Kaa platform deployment is variable upon your needs and case specifics.

The Kaa team is continuously developing an extensive number of services for you to choose from. Also, you can develop your own services and integrate them in the platform.

For detailed documentation on each Kaa service, use the Components dropdown list at the top of the page.

Extension services

Extensions (extension services) are special Kaa platform services that implement various IoT functionality offered by the platform to the endpoints, e.g. data collection, configuration management, metadata attributes synchronization, etc. As a rule of thumb, when you see a service short name that ends with an “X”—that is likely an extension service. Examples of the Kaa platform extensions are Data Collection extension (DCX), Endpoint Metadata extension (EPMX), Configuration Management extension (CMX), etc.

All extensions sit behind the platform communication layer and interoperate with the communication service (see KPC). Such architecture allows you to easily expand the Kaa platform with a new IoT functionality by just dropping a new extension behind the communication layer:

Diagram showing extension services

Read about the Kaa Protocol MQTT topic structure to understand how endpoint messages are routed to the extensions.

Service interface protocols

Different services are designed to handle data differently. Structures and formats of data that different services work with are documented in the interface protocols filed as a list of Kaa RFCs. Apart from regulating the data exchange between Kaa services, Kaa RFCs define rules for almost all the platform entities.

Solution cluster

Given the microservice nature of the platform, your Kaa-based IoT solution will be deployed as a cluster of microservices.

Kaa solution is a managed set of interrelated Kaa applications that work together to cover an IoT use case.

Within a Kaa solution cluster, some of the services perform business logic functions, while the others fulfill infrastructure responsibilities necessary for the cluster operation (load balancing, fault tolerance, etc.).

Blueprint

Kaa blueprint is a detailed declarative description of a certain Kaa solution deployment, all its setup and configuration parameters.

Once you defined a blueprint for your Kaa solution, you can have the solution working while continuing to develop the blueprint: you can store it, scale it, tweak it, test it, deploy it elsewhere, etc.

Blueprint contains information about the names, versions, and all configuration parameters of services used in the applications of your Kaa solution. It also contains information about the environment and deployment parameters used to set up the solution cluster.