MQTT Subscriber

Plugin parameters may be specified as key-value pairs in the --trigger-arguments flag (CLI) or in the trigger_arguments field (API) when creating a trigger. This plugin supports TOML configuration files for complex mapping scenarios, which can be specified using the config_file_path parameter.

Plugin metadata

This plugin includes a JSON metadata schema in its docstring that defines supported trigger types and configuration parameters. This metadata enables the InfluxDB 3 Explorer UI to display and configure the plugin.

Required parameters

In TOML configuration, broker_host and topics are placed under the [mqtt] section; table_name and table_name_field are placed under [mapping.json] or [mapping.text] section.

Parameter	Type	Default	Description
broker_host	string	required	MQTT broker hostname or IP address
topics	string	required	Space-separated list of topics (e.g., “sensors/temp sensors/humidity”)
table_name	string	required (json/text only)	InfluxDB measurement name for storing data. Not required for lineprotocol format or when table_name_field is set.
table_name_field	string	none	JSON field name or regex pattern to extract table name dynamically from each message. Alternative to static table_name.

Connection parameters

In TOML configuration, these parameters are placed under the [mqtt] section.

Parameter	Type	Default	Description
broker_port	integer	1883	MQTT broker port (1883 for non-TLS, 8883 for TLS)
qos	integer	1	MQTT Quality of Service level (0, 1, or 2)
client_id	string	auto-generated	MQTT client identifier (must be unique per broker)

Recommendation: Use QoS 1 for most IoT scenarios. It provides reliable delivery with minimal overhead.

Authentication parameters

In TOML configuration, these parameters are placed under the [mqtt.auth] section.

Parameter	Type	Default	Description
username	string	none	MQTT broker username (required with password)
password	string	none	MQTT broker password (required with username)

Note: Both username and password must be provided together for authentication.

TLS/SSL parameters

In TOML configuration, these parameters are placed under the [mqtt.tls] section.

Parameter	Type	Default	Description
ca_cert	string	none	Path to CA certificate file
client_cert	string	none	Path to client certificate for mutual TLS
client_key	string	none	Path to client private key for mutual TLS

Note: For mutual TLS, both client_cert and client_key must be provided together.

Message format parameters

In TOML configuration, format is placed under the [mqtt] section; timestamp_field is placed under [mapping.json] or [mapping.text] section.

Parameter	Type	Default	Description
format	string	“json”	Message format: json, lineprotocol, or text
timestamp_field	string	none	Field containing timestamp (format depends on message format)

Format-specific timestamp_field syntax:

The timestamp field format differs between JSON and Text formats:

Format	Syntax	Split Method	Example (CLI)	Example (TOML)
JSON	field_name:format	Split by first :	"timestamp:ms"	"$.timestamp:ms"
Text	regex:format	Split by last :	"ts:(\\d+):ms"	"ts:(\\d+):ms"

Note: In CLI arguments, JSON paths are specified without $. prefix (added automatically). In TOML configuration, use full JSONPath syntax with $. prefix.

Note: Text format uses the last colon to split, allowing regex patterns to contain colons (e.g., time patterns).

Supported timestamp formats: - ns - nanoseconds (Unix timestamp) - ms - milliseconds (Unix timestamp) - s - seconds (Unix timestamp) - datetime - ISO 8601 string (e.g., “2021-12-01T12:00:00Z”)

JSON format parameters

In TOML configuration, tags are placed under [mapping.json.tags] section and fields under [mapping.json.fields] section.

Parameter	Type	Default	Description
tags	string	none	Space-separated tag names. Example: “room sensor location”
fields	string	required	Space-separated field mappings. Format: “name:type=jsonpath” without $.

Field specification format: "temp:float=temperature hum:int=humidity status:bool=online"

Supported field types: int, uint, float, string, bool

Text format parameters

In TOML configuration, tags are placed under [mapping.text.tags] section and fields under [mapping.text.fields] section.

Parameter	Type	Default	Description
tags	string	none	Space-separated tag patterns. Format: “name=regex_pattern”
fields	string	required	Space-separated field patterns. Format: “name:type=regex_pattern”

Tag specification format: "room=room:([^,\\s]+) sensor=sensor:(\\w+)"

Field specification format: "temp:float=temp:([\\d.]+) status:bool=(true|false)"

TOML configuration

Parameter	Type	Default	Description
config_file_path	string	none	Path to TOML config file (absolute or relative)

To use a TOML configuration file, specify the config_file_path in the trigger arguments.

File path resolution

All file paths in the plugin (configuration file, TLS certificates) follow the same resolution logic:

• Absolute paths (e.g., /etc/mqtt/config.toml) are used as-is
• Relative paths (e.g., config.toml, certs/ca.crt) are resolved from PLUGIN_DIR environment variable

If a relative path is specified and PLUGIN_DIR is not set, the plugin will return an error.

Example TOML configuration

mqtt_config_example.toml - comprehensive configuration example with all three message formats