Kaa Cloud Getting Started

Overview

In this tutorial, we will look at how to get started with the Kaa Cloud in two simple steps:

  1. Connect a device simulator to the Kaa Cloud server.
  2. Send and visualize the device simulated data on the Web Dashboard.

Prerequisites

  1. You have an account on the Kaa Cloud. It is free and has no time limit, so create one if you haven’t yet.

Playbook

Connect a device

To help you get started with the Kaa Cloud real quick, we’ve created a Python simulator that connects to the platform and simulates a real device behavior, as follows:

1. The simulator sends the following metadata to the platform on its start.

{
    "serial": "00-14-22-01-23-45",
    "mac": "50:8c:b1:77:e8:e6"
}

2. The simulator sends telemetry data of the following format every 10 seconds.

{
    "timestamp": 1569836796860,
    "temperature": 23,
    "log": "Randomly generated string: YjZgn3IbM6",
    "latitude": 37.34929,
    "longitude": -122.03247,
    "battery_level": 78.7
}

where:

  • timestamp - the current timestamp;
  • temperature - a random number in the range of 20-25;
  • log - a string with a randomly generated last part;
  • latitude - latitude taken from the file;
  • longitude - longitude taken from the file;
  • battery_level - a number in the range of 0-100.

3. The simulator listens to the HEALTH_CHECK command and responds with the following telemetry data upon receiving it.

{
    "log": "Endpoint health status: OK"
}


By default, a Kaa Cloud account includes pre-provisioned endpoint filters and software (firmware) definitions so you can play with it as well.


Now let’s proceed with the instructions to get you going.

1. Go to the “Device management” dashboard in your Kaa Cloud account.

Empty device management dashboard

As you can see there are no connected devices yet. Let’s connect one.


2. Register the device digital twin by clicking “Add Device” button. It’s called “endpoint” in Kaa.

3. Choose the application version from the drop-down menu. You can bump the application version in the application administration page as you go along and your devices evolve. Enter the desired [endpoint token][endpoint token]. The token is used for device identification during its communication with the Kaa platform. Endpoint tokens are any non-empty strings that do not contain the following reserved characters: +, #, /, and .. The token will be autogenerated if you leave this field blank.

Enter endpoint metadata and click the Save button. Metadata is simply key-value attributes that provide certain information about a device, e.g. its location, owner, customer, model, etc.

Device adding. Second step


4. Copy and save the endpoint token in some file because you won’t be able to see it again in the future. We will use the token in a bit to connect the simulator.

Device creation. The third step


5. Go to the device details page of the recently created endpoint (by clicking on the corresponding row in the device table) and copy its application version.

Copy device application version


6. Open the simulator using this link, enter the app_version_name and the device token which you have saved in the previous steps and run the simulator.

After accomplishing the step, you should see the simulator logs.

INFO: Using endpoint token , server at cloud.kaaiot.com:1883
DEBUG: Composed data collection topic: kp1//dcx//json/59
DEBUG: Composed command log topic: kp1//cex//command/HEALTH_CHECK/status
DEBUG: Composed command result log topic: kp1//cex//result/HEALTH_CHECK
INFO: Connecting to KPC instance at cloud.kaaiot.com:1883...
INFO: Successfully connected
INFO: Sent metadata: {"serial": "00-14-22-01-23-45", "mac": "50:8c:b1:77:e8:e6", "latitude": 37.35119, "longitude": -122.03248}

DEBUG: : Sent next data sample: [{"timestamp": 1573491828080, "temperature": 24, "log": "Randomly generated string: INSG0Y8OLP", "latitude": 37.35119, "longitude": -122.03248, "battery_level": 100}]
INFO: Message received: topic [kp1//dcx//json/59/status]
body []

Congratulations, you have just connected your first device simulator to the Kaa Cloud! It is time to visualize data from it.


Visualize data from the device

We are going to create two dashboards: a dashboard with a map widget displaying all devices and a dashboard with a chart widget displaying specific device data only.

1. Enter edit mode (top right corner switch) and click the “Add dashboard” button that should appear after entering the edit mode.

Add dashboard button

3. Populate the dashboard creation form as shown on the screen below.

Add top-level dashboard form

4. Now let’s add the second dashboard that displays data from the device. Again, click the “Add dashboard” button and fill the dashboard creation form. Except we don’t want to display this dashboard in the sidebar, since every time we enter the dashboard we must somehow pass a value for the endpointId dashboard URL parameter. Endpoint Location widget will do it for us later. The dashboard discovers the endpoint that it must display data for using the value of the endpointId URL parameter.

Add device-related dashboard form

5. Return back to the first dashboard, search for the Endpoint Location widget and add it. Configure the widget to route browser to the device dashboard by clicking on device pins.

Endpoint list widget configuration form

6. Save changes and arrange the widget as you like.

Top level dashboard with map


It’s time to visualize data from the device.

7. To build a chart from the temperature add and configure the Multi Series Chart widget.

Device-related dashboard with chart

8. Click the “Publish changes” button in the top right corner to save changes so that they won’t be dismissed after the page refresh.

Save changes pop-up


Congratulations, you have connected and visualized data from your device! Now play around with other simulator readings battery_level, latitude, longitude and add your own. We encourage you to experiment with the simulator source code, modify the dashboards, and get back to us with the feedback!


Explore the “Software management” dashboard and get acquainted with its capabilities.

Next steps

  • Communication - find out what is under the hood of the Kaa platform communication layer.
  • Device management - learn how the Kaa platform device management feature works.
  • Data collection - learn how the Kaa platform data collection feature works.