Quick start

Get MQTT Gateway running in under 5 minutes with this fast-track guide

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:

id	received_at	flow_code	attribute_name	attribute_value	last_msg_id
1	2024-03-03 …	AHT10_SENSOR	temperature	29.47	1
2	2024-03-03 …	AHT10_SENSOR	humidity	47.85	1

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