Create Import Application¶

An Import Application is designed to collect information from Assets or external sources and save them to the Kelvin Platform.

1

$ kelvin app create --app-type importer <IMPORT_NAME>

This will give a response similar to this;

1
2
3
4

[kelvin.sdk][2025-09-02 04:12:01][I] Refreshing metadata..
[kelvin.sdk][2025-09-02 04:12:02][I] Creating new application "demoimporter"
[kelvin.sdk][2025-09-02 04:12:02][R] Successfully created new application: "demoimporter".
[kelvin.sdk][2025-09-02 04:12:02][I] Kelvin code samples are available at: https://github.com/kelvininc/app-samples

This will automatically create an Import Application bootstrap within a new directory and populated with some default files and configurations.

Folder Structure¶

You can now open the folder in your favorite IDE or editor and start to modify the files to create your Import Application.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

$ cd demoimporter
$ tree ./
├── .dockerignore
├── Dockerfile
├── app.yaml
├── main.py
├── requirements.txt
└── ui_schemas
    ├── configuration.json
    └── io_default.json

Below is a brief description of each file.

app.yaml¶

The app.yaml is the main configuration file that holds both Application definitions as well as the deployment/runtime configuration.

It is composed of the following sections:

spec_version key¶

The spec_version key is automatically injected and specifies the Import Application JSON Schema (latest) version which both defines and validates the app.yaml structure.

1

spec_version: 5.0.0

type¶

This defines the type for the application.

• app: A Smart App that allows mapping inputs and outputs to data streams, sending control changes, recommendations, and data tags.
• docker: An docker application that does not connect to the platform's data streams.
• importer: Connects to an external system to import data into the platform as well as receive control changes to act on the external system.
• exporter: Connects to the platform to export data to an external system.

1

type: importer

info¶

The root section holds the Import Application basic information required to make itself uploadable to Kelvin's App Registry.

1
2
3
4

name: camera-connector
title: Camera Connector
description: Publishes camera feed images to Kelvin Platform.
version: 1.0.0

The name is the Import Application's unique identifier.

The title and description will appear on the Kelvin UI when creating a Connector once the Import Application is uploaded.

The version defines the version of this Import Application and is used in the Kelvin UI.

flags¶

This is where you are able to set some of the Application's capabilities.

1
2
3
4
5

flags:
  enable_runtime_update:

    # enables configuration updates at runtime
    configuration: false 

importer_io¶

This is the main section that defines the types and function of the Data Streams that are allowed for this Import Application.

1
2
3
4
5
6
7
8

# definition of which kind of datastreams are allowed to be deployed
importer_io:
  - name: default
    data_types:    # default: [number, string, boolean, object name]
      - number
      - string

    control: true # the app allows control

ui_schemas¶

This is where the Importer configuration are defined for the Kelvin UI.

The actual information is kept in a json file in the schemas folder of the project. The file location is defined in the app.yaml file like this;

1
2
3
4
5
6
7
8
9

# optional to generate UI schemas
ui_schemas:

  # app configuration schema
  configuration: "ui_schemas/configuration.json" # default: "ui_schemas/configuration.json"

  # Importer_io configuration schema
  io_configuration:
    default: "ui_schemas/io_configuration/io_default.json" # default: "ui_schemas/io_default.json"

Below is some information on the content options in the json files.

configuration.json

The configuration.json file will come with default blank schemas when first created.

1
2
3
4
5

{
    "type": "object",
    "properties": {},
    "required": []
}

An example of a Configurations file filled in would look something like this;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
    "type": "object",
    "properties": {
      "upload_interval": {
        "type": "number",
        "title": "Upload Interval",
        "minimum": 0,
        "maximum": 100
      }
    },
    "required": ["upload_interval"]
}

Which will be displayed on the Kelvin UI like this:

io_default.json

These are for the definition of any objects data_types.

If not defined they use the default ui_schemas/io_default.json.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
    "type": "object",
    "properties": {
      "address": {
        "type": "number",
        "title": "Address",
        "minimum": 1,
        "maximum": 49999
      }
    },
    "required": ["address"]
}

defaults¶

This section hold four main sections;

• system : Is used to set different system requirements/constraints within the Import Application running environment. i.e. Resources, Environment Variables, Volumes, Ports, etc.

1
2

defaults:
  system: {}

defaults/system section

The system section is [optional].

This is where developers can set the system settings that the Import Application needs to be able to function as intended.

This includes opening ports, setting environment variables, limited resource usage, attaching volumes and setting the privileged tag which gives extended privileges on the host system.

1
2
3
4

defaults:
  system:
    environment_vars: []
    volumes: []

1
2
3
4
5
6
7
8
9

defaults:
  system:
    resources:
      requests:   # Reserved
        cpu: 100m
        memory: 256Mi
    limits:     # Limits
        cpu: 200m
        memory: 512Mi

1
2
3
4
5
6
7
8
9

defaults:
  system:
    environment_vars:
      - name: AZURE_ACCOUNT_NAME
        value: <% secrets.azure-account-name %>
      - name: AZURE_ACCOUNT_KEY
        value: <% secrets.azure-account-key %>
      - name: AZURE_STORAGE_CONTAINER
        value: <% secrets.azure-storage-container %>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

defaults:
  system:
    volumes:
      # Folder Volume
      - name: serial-rs232
        target: /dev/rs232 # Container path
        type: host
        host:
        source: /dev/ttyS0 # Host path

      # Persistent Volume
      - name: extremedb
        target: /extremedb/data
        type: persistent

      # File/Text Volume
      - name: model-parameters
        target: /opt/kelvin/data/parameters.bin
        type: text # Renders data into a file
        text:
        base64: true
        encoding: utf-8
        data: |-
              SGVsbG8gUHJvZHVjdCBHdWlsZCwgZnJvbSB0aGUgRW5naW5lZXJpbmcgR3VpbGQhCg==

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

defaults:
  system:
    ports:
      - name: http
        type: host # Exposed on the host
        host:
        port: 80

      - name: opcua
        type: service # Exposed as a service for other containers
        service:
        port: 48010
        exposed_port: 30120
        exposed: true

1
2
3

defaults:
  system:
      privileged: true

config.yaml¶

You use config.yaml to override default configurations defined in your app.yaml file during local development and testing.

This file provides a secure way to manage sensitive data like credentials, API keys, and environment-specific settings without committing them to version control or uploading them to the cloud platform.

The configuration loading follows a strict hierarchy: config.yaml → app.yaml defaults → graceful failure.

This ensures your SmartApp always prioritizes local overrides while falling back to safe defaults when appropriate.

The file itself will contain any hierarchy from the configurations key only.

If the app.yaml has this;

1
2
3
4
5
6
7
8
9

# app.yaml
defaults:
  configuration:
    threshold: 50.0
    interval: 60
    mqtt:
      host: <% secrets.mqtt_host %>
      username: <% secrets.mqtt_username %>
      password: <% secrets.mqtt_password %>

Then the local config.yaml will look like this;

1
2
3
4
5
6
7
8

# config.yaml
threshold: 75.0
interval: 30
mqtt:
  host: "localhost_from_config"
  username: "user_from_config"
  password: "password_from_config"
debug_mode: true

Python¶

The main.py is used as the entry point of the Import Applications. When it runs, main.py is typically the first script that gets executed, and it usually contains the main logic or orchestrates the flow of the Import Applications. However, naming a file "main.py" is just a convention, and it's not mandatory. The name helps developers quickly identify where the primary logic of the Import Applications begins.

The code example generated upon kelvin app create should be deleted and replaced as this is designed for a Kelvin SmartApp™.

Here is an example script that will grab an image from an RTSP camera stream and import it into the Kelvin Platform.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

import asyncio
import base64
import cv2
import json
import os

from kelvin.application import KelvinApp
from kelvin.message import KMessageTypeData, Message
from kelvin.message.krn import KRNAssetDataStream

async def capture_rtsp_frames(rtsp_url):
    cap = cv2.VideoCapture(rtsp_url)
    if not cap.isOpened():
        raise Exception("Failed to open RTSP stream")

    while True:
        ret, frame = cap.read()
        if not ret:
            print("Failed to grab frame")
            continue

        _, buffer = cv2.imencode('.jpg', frame)
        base64_image = base64.b64encode(buffer).decode('utf-8')
        yield {"image_filename": "rtsp_frame.jpg", "image_base64": base64_image}

        await asyncio.sleep(1)  # Adjust based on your needs

async def main() -> None:
    # Creating instance of Kelvin App Client
    app = KelvinApp()

    # Connect the App Client
    await app.connect()

    rtsp_url = "rtsp://your_rtsp_stream_url"
    frame_generator = capture_rtsp_frames(rtsp_url)

    while True:

        # Get the next image from the generator
        image = next(image_generator)

        for asset in app.assets.keys():
            print(f'publishing to asset {asset} with image {image["image_filename"]}')

            await app.publish(Message(
                type=KMessageTypeData(primitive="object", icd="camera-image"),
                resource=KRNAssetDataStream(asset, "camera-feed"),
                payload=json.dumps(image)
            )
        )

        # Custom Loop
        await asyncio.sleep(30)


if __name__ == "__main__":
    asyncio.run(main())

Supporting Files¶

1
2
3
4
5
6
7
8

FROM python:3.10-slim

ENV PYTHONUNBUFFERED=1
WORKDIR /opt/kelvin/app
COPY . /opt/kelvin/app
RUN pip install -r requirements.txt

ENTRYPOINT python main.py