Gateway Runtime

This section documents the core runtime components of the TEG Gateway. These modules define the application entry point, startup sequence, and initial device provisioning.

Main Loop

Main entry point for the TEG Gateway.

This module implements the primary runtime loop of the Edge Gateway. It is responsible for initializing all subsystems, establishing communication with ThingsBoard, and coordinating message flow between the controller, local persistence layers, and remote services.

Responsibilities

• Parse command-line arguments and perform self-provisioning if required.

• Initialize local SQLite databases used for buffering and archiving.

• Start and supervise the MQTT client connection to ThingsBoard.

• Dispatch incoming MQTT messages to RPC, OTA, and remote file management handlers.

• Persist and forward controller telemetry and log messages.

• Supervise the controller container and trigger restarts if required.

• Publish auxiliary health and timing telemetry.

Notes

• The main loop is intentionally single-threaded for deterministic behavior.

• Background daemon threads are used only for MQTT I/O and file change detection.

• Fatal errors result in a graceful shutdown followed by forced termination if necessary.

main.forced_shutdown_handler(_sig, _frame)

Handle forced shutdown if graceful shutdown fails.

This handler is triggered by a SIGALRM when the graceful shutdown timeout is exceeded and terminates the process immediately.

Return type:

None

main.get_last_controller_health_check_ts()

Return the timestamp of the last controller health check.

Return type:

int

Returns:

Unix timestamp in milliseconds of the last recorded health check, or 0 if no health check has been recorded.

main.shutdown_handler(sig, _frame)

Handle graceful shutdown of the Edge Gateway.

This handler is invoked on SIGINT and SIGTERM. It attempts to shut down all subsystems cleanly, including MQTT connections and SQLite databases, before terminating the process.

Parameters:

• sig (Any) – Received signal number.

• _frame (Any) – Current stack frame (unused).

Return type:

None

Self-Provisioning

This module implements the initial device self-provisioning workflow used to obtain credentials and establish a trusted connection to ThingsBoard on first startup.

Self-provisioning logic for the Edge Gateway.

This module implements MQTT-based self-provisioning against ThingsBoard to obtain an access token for the Edge Gateway at first startup.

If an access token already exists locally, self-provisioning is skipped. Otherwise, the gateway connects using the ThingsBoard provisioning credentials and requests a new device access token, which is persisted locally for future use.

Notes

• Provisioning uses the ThingsBoard MQTT provisioning API.

• TLS is always enabled; a custom CA certificate can be supplied via environment variables.

• Provisioning is a blocking operation and is expected to run only during startup.

self_provisioning.get_device_name(args)

Determine the ThingsBoard device name for this gateway.

The device name is resolved in the following order: 1. Explicit --device-name CLI argument (if present) 2. THINGSBOARD_DEVICE_NAME environment variable 3. Local hostname 4. Randomly generated fallback name

Parameters:

args (Namespace) – Parsed command-line arguments.

Return type:

str

Returns:

Resolved device name string.

self_provisioning.self_provisioning_get_access_token(args)

Obtain a ThingsBoard access token via self-provisioning if required.

The function first checks whether an access token already exists locally. If so, it returns the existing token. Otherwise, it performs MQTT-based self-provisioning to request a new access token from ThingsBoard.

Parameters:

args (Namespace) – Parsed command-line arguments containing ThingsBoard connection details.

Return type:

Tuple[bool, str]

Returns:

Tuple (created, access_token), where created indicates whether a new token was generated during this call.