Controller Repository

The controller git repository contains the software for interfacing with device-side hardware and is managed by the TEG-gateway. It is designed to be a standalone, versioned component that is built and deployed independently from the TEG-gateway.

Architecture Overview

The controller repository:

  • is a dedicated Git repository (not part of the gateway)

  • has its own versioning and release cycle

  • is fetched and built by the gateway via the ThingsBoard OTA update mechanisms and git remote repository

  • is executed inside an isolated Docker container

  • communicates with the gateway exclusively via a local SQLite database

The TEG-gateway is responsible for:

  • building the controller Docker image

  • starting and supervising the controller Docker container

  • monitoring controller health

  • restarting the controller Docker container in case of failure

The controller is responsible for:

  • Implementing device-specific logic (sensors, actuators, control flows).

  • Writing outbound messages to the local SQLite message queue (measurements, logs).

  • Providing a periodic health check heartbeat message.

Repository Structure

A minimal controller repository must contain:

  • Dockerfile (in repository root)

  • controller source code

  • TGE-communication implementation via SQLite

  • dependency definition (e.g. requirements.txt)

A typical structure:

controller-repo/
├── Dockerfile
├── requirements.txt
├── main.py
├── db.py
├── config/
└── modules/

The gateway automatically builds the Docker image from the root Dockerfile unless a different file is specified via environment variables.

Linking the Controller Repository

The controller repository is linked to the gateway using the environment variable:

TEG_CONTROLLER_GIT_PATH

This variable must point to the controller Git repository and must have a git remote configured / authenticated for the OTA software update feature to function.

Setup details are described in: Environment variables

SQLite Communication Interface

The controller and gateway communicate via a shared SQLite database.

The controller must:

  1. Enqueue outbound messages into the messages table.

  2. Periodically update the health_check table.

Database schema definitions are documented in: Database Schemas

A reference implementation is available in:

demo/example_controller/db.py

Outbound Message Queue

Messages must be inserted into the messages table with:

  • type (telemetry, attributes, rpc, etc.)

  • message (JSON payload)

The gateway consumes and forwards these messages to ThingsBoard via MQTT.

Health Check Mechanism

The controller must periodically write a timestamp (milliseconds since epoch) to:

health_check(id=1, timestamp_ms=<now>)

The TEG-gateway monitors this timestamp to detect stalled or crashed controllers.

Failure Handling

Controllers must fail fast and exit the main process if an unrecoverable error occurs.

The TEG-gateway will automatically restart the container using an exponential backoff.

Controllers must not:

  • Attempt self-restarts

  • Implement their own process supervision

  • Modify the database schema

Main Loop Requirements

A typical controller main loop should:

  1. Initialize configuration.

  2. Connect to the SQLite database.

  3. Initialize sensors/actuators.

  4. Enter execution loop.

  5. Perform periodic tasks.

  6. Write health check in every iteration.

Example pattern:

while True:
    read_sensors()
    process_logic()
    enqueue_messages()
    write_health_check()
    sleep(interval)

Optional Components

Base Classes

Reusable base classes for sensors and actuators are recommended to:

  • Standardize device interfaces

  • Reduce boilerplate

  • Improve testability

Example implementations are provided in:

demo/example_controller/sensor and demo/example_controller/actuator

Remote Configuration

Controllers can use the gateway Remote File Management to receive configuration files (e.g. config.json).

Typical workflow:

  • File is managed via ThingsBoard UI using shared attributes (see Remote File Management ).

  • Gateway syncs file to controller data folder (mounted to controller docker container filesystem).

  • Controller reads configuration at startup.

  • Configurable: Configuration changes trigger controller restart.

Example Controller

A minimal working controller is available at:

demo/example_controller/

It includes:

  • SQLite communication module

  • Example sensor and actuator base classes

  • Minimal main loop

  • Dockerfile

  • Requirements file

You may use this as a starting template for new implementations.