> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/gsampallo/MQTTGateway/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/installation).

## 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)

<Note>
  Don't have an MQTT broker? You can use test.mosquitto.org or install Mosquitto locally with `sudo apt install mosquitto mosquitto-clients`
</Note>

## Installation

<Steps>
  <Step title="Clone and setup">
    Clone the repository and create a virtual environment:

    ```bash theme={null}
    git clone https://github.com/gsampallo/MQTTGateway.git
    cd MQTTGateway
    python -m venv .venv
    source .venv/bin/activate  # On Windows: .venv\Scripts\activate
    ```
  </Step>

  <Step title="Install dependencies">
    Install the required Python packages:

    ```bash theme={null}
    pip install -r requirements.txt
    ```

    This installs SQLAlchemy, PyMySQL, paho-mqtt, requests, and python-dotenv.
  </Step>

  <Step title="Configure environment">
    Create a `.env` file with your database and MQTT broker settings:

    ```bash theme={null}
    cp .env.example .env
    ```

    Edit `.env` with your database credentials:

    ```bash theme={null}
    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
    ```

    <Warning>
      Update `DB_HOST`, `DB_NAME`, `DB_USER`, and `DB_PASSWORD` to match your MariaDB server configuration.
    </Warning>
  </Step>

  <Step title="Start the gateway">
    Run the gateway:

    ```bash theme={null}
    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
  </Step>
</Steps>

## Create your first flow

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

<Steps>
  <Step title="Connect to your database">
    Connect to your MariaDB database using your preferred client:

    ```bash theme={null}
    mysql -h 192.168.0.137 -u demo -p db
    ```
  </Step>

  <Step title="Insert a flow">
    Create a flow that listens to the `sensors/aht10` topic and stores data in the database:

    ```sql theme={null}
    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
  </Step>

  <Step title="Wait for flow reload">
    The gateway reloads flows every 10 minutes by default. To see your flow immediately, restart the gateway:

    ```bash theme={null}
    # Press Ctrl+C to stop, then restart
    python app.py
    ```

    <Info>
      In production, you can adjust `FLOWS_RELOAD_INTERVAL_SECONDS` to reload flows more frequently.
    </Info>
  </Step>

  <Step title="Publish a test message">
    Publish a test message to the MQTT broker using mosquitto\_pub:

    ```bash theme={null}
    mosquitto_pub -h 192.168.0.137 -t sensors/aht10 \
      -m '{"temperature":29.47,"humidity":47.85}'
    ```

    Or using Python:

    ```python theme={null}
    import paho.mqtt.publish as publish

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

## Verify the data

Query the `data` table to see your stored message:

```sql theme={null}
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:

```sql theme={null}
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

<CardGroup cols={2}>
  <Card title="Installation guide" icon="download" href="/installation">
    Detailed installation and Docker deployment instructions
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration/environment-variables">
    Learn about all environment variables and database settings
  </Card>

  <Card title="Flows" icon="diagram-project" href="/concepts/flows">
    Understand how flows work and how to configure them
  </Card>

  <Card title="Flow examples" icon="book" href="/reference/flow-examples">
    Explore real-world flow examples and use cases
  </Card>
</CardGroup>