mqtt

MQTT adapter

MQTT adapter provides an MQTT API for sending and receiving messages through the platform. It uses mProxy (pkg/mproxy) to proxy traffic between MQTT clients and the underlying MQTT broker, intercepting connections to authenticate things and forward messages to the internal message broker.

MQTT Topics

Messages are published and subscribed to using the following topic format:

messages/<subtopic>

<subtopic> is optional and can be any path-like string (e.g. messages/sensors/temperature).

Authentication

Things authenticate over MQTT using:

• Username: Thing key type — internal or external
• Password: Thing key value

Ports

Subscriptions

The adapter persists active MQTT subscriptions to PostgreSQL (database subscriptions by default). The schema:

CREATE TABLE IF NOT EXISTS subscriptions (
    topic       VARCHAR(1024),
    group_id    UUID,
    thing_id    UUID,
    client_id   VARCHAR(256),
    status      VARCHAR(128),
    created_at  FLOAT,
    PRIMARY KEY (client_id, topic, group_id, thing_id)
);

Configuration

The service is configured using the environment variables presented in the following table. Note that any unset variables will be replaced with their default values.

Deployment

The service itself is distributed as Docker container. Check the mqtt-adapter service section in docker-compose to see how the service is deployed.

To start the service outside of the container, execute the following shell script:

# Download the latest version of the service
git clone https://github.com/MainfluxLabs/mainflux

cd mainflux

# compile the mqtt adapter
make mqtt

# Copy binary to bin
make install

# Set the environment variables and run the service
MF_MQTT_ADAPTER_LOG_LEVEL=[Log level] \
MF_MQTT_ADAPTER_MQTT_PORT=[MQTT listening port] \
MF_MQTT_ADAPTER_MQTT_TARGET_HOST=[Upstream MQTT broker host] \
MF_MQTT_ADAPTER_MQTT_TARGET_PORT=[Upstream MQTT broker port] \
MF_MQTT_ADAPTER_WS_PORT=[WebSocket listening port] \
MF_MQTT_ADAPTER_WS_TARGET_HOST=[Upstream WS broker host] \
MF_MQTT_ADAPTER_WS_TARGET_PORT=[Upstream WS broker port] \
MF_MQTT_ADAPTER_WS_TARGET_PATH=[Upstream WS path] \
MF_MQTT_ADAPTER_DB_HOST=[Subscriptions database host] \
MF_MQTT_ADAPTER_DB_PORT=[Subscriptions database port] \
MF_MQTT_ADAPTER_DB_USER=[Subscriptions database user] \
MF_MQTT_ADAPTER_DB_PASS=[Subscriptions database password] \
MF_MQTT_ADAPTER_DB=[Subscriptions database name] \
MF_BROKER_URL=[Internal message broker URL] \
MF_THINGS_AUTH_GRPC_URL=[Things service Auth gRPC URL] \
MF_THINGS_AUTH_GRPC_TIMEOUT=[Things service Auth gRPC timeout] \
MF_AUTH_GRPC_URL=[Auth service gRPC URL] \
MF_JAEGER_URL=[Jaeger service URL] \
MF_AUTH_CACHE_URL=[Auth cache URL] \
MF_MQTT_ADAPTER_ES_URL=[Event store URL] \
$GOBIN/mainfluxlabs-mqtt

Usage

Connect any MQTT client to port 1883 (plain) or 8883 (TLS) using a Thing key as the password. Publish messages to messages/<subtopic> to send them through the platform.

For the full API reference, see the AsyncAPI documentation.