Skip to content

Getting started user

This getting-started page will let you deploy the agent on your platform and provision it on Kamea.

Prerequisite

  • You need to have your device created on Kamea

Refer to the Kamea documentation to learn how to create a compatible device.

  • You need to have your release package built

    A pre-built package can be found in the Package Registry of the Gitlab project.

Deploy to your platform

Debian-based distributions

Upload the package to your target

The examples below are using SSH and SCP to connect and/or to send files to the target.

scp <release-package-path> <username>@<target-ip>:<destination-path>

Then, we can proceed to the installation.

Connect to the target.

ssh <username>@<ip-address>

A password may be required depending on your configuration. Then, go to the directory you deployed the package.

For Raspbian, we'll be using dpkg to install the agent.

cd <update-directory>
dpkg -i <your-klas-release-package>.deb

Yocto and other linux distributions

Refer to the meta-klas documentation to learn how to build and integrate Klas on your Yocto platform.

Or you can cross-compile and deploy Klas, following the dedicated documentation.

Welma

For Welma devices, updatectl can also be used to install Klas on your target.

cd <update-directory>
updatectl install <package>.swu

Then reboot your device and re-ssh on it to confirm the update:

updatectl confirm

Your Kamea Linux Agent Service should be successfully installed and ran once to create default configuration files. Now, you need to generate your SSL certificate and edit your provisioning config file to establish a working connection between the agent and the cloud.

Provision your device

There are two channel to provision your device:

  • Using MQTT channel,
  • Using Iot Hub.

Using channel MQTT with CA-Signed

The safest MQTT channel but need a (little) more complicated setup;

  • The first step is to generate the certificate on your HOST Machine.

Ensure you recovered these files from Kamea Support: - certificate.pem - private_key.pem - passphrase

and place them under the dev-tools/ssl/intermediate_ca folder.

  • Then, you need to provide a passphrase file for encrypting your private key.
echo "your-passphrase-here" > "dev-tools/ssl/passphrase"
  • Generate your certificate, don't forget to replace the corresponding field with your device ID
dev-tools/ssl/generate_cert.sh package/ssl                  \
  -n <your-device-id>                                       \
  -c dev-tools/ssl/intermediate_ca/certificate.pem          \
  -k dev-tools/ssl/intermediate_ca/private_key.pem          \
  -p dev-tools/ssl/intermediate_ca/passphrase               \
  -P dev-tools/ssl/passphrase                               \
  -C dev-tools/ssl/common_name

This script will output a common-name to be used in Kamea. Save it.

  • The next step is to provision a new device on Kamea and copy/past the common-name retrieved from the script into the Kamea's common-name field. If you don't know how to provision a new device on Kamea, c.f. the Kamea documentation.
  • After successfully provisioned your device on Kamea, download the broker_ca.crt (by clicking on the big blue button at the end) and send it to the target /var/KameaLinuxAgent/ssl directory with scp as you will need it to connect to the cloud.
  • You will also need to send the generated certificate package/ssl/<device-id>.pem to the target /var/KameaLinuxAgent/ssl/, still with with scp.
  • Edit the relevant information retrieved from the device management on Kamea to /var/KameaLinuxAgent/config/config-provisioning.json as detailed below:

deviceId: the certificate's common-name
hostname: the MQTT endpoint without the mqtts:// and without everything after the last : (which is the port)
port: the endpoint port.
mode: must be set to ca-signed
channel: must be set to mqtt
trust-store the path to the broker certificate. Should be ssl/broker_ca.crt
key-store: the path to device certificate. Should be ssl/<device-certificate>.pem passphrase: The passphrase that protect your private key

password: unused and can be left empty

Using MQTT channel with Login

The fastest way - but not the safest.

  • On Kamea, provision a new device using Mqtt / Login-Password

If you don't know how to create / provision a device, check the user documentation

  • After successfully provisioned your device on Kamea, download the broker_ca.crt and send it to the target's /var/KameaLinuxAgent/ssl directory as you will need it to connect to the cloud.
  • Provide the login information to /var/KameaLinuxAgent/config/config-provisioning.json

hostname the MQTT endpoint without the mqtts:// and without everything after the last : (which is the port)
port: the endpoint port.
deviceId: the login credentials
password: the password credentials
mode: must be set to login-password
channel: must be set to mqtt
trust-store: the path to the broker certificate. Should be ssl/broker_ca.crt

passphrase and key-store are unused and can be left empty

Using Iot Hub channel with symmetric key

  • On Kamea, provision a new device using Iot Hub / Symmetric key

If you don't know how to create / provision a device, check the user documentation

  • After successfully provisioned your device on Kamea, copy the Iot hub hostname, primary and secondary connection string.
  • Provide the copied information to /var/KameaLinuxAgent/config/config-provisioning.json. This file should look like this:

"hostname": "",
"port": 8883,
"mode": "symmkey",
"channel": "azure-iot-hub",
"primary-connection-string": ",
"secondary-connection-string": ""

Using Iot Hub channel with self-signed certificate

  • On Kamea, provision a new device using Iot Hub / X.509 Self Signed method. Then, go the device settings and save the internal ID as it will be required to create the certificate. Also, save the hostname for later.

If you don't know how to create / provision a device, check the user documentation

  • On the device, create the certificate under the ssl folder next to the agent binary, with this command:
step certificate create <device-id> device.crt device.key --profile self-signed --subtle --no-password --insecure

don't forget to replace with the kamea device internal saved previously

  • Then, retrieve the certificate fingerprint and pastes it to the kamea X.509 Self Signed settings, both on primary and secondary. To retrieve the fingerprint, use:
step certificate fingerprint device.crt
  • Finally, provide the information to /var/KameaLinuxAgent/config/config-provisioning.json as followed:

"hostname": "",
"port": 8883,
"mode": "self-signed",
"channel": "azure-iot-hub",
"deviceId": "",
"trust-store": "ssl/device.crt",
"key-store": "ssl/device.key"

Run the application

In the case of using Systemd:
You can now start the service using systemctl restart klas (sudo may be required)
systemctl status klas can be used to check the agent logs.

Firmware update

Klas is used to facilitate the firmware update process by downloading the new firmware, communicating with the system, and keeping track of the update status.

To start a firmware update, refer to the Kamea documentation to learn how to:

  • Upload a new firmware version.
  • Apply the new firmware version to your device

If you want more information about the firmware update process, check the Klas Firmware Update documentation.