Getting started development

Documentation

Installation

# Install Python
sudo apt install python3

# Create a virtual environment
python3 -m venv .venv

# Activate the virtual environment
source .venv/bin/activate

# Install required packages
pip install mkdocs
pip install mkdocs-material
pip install mkdocs-macros-plugin

# Deactivate the virtual environment
deactivate

Build Documentation

# Activate the virtual environment
source .venv/bin/activate

# Build the documentation
mkdocs build -f mkdocs/mkdocs.yml

# Serve the documentation locally
mkdocs serve -f mkdocs/mkdocs.yml

# Deactivate the virtual environment
deactivate

Setup the development environment

Read the documentation under dev-tools about the different technical aspect of this project.

Prerequisites

• jq is necessary to automatically pre-fill dev configuration file

  sudo apt install jq
  

• step-cli is necessary for generating certificates

  wget https://dl.smallstep.com/cli/docs-cli-install/latest/step-cli_amd64.deb
  sudo dpkg -i step-cli_amd64.deb
  

• Intermediate CA files

  • dev-tools/ssl/intermediate_ca/certificate.pem
  • dev-tools/ssl/intermediate_ca/private_key.pem
  • dev-tools/ssl/intermediate_ca/passphrase

Please contact KLAS or KAMEA developers to recover these files

• A private key passphrase file
  • dev-tools/ssl/passphrase

You need to provide a passphrase file for encrypting your private key

echo "your-passphrase-here" > "dev-tools/ssl/passphrase"

• A KAMEA account : https://kamea.theembeddedkit.io/management

  • Please contact KAMEA developers to create an account

• A gitlab personal access token

  • https://gitlab.com/-/user_settings/personal_access_tokens
  • Add new token
  • Choose the name you prefer
  • Click on the checkbox "api"
  • Create personal access token
  • You need to save this token somewhere after that you can't see it anymore

Setup the environment

1. Export the GitLab Access Token
   • Paste the generated personal access token here.

       export GITLAB_ACCESS_TOKEN= <your-token-here>
     

2. Run the script setup.sh. It will configure the development environment to build and run the application properly.

   ./setup.sh -y
   

(With -y it's automatic yes to all prompts)

⚠️ Warning: Sometimes, antivirus software may block the installation of the SDK in the default /opt/... directory. In such cases, it's recommended to remove the -y option and set a different installation directory, such as /tmp/... or other directory not managed by the antivirus.

1. The generated certificate's common name will be printed

    [2025-03-14 16:23:36] [INFO] COMMON NAME: 'klas-agent-alitim@xxxxxxxxxxxx'
   

   • Go to Kamea : https://kamea.theembeddedkit.io/management
   • Add device
     • Device Type: Generic JSON device > Next
     • Device Config: Field Device name Choose the name you prefer > Create > Access channel
     • Provisioning: MQTT > X.509 CA Signed > Copy and paste the common name klas-agent-alitim@xxxxxxxxxxxx into the Common Name field > Provision
     • Config-Provisioning: Copy and paste the hostname and the port from the MQTT endpoint field like mqtts:\/\/ <hostname>:<port> into the package/config/config-provisioning.json file.
2. You will be asked to enter your password to install the SDKs

    [sudo] password for alitim: <your-password-here>
   

   • Write your login password here
3. If you're cross-compiling for another platform, source the matching SDK environment:
   • Raspbian: source /opt/raspbian/bullseye/klas-rpi4-sdk/environment-setup-aarch64-rpi4-linux-gnu
   • Yocto (including Welma): . /opt/welma/1.2.0/klas-stm32mp15-sdk/environment-setup-cortexa7t2hf-neon-vfpv4-poky-linux-gnueabi

Build

Dependencies

You need to execute this outside the project

Boost v1.86.0

  curl -sSLo boost-1.86.tar.gz https://archives.boost.io/release/1.86.0/source/boost_1_86_0.tar.gz
  tar -xvf boost-1.86.tar.gz
  ./bootstrap.sh
  sudo ./b2 install --build-type=complete --with-process --layout=tagged
  rm boost-1.86.tar.gz

OpenSSL

# libssl for compilation
sudo apt install libssl-dev

Paho CPP

git clone https://github.com/eclipse-paho/paho.mqtt.cpp.git
cd paho.mqtt.cpp
git checkout v1.5.0
git submodule init
git submodule update
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DPAHO_HIGH_PERFORMANCE=ON    \
  -DPAHO_WITH_MQTT_C=ON -DPAHO_WITH_SSL=ON -DPAHO_BUILD_STATIC=ON \
  -DPAHO_BUILD_SHARED=OFF -DPAHO_ENABLE_TESTING=OFF
sudo cmake --build . --target install

sdbus-c++

  sudo apt install -y pkg-config libsystemd-dev
  git clone https://github.com/Kistler-Group/sdbus-cpp.git
  cd sdbus-cpp && git checkout v2.1.0
  mkdir build && cd build
  cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF
  sudo cmake --build . --target install

Then, you need to setup the tools that converts xml to headers:

  cd ../tools/
  mkdir build && cd build
  cmake ..
  sudo make install

CMake Options

Command line

Build

• mkdir build && cd build && cmake .. && make

Run

• After building the project you can find the exe in build/bin/KameaLinuxAgent
• Run the project with
  • cd build/bin && ./KameaLinuxAgent

Unit Tests

• Build CMake with the option -DKLAS_UNIT_TESTING=ON
• Run the tests with make test