Remote File Management

This section documents the remote file management subsystem, which enables configuration files to be defined, synchronized, validated, and applied remotely via ThingsBoard attributes.

File Writer

Remote file read/write utilities for the Edge Gateway.

This module implements the client-side logic required for the Remote File Management feature. It is responsible for reading local files, computing file hashes, detecting changes, and synchronizing file contents and metadata with ThingsBoard via client attributes.

The GatewayFileWriter acts as a singleton and maintains in-memory state about managed files and their last known hashes to enable efficient change detection.

Responsibilities

• Read local files in binary or encoded form (text, JSON, base64).

• Compute and track file hashes for change detection.

• Mirror file contents back to ThingsBoard using FILE_READ_<file_key> attributes.

• Support path expansion using gateway environment variables (e.g. $DATA_PATH).

Notes

• File definitions and expected encodings are provided via shared attributes (see the Remote File Management user guide).

• This module does not apply file updates itself; it only handles reading, hashing, and reporting.

class modules.file_writer.GatewayFileWriter

Bases: object

Handle local file reading and hash tracking for remote file management.

This class maintains the current file definitions, the last known file hashes, and provides helper methods to read files and detect changes. It is implemented as a singleton to ensure consistent state across the gateway process.

calc_file_hash(path)

Calculate the MD5 hash of a file.

Parameters:

path (str) – Absolute path to the file.

Return type:

str

Returns:

MD5 hash string, or E_NOFILE if the file does not exist.

did_file_change(path)

Check whether a file has changed since the last read.

Parameters:

path (str) – Absolute path to the file.

Return type:

bool

Returns:

True if the file content has changed, otherwise False.

expand_file_path(file_path)

Expand environment variables in a file path.

Replaces occurrences of $DATA_PATH and legacy placeholders with the resolved controller data path.

Parameters:

file_path (Optional[str]) – Raw file path from the FILES definition.

Return type:

Optional[str]

Returns:

Expanded absolute file path, or None if input is None.

files: dict | None = None

get_files()

Return the current file definitions.

Return type:

dict

Returns:

Dictionary of managed file definitions.

Raises:

Exception – If file definitions have not been initialized.

get_tb_file_hashes()

Return the file hashes received from ThingsBoard.

Return type:

Optional[dict]

Returns:

Hash dictionary or None if not available.

hashes: dict[str, str] = {}

read_file(file_path, file_encoding)

Read a file and return its contents encoded as a string.

Parameters:

• file_path (str) – Absolute path to the file.

• file_encoding (str) – Encoding type (text, json, or base64).

Return type:

str | None

Returns:

Encoded file content as a string, or None if the file does not exist.

read_file_raw(file_path)

Read a file from disk as raw bytes and update its cached hash.

Parameters:

file_path (str) – Absolute path to the file.

Return type:

bytes | None

Returns:

File contents as bytes, or None if the file does not exist.

set_files(files)

Set the current file definitions.

Parameters:

files (dict) – Dictionary defining managed files as provided by the FILES attribute.

Return type:

None

set_tb_hashes(hashes)

Set the file hashes received from ThingsBoard.

Parameters:

hashes (dict) – Hash dictionary from the FILE_HASHES client attribute.

Return type:

None

tb_hashes: dict | None = None

modules.file_writer.write_file_content_to_client_attribute(file_identifier, file_content)

Publish file contents to a ThingsBoard client attribute.

Parameters:

• file_identifier (str) – Logical file key as defined in the FILES attribute.

• file_content (str) – File content encoded according to the file definition.

Return type:

None

Definition and Synchronization

File Definition Update

Handle remote file definition updates received via MQTT.

This module processes ThingsBoard shared attribute updates of the FILES object and validates the remote file definitions used by the Edge Gateway for Remote File Management.

Responsibilities

• Parse and validate incoming FILES definitions.

• Verify required properties such as file paths and encodings.

• Reject invalid or unsupported file definitions early.

• Update the active file definitions in GatewayFileWriter.

• Trigger a file hash synchronization request (FILE_HASHES).

Notes

• File content updates and hash reconciliation are handled by check_for_file_content_update and check_for_file_hashes_update respectively.

• This module performs validation only; it does not apply file contents.

on_mqtt_msg.check_for_files_definition_update.on_msg_check_for_files_definition_update(msg_payload)

Process an incoming file definition update message.

Parameters:

msg_payload (Any) – MQTT message payload containing shared attributes.

Return type:

bool

Returns:

True if the message was handled as a file definition update, False otherwise.

File Hashes Update

Handle remote file hash synchronization updates received via MQTT.

This module processes ThingsBoard client attribute updates for FILE_HASHES and implements the synchronization side of the Remote File Management workflow.

Responsibilities

• Compare local file hashes with hashes reported by ThingsBoard.

• Detect missing, modified, or outdated files on the Edge Gateway.

• Request file content updates via FILE_CONTENT_<file_key> when required.

• Mirror local file state back to ThingsBoard using FILE_READ_<file_key>.

• Publish updated FILE_HASHES client attributes after reconciliation.

Notes

• File metadata (paths, encodings, write versions) is defined via the FILES shared attribute.

• This module complements on_mqtt_msg.check_for_file_content_update, which applies incoming file content updates.

on_mqtt_msg.check_for_file_hashes_update.on_msg_check_for_file_hashes_update(msg_payload)

Process an incoming file hash synchronization message.

Parameters:

msg_payload (Any) – MQTT message payload containing client attributes.

Return type:

bool

Returns:

True if the message was handled as a file hash update, False otherwise.

Content Application

Handle remote file content updates received via MQTT.

This module processes ThingsBoard shared attribute updates of the form FILE_CONTENT_<file_key> and applies the corresponding file changes on the Edge Gateway filesystem.

It implements the apply side of the Remote File Management workflow: - Decode incoming file content according to its declared encoding. - Write updated file contents to disk. - Recalculate and publish file hashes (FILE_HASHES). - Mirror updated file contents back via FILE_READ_<file_key> attributes. - Optionally trigger a controller restart if required by the file definition.

Notes

• File metadata (paths, encodings, flags) is defined in the FILES shared attribute.

• Hash synchronization logic is coordinated with on_mqtt_msg.check_for_file_hashes_update.

on_mqtt_msg.check_for_file_content_update.on_msg_check_for_file_content_update(msg_payload)

Process an incoming file content update message.

Parameters:

msg_payload (Any) – MQTT message payload containing shared attributes.

Return type:

bool

Returns:

True if the message was handled (even if no update was applied), False if the message is not related to file content updates.