Utilities

This section documents utility and support modules used across the TEG Gateway. These modules provide configuration, logging, and defensive helper functions.

Miscellaneous Helpers

Miscellaneous helper utilities for the Edge Gateway.

This module provides small, reusable helper functions that are used across multiple subsystems of the Edge Gateway. The functions are intentionally simple, stateless (where possible), and defensive to avoid propagating errors in critical runtime paths.

The utilities in this module focus on: - Safe access to nested data structures. - Defensive type extraction from loosely structured inputs. - Graceful shutdown handling on fatal errors. - Basic filesystem existence checks.

Notes

• Functions in this module are designed to never raise unexpected exceptions.

• Logging is used instead of raising where failure must not crash the gateway.

utils.misc.fatal_error(msg)

Log a fatal error and terminate the gateway gracefully.

The function logs the error together with a stack trace, waits briefly to allow logs to be flushed, and then triggers a graceful shutdown using SIGINT followed by process termination.

Parameters:

msg – Error message or exception object.

Return type:

None

utils.misc.file_exists(path)

Check whether a file exists at the given path.

Parameters:

path (str) – File path to check.

Return type:

bool

Returns:

True if the file exists and is readable, otherwise False.

utils.misc.get_instance_maybe(inst_type, *properties)

Return the first value matching a given type.

Iterates over the provided values and returns the first element that is an instance of the requested type.

Parameters:

• inst_type – Expected type.

• *properties – Values to inspect.

Return type:

Any

Returns:

First matching instance or None.

utils.misc.get_maybe(dictionary, *properties)

Safely retrieve a nested value from a dictionary.

This helper traverses a dictionary using a sequence of keys and returns None if any intermediate key is missing or if the input is None.

Parameters:

• dictionary – Source dictionary (may be None).

• *properties – Sequence of keys to traverse.

Return type:

Any

Returns:

The resolved value or None if not found.

Logging

Logging utilities for the Edge Gateway.

This module provides lightweight logging helpers used throughout the Edge Gateway and controller runtime. Log messages are printed to stdout and, when possible, published to ThingsBoard via MQTT.

If log publication fails (e.g. due to connectivity issues), messages are buffered locally in an SQLite database and can be forwarded later once connectivity is restored.

Design goals

• Avoid circular imports by resolving dependencies at runtime.

• Never block or crash the gateway due to logging failures.

• Preserve log messages during temporary connectivity outages.

Notes

• The log level is controlled via the LOG_LEVEL environment variable.

• Buffered log messages are stored in GATEWAY_LOGS_BUFFER_DB_PATH.

modules.logging.debug(message)

Log a DEBUG-level message.

modules.logging.error(message)

Log an ERROR-level message.

modules.logging.info(message)

Log an INFO-level message.

modules.logging.log(level, message)

Log a message and attempt to publish it via MQTT.

The message is always printed to stdout. If the MQTT publication fails, the log entry is stored locally in an SQLite buffer database for later processing.

Parameters:

• level (str) – Log level (e.g. DEBUG, INFO, WARN, ERROR).

• message (str) – Log message text.

modules.logging.warn(message)

Log a WARN-level message.

Paths and Configuration

Filesystem path configuration for the Edge Gateway.

This module centralizes all filesystem paths used by the Edge Gateway and the controller runtime. Paths are resolved at import time based on environment variables, with sensible defaults derived from the project directory.

The primary purpose of this module is to provide a single, consistent source of truth for: - Gateway and controller data directories - Controller Git repository and Docker build context paths - SQLite database locations used for buffering and archiving - Log storage paths

Environment variables

The following environment variables can be used to override default paths:

• TEG_DATA_PATH: Base data directory for the Edge Gateway.

• TEG_CONTROLLER_DATA_PATH: Base data directory for the controller.

• TEG_CONTROLLER_LOGS_PATH: Directory for controller log files.

• TEG_CONTROLLER_GIT_PATH: Path to the controller Git repository.

• TEG_CONTROLLER_DOCKERCONTEXT_PATH: Docker build context for the controller.

• TEG_CONTROLLER_DOCKERFILE_PATH: Path to the controller Dockerfile.

Notes

• Path resolution is performed eagerly at import time.

• Missing critical configuration (e.g. controller Git path) is treated as a fatal configuration error and logged immediately.

Args

Command-line argument parsing for the Edge Gateway.

This module defines the command-line interface (CLI) arguments supported by the TEG Gateway entry point. Parsed arguments are used to override runtime configuration such as the ThingsBoard host and port.

The CLI is intentionally minimal and primarily intended for local testing, development, and containerized deployments.

args.parse_args()

Parse command-line arguments for the Edge Gateway.

Return type:

Namespace

Returns:

Parsed command-line arguments as an argparse.Namespace.