Terms and Concepts
In this short video, we will talk about some of the key Kaa concepts, i.e., client, endpoint, application, and application version.
Endpoint
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.
All data coming to the platform is associated with endpoints.
“Endpoint” is a cross-cutting concept—all Kaa services from the communication layer to representation one are aware of endpoints.
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:
- The 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.
Note that we mostly avoid terms such as “device” or “thing” in technical documentation. This is because an individual physical device can be represented as multiple independent endpoints; or you could open multiple connections from a single device, representing multiple clients.
Endpoint ID
Endpoint ID is used to uniquely identify an endpoint within a Kaa platform instance.
An endpoint ID is usually a UUID that is automatically generated by the Kaa at the moment of creating a new endpoint (e.g. b1857120-9e72-4886-b3c2-b1bddccbf475).
User-defined endpoint IDs are, however, also permitted as long as they match ^[a-zA-Z0-9._~-]+$ regex pattern.
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.
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.
Endpoint metadata
Endpoint metadata are key-value attributes associated with an endpoint. It can be endpoint’s location, description, serial number, hardware version, etc.
Simply put, endpoint metadata is a JSON document of a free structure that is associated with a specific endpoint.
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, HTTP, etc.) to exchange data with Kaa servers.
Application
The Kaa platform is designed to handle different types of devices simultaneously and allow them to co-exist in the scope of a single solution. To do that, we use the concept of Kaa application.
Think of Kaa application as of container where you put your system configuration that depends on the device type.
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.
Application version
Applications can have versions. Use versions to evolve your devices by adding or retiring features while keeping your old versions up and running.
Kaa supports running multiple versions simultaneously. This means that you can develop new functionality for your endpoints without disturbing your existing ones.
Due to the various compatibility reasons the application and application version names must be limited to lowercase latin letters (
a-z), digits (0-9), dashes (-) and underscores (_).
Tenant
Tenant is a secure and isolated partition within the Kaa platform where you can create, organize, and manage your resources. Each tenant’s data is isolated and invisible to other tenants sharing the application instance, ensuring data security and privacy for all tenants. A tenant manages a set of users, credentials, scopes, roles, groups, and resources. A user belongs to and logs into a tenant.
Every tenant has unique tenant ID associated with it. You can find tenant ID from any page on Kaa UI navigating to the profile icon.
