mqtt2influx

A lightweight Python tool (and companion Docker image) to bridge your MQTT sensor streams into InfluxDB for time-series analysis.

---

🤔 Why This Repo Exists

MQTT is a go-to protocol for IoT and sensor data transmission - but it doesn't store data.
InfluxDB is perfect for storing time-series data - but it doesn't talk MQTT out of the box.

mqtt2influx bridges that gap:

• ✅ Subscribes to MQTT topics with minimal setup
• ✅ Writes values directly into InfluxDB with timestamps
• ✅ Enables easy graphing and querying with Grafana or Chronograf
• ✅ Eliminates the need for custom Node-RED flows or Python scripts

Whether you're monitoring temperature sensors, home automation events, or custom devices - this repo gives you a fast path from MQTT to metrics.

---

📖 Table of Contents

• Features
• Quickstart
• Configuration
• Usage
• Topics Mapping
• Docker Support

---

🧰 Features

• Simple yet powerful script to bridge MQTT → InfluxDB
• Configurable via environment variables or .env file
• Flexible topic-to-measurement mapping (topics.txt)
• Ideal for IoT setups, telemetry collection, or sensor dashboards

---

🚀 Quickstart

git clone https://github.com/mortylabs/mqtt2influx.git
cd mqtt2influx
cp .env.example .env
nano .env  # configure MQTT + Influx credentials
pip install -r requirements.txt
python mqtt2influx.py

⚙️ Configuration

Start by copying the example config:

cp .env.example .env

Then edit .env to set your connection and subscription parameters:

Variable	Description	Required	Example
MQTT_HOST	MQTT broker hostname or IP	✅	mqtt.local
MQTT_PORT	MQTT broker port	✅	1883
MQTT_USER	MQTT username (optional)	❌	myuser
MQTT_PASS	MQTT password (optional)	❌	mypassword
INFLUX_URL	Full URL to your InfluxDB server	✅	http://influx.local:8086
INFLUX_ORG	InfluxDB organization name	✅	homelab
INFLUX_BUCKET	InfluxDB bucket to store data	✅	mqtt_data
TOPICS_FILE	Path to topic mapping file	✅	topics.txt

Next, define the topics you wish to subscribe to in the text file topics.txt as follows:

MY_TOPIC1    SHORT_NAME1
MY_TOPIC2    SHORT_NAME2

🗂️ MQTT Topics to Influx Mapping

Define which MQTT topics to subscribe to and how they map to InfluxDB measurements using a simple topics.txt file.

🔧 Example topics.txt

home/sensors/temperature temperature
home/sensors/humidity    humidity
garden/moisture/level    soil_moisture

Each line follows the format:

<mqtt_topic> <influx_measurement>

💡 Notes

• Whitespace separates the MQTT topic from the desired InfluxDB measurement name.
• Wildcards (e.g., home/+/temperature, sensors/#) can be used for grouped subscriptions.
• The payload of each MQTT message is assumed to be a numeric value (e.g., temperature, voltage, etc.).
• All data is timestamped automatically when written to InfluxDB.

💡 Pro tip: You can use wildcards like home/+/temperature in topics.txt to subscribe to topic groups.

🐳 Docker Support

Run mqtt2influx using Docker for easy deployment:

🔨 Build the Docker image

bash
./build.sh

This will build a minimal Python image with the required dependencies and your current config.

▶️ Run the container

./run.sh

Make sure your .env file and topics.txt are available in the container's context (or volume-mounted).