MQTT v3.1.1 Gateway

TinyMQ v2.7.0 introduced a native, zero-dependency MQTT v3.1.1 gateway on TCP port 1883.

This allows IoT devices, microcontrollers (like ESP32/Arduino), and standard MQTT clients to publish and subscribe to the TinyMQ broker directly.

Cross-Protocol Routing

TinyMQ seamlessly translates between protocols. A message published via HTTP can be consumed by an MQTT client, and vice versa.

Supported Features

• Connect: With or without authentication.
• Publish: QoS 0 and QoS 1 are fully supported. (QoS 2 packets are gracefully rejected).
• Subscribe: Supports multiple topics per packet.
• Ping: PINGREQ and PINGRESP for keep-alive.
• OOM Protection: MQTT connections respect the broker's 2 MB payload limit.

Topic Mapping & Wildcards

MQTT uses different wildcard characters than standard regex. TinyMQ automatically translates MQTT wildcards into its internal wildcard format.

MQTT Pattern	TinyMQ Translation	Description
#	*	Matches everything (multi-level)
+	*	In TinyMQ, single-level + is currently mapped to *

Authentication

If you have secured your broker using the TINYMQ_API_KEY environment variable, MQTT clients must provide this key to connect.

• Username: Ignored.
• Password: Must exactly match the TINYMQ_API_KEY. TinyMQ uses constant-time comparison to prevent timing attacks.

Example: Mosquitto CLI

Publish a message:

mosquitto_pub -h localhost -p 1883 -t "sensor/temp" -m "24.5" -P "your_api_key"

Subscribe to a topic:

mosquitto_sub -h localhost -p 1883 -t "sensor/#" -P "your_api_key"

Example: Python (Paho-MQTT)

import paho.mqtt.client as mqtt

def on_message(client, userdata, msg):
    print(f"Received: {msg.payload.decode()} on {msg.topic}")

client = mqtt.Client()
client.username_pw_set(username="", password="your_api_key")
client.on_message = on_message

client.connect("localhost", 1883, 60)
client.subscribe("sensor/#")
client.loop_forever()

Disabling MQTT

If you don't need the MQTT gateway and want to close port 1883, set:

TINYMQ_MQTT_DISABLE=true