MQTT Transport

When to Use MQTT

Use MQTT instead of the default Socket.IO transport when:

Your device has limited RAM (microcontrollers, Pico W)
The network connection is unreliable or intermittent
You need offline message queueing (commands delivered when the device reconnects)
You are already running an MQTT infrastructure
The device is battery-powered and needs a lightweight protocol

The Lua Device Gateway runs an MQTT broker at wss://mqtt.heylua.ai/mqtt. You do not need to run your own broker.

Configuration

For a new Node.js installation, provision a device credential for the exact agent, device name, and operations that the device uses. The published Python 1.3.0 client and the current MicroPython distribution continue to use api_key with existing legacy keys.

Node.js

import { DeviceClient } from '@lua-ai-global/device-client';

const device = new DeviceClient({
  agentId: 'your-agent-id',
  deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
  deviceName: 'pico-sensor-01',
  transport: 'mqtt',
  mqttUrl: 'wss://mqtt.heylua.ai/mqtt', // default, can be omitted
  commands: [
    { name: 'read_sensor', description: 'Read temperature and humidity' },
  ],
});

device.onCommand('read_sensor', async () => {
  return { temperature: 22.5, humidity: 60 };
});

await device.connect();

Python

import asyncio
import os
from lua_device import DeviceClient, DeviceCommandDefinition

client = DeviceClient(
    agent_id="your-agent-id",
    api_key=os.environ["LUA_API_KEY"],
    device_name="pico-sensor-01",
    transport="mqtt",
    mqtt_url="wss://mqtt.heylua.ai/mqtt",  # default, can be omitted
    commands=[
        DeviceCommandDefinition(name="read_sensor", description="Read temperature and humidity"),
    ],
)

@client.on_command("read_sensor")
async def handle_read_sensor(payload):
    return {"temperature": 22.5, "humidity": 60}

asyncio.run(client.connect())

MicroPython

from lua_device import LuaDevice

device = LuaDevice(
    agent_id="your-agent-id",
    api_key="your-api-key",
    device_name="pico-sensor-01",
    server="mqtt.heylua.ai",
    port=443,
)

@device.command("read_sensor")
def read_sensor(payload):
    return {"temperature": 22.5, "humidity": 60}

device.connect()
device.run()  # blocks, listens for commands

Topic Structure

All MQTT topics follow a consistent prefix pattern:

lua/devices/{agentId}/{deviceName}/{suffix}

Topic Suffix	Direction	QoS	Retained	Purpose
`status`	Device publish	1	Yes	Online/offline status (retained for broker persistence)
`heartbeat`	Device publish	0	No	Keepalive signal every 30 seconds
`response`	Device publish	1	No	Command execution results
`trigger`	Device publish	1	No	Device-to-agent event triggers
`command`	Device subscribe	1	No	Incoming commands from the agent
`connected`	Device subscribe	1	No	Server connection confirmation
`trigger_ack`	Device subscribe	1	No	Trigger receipt acknowledgment
`trigger_result`	Device subscribe	1	No	Trigger execution results (optional)
`error`	Device subscribe	1	No	Server-side error messages
`pong`	Device subscribe	0	No	Heartbeat response

Last Will and Testament (LWT)

The MQTT client automatically sets a Last Will and Testament message on the status topic. If the device disconnects unexpectedly (network failure, power loss), the broker publishes the LWT message, which the gateway uses to immediately mark the device as offline.

{
  "status": "offline",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

This is more reliable than heartbeat-based detection alone, since the broker publishes the LWT within seconds of losing the TCP connection.

QoS Levels

QoS	Meaning	Used For
0	At most once (fire-and-forget)	Heartbeats — acceptable to miss one
1	At least once (with acknowledgment)	Commands, responses, triggers, status — must not be lost

The device client uses QoS 1 for all messages except heartbeats. Combined with persistent sessions (clean: false), this means commands are queued by the broker when the device is temporarily offline and delivered when it reconnects.

The idempotency dedup layer on the device (LRU cache of recent commandId values) ensures that redelivered QoS 1 messages do not cause duplicate command execution.

Authentication

MQTT authentication uses the username and password fields of the MQTT CONNECT packet:

Field	Value
`clientId`	`lua-{agentId}-{deviceName}`
`username`	`{agentId}:{deviceName}`
`password`	Node.js/custom clients: device credential. Published Python/MicroPython clients: existing legacy `api_key`.

For a typed device credential, the CONNECT password is the only MQTT message that contains the secret. The client sends its command manifest in a separate non-retained status message without the credential. Retained status messages never contain a secret. Existing clients that use a non-dotted legacy key keep their current behavior. They send the key as the CONNECT password and in the existing non-retained apiKey status field. See Device credentials.

Complete Example

A humidity and temperature monitor that fires an alert trigger when conditions are out of range:

import { DeviceClient } from '@lua-ai-global/device-client';

const device = new DeviceClient({
  agentId: process.env.LUA_AGENT_ID!,
  deviceCredential: process.env.LUA_DEVICE_CREDENTIAL!,
  deviceName: 'greenhouse-sensor',
  transport: 'mqtt',
  group: 'greenhouse-sensors',
  commands: [
    {
      name: 'read_environment',
      description: 'Read temperature, humidity, and soil moisture',
    },
    {
      name: 'toggle_irrigation',
      description: 'Turn irrigation on or off',
      inputSchema: {
        type: 'object',
        properties: {
          enabled: { type: 'boolean' },
        },
        required: ['enabled'],
      },
    },
  ],
});

let irrigationOn = false;

device.onCommand('read_environment', async () => {
  return {
    temperature: 28.3,
    humidity: 65,
    soilMoisture: 42,
    irrigationOn,
    timestamp: new Date().toISOString(),
  };
});

device.onCommand('toggle_irrigation', async (payload) => {
  irrigationOn = payload.enabled;
  return { irrigationOn };
});

async function main() {
  device.on('connected', () => console.log('Sensor online (MQTT)'));
  device.on('reconnected', () => console.log('Sensor reconnected'));
  device.on('error', (err) => console.error('MQTT error:', err));

  await device.connect();

  // Periodically check conditions and fire triggers
  setInterval(async () => {
    const humidity = 65 + Math.random() * 20;
    if (humidity > 80) {
      await device.trigger('humidity_alert', {
        humidity: Math.round(humidity),
        threshold: 80,
        sensor: 'greenhouse-sensor',
      });
    }
  }, 10000);
}

main().catch(console.error);

import asyncio
import os
import random
from datetime import datetime, timezone
from lua_device import DeviceClient, DeviceCommandDefinition

irrigation_on = False

client = DeviceClient(
    agent_id=os.environ["LUA_AGENT_ID"],
    api_key=os.environ["LUA_API_KEY"],
    device_name="greenhouse-sensor",
    transport="mqtt",
    group="greenhouse-sensors",
    commands=[
        DeviceCommandDefinition(
            name="read_environment",
            description="Read temperature, humidity, and soil moisture",
        ),
        DeviceCommandDefinition(
            name="toggle_irrigation",
            description="Turn irrigation on or off",
            input_schema={
                "type": "object",
                "properties": {
                    "enabled": {"type": "boolean"},
                },
                "required": ["enabled"],
            },
        ),
    ],
)

@client.on_command("read_environment")
async def handle_read_environment(payload):
    return {
        "temperature": 28.3,
        "humidity": 65,
        "soilMoisture": 42,
        "irrigationOn": irrigation_on,
        "timestamp": datetime.now(timezone.utc).isoformat(),
    }

@client.on_command("toggle_irrigation")
async def handle_toggle_irrigation(payload):
    global irrigation_on
    irrigation_on = payload["enabled"]
    return {"irrigationOn": irrigation_on}

async def main():
    await client.connect()
    print("Sensor online (MQTT)")

    # Periodically check conditions and fire triggers
    while True:
        humidity = 65 + random.random() * 20
        if humidity > 80:
            await client.trigger("humidity_alert", {
                "humidity": round(humidity),
                "threshold": 80,
                "sensor": "greenhouse-sensor",
            })
        await asyncio.sleep(10)

asyncio.run(main())

Next Steps

MicroPython Client

Run on a Raspberry Pi Pico W with native MQTT

Pico W Setup Guide

Step-by-step hardware setup with Thonny

Node.js Client

Socket.IO transport for full-featured Node.js devices

Architecture

Understand the full transport comparison

Getting Started

Device Client

Agent Integration

Examples

Advanced

CLI Commands

When to Use MQTT

Configuration

Node.js

Python

MicroPython

Topic Structure

Last Will and Testament (LWT)

QoS Levels

Authentication

Complete Example

Next Steps

MicroPython Client

Pico W Setup Guide

Node.js Client

Architecture

​When to Use MQTT

​Configuration

​Node.js

​Python

​MicroPython

​Topic Structure

​Last Will and Testament (LWT)

​QoS Levels

​Authentication

​Complete Example

​Next Steps

MicroPython Client

Pico W Setup Guide

Node.js Client

Architecture

When to Use MQTT

Configuration

Node.js

Python

MicroPython

Topic Structure

Last Will and Testament (LWT)

QoS Levels

Authentication

Complete Example

Next Steps