Skip to main content
Get MQTT Gateway up and running quickly with this streamlined guide. For detailed installation instructions, see the installation guide.

​
Prerequisites

Before you begin, ensure you have:
  • Python 3.12 or higher
  • MariaDB or MySQL server (accessible on your network)
  • MQTT broker (e.g., Mosquitto, HiveMQ)
Don’t have an MQTT broker? You can use test.mosquitto.org or install Mosquitto locally with sudo apt install mosquitto mosquitto-clients

​
Installation

1

Clone and setup

Clone the repository and create a virtual environment:
git clone https://github.com/gsampallo/MQTTGateway.git
cd MQTTGateway
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
2

Install dependencies

Install the required Python packages:
pip install -r requirements.txt
This installs SQLAlchemy, PyMySQL, paho-mqtt, requests, and python-dotenv.
3

Configure environment

Create a .env file with your database and MQTT broker settings:
cp .env.example .env
Edit .env with your database credentials:
DB_HOST=192.168.0.137
DB_PORT=3306
DB_NAME=db
DB_USER=demo
DB_PASSWORD=demo
LOG_DIR=./log
HTTP_TIMEOUT_SECONDS=10
MQTT_CLIENT_ID=mqtt-gateway
MQTT_KEEPALIVE=60
FLOWS_RELOAD_INTERVAL_SECONDS=600
Update DB_HOST, DB_NAME, DB_USER, and DB_PASSWORD to match your MariaDB server configuration.
4

Start the gateway

Run the gateway:
python app.py
On first run, the gateway will:
  • Create database tables (mqtt_servers, flows, data)
  • Insert a default MQTT broker configuration
  • Connect to your MQTT broker

​
Create your first flow

Now let’s create a flow to receive and store sensor data from MQTT.
1

Connect to your database

Connect to your MariaDB database using your preferred client:
mysql -h 192.168.0.137 -u demo -p db
2

Insert a flow

Create a flow that listens to the sensors/aht10 topic and stores data in the database:
INSERT INTO flows (
  code,
  description,
  topic,
  action,
  payload_schema,
  endpoint_url,
  last_msg_id,
  enabled
)
VALUES (
  'AHT10_SENSOR',
  'Flow sensor de temperatura y humedad',
  'sensors/aht10',
  'STORE_DB',
  '{"temperature":"float","humidity":"float"}',
  NULL,
  0,
  1
);
This flow:
  • Subscribes to the sensors/aht10 MQTT topic
  • Validates incoming messages against the schema (requires temperature and humidity as floats)
  • Stores valid messages in the data table
3

Wait for flow reload

The gateway reloads flows every 10 minutes by default. To see your flow immediately, restart the gateway:
# Press Ctrl+C to stop, then restart
python app.py
In production, you can adjust FLOWS_RELOAD_INTERVAL_SECONDS to reload flows more frequently.
4

Publish a test message

Publish a test message to the MQTT broker using mosquitto_pub:
mosquitto_pub -h 192.168.0.137 -t sensors/aht10 \
  -m '{"temperature":29.47,"humidity":47.85}'
Or using Python:
import paho.mqtt.publish as publish

publish.single(
    "sensors/aht10",
    '{"temperature":29.47,"humidity":47.85}',
    hostname="192.168.0.137"
)

​
Verify the data

Query the data table to see your stored message: 
SELECT * FROM data ORDER BY received_at DESC LIMIT 10;
Expected output:
idreceived_atflow_codeattribute_nameattribute_valuelast_msg_id
12024-03-03 …AHT10_SENSORtemperature29.471
22024-03-03 …AHT10_SENSORhumidity47.851
Each attribute from the JSON payload is stored as a separate row, linked by the last_msg_id counter.

​
Try an HTTP endpoint flow

You can also forward messages to HTTP endpoints instead of storing them in the database. Create a flow with the POST_ENDPOINT action: 
INSERT INTO flows (
  code,
  description,
  topic,
  action,
  payload_schema,
  endpoint_url,
  last_msg_id,
  enabled
)
VALUES (
  'AHT10_ENDPOINT',
  'Flow para publicar a endpoint HTTP',
  'sensors/aht10/http',
  'POST_ENDPOINT',
  '{"temperature":"float","humidity":"float"}',
  'http://host.docker.internal:8080/iot/data',
  0,
  1
);
When a message arrives on sensors/aht10/http, the gateway will POST it to the configured endpoint URL.

​
Next steps

Installation guide

Detailed installation and Docker deployment instructions

Configuration

Learn about all environment variables and database settings

Flows

Understand how flows work and how to configure them

Flow examples

Explore real-world flow examples and use cases

Build docs developers (and LLMs) love

Get started for freeTalk to us