Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.heylua.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Architecture Overview

The Device Gateway sits between your physical devices and the Lua agent runtime. It handles authentication, connection management, command routing, and trigger delivery.

​
Self-Describing Flow

When a device connects, it does not need any server-side configuration. The device tells the gateway what it can do, and the gateway tells the agent.
1

Device connects with command manifest

The device client sends its commands array during the Socket.IO auth handshake or MQTT online status message. Each command includes a name, description, and optional JSON Schema for input parameters.
2

Gateway registers device

The gateway validates the API key, registers the device, and stores the command manifest. The device appears as “online” to the agent.
3

Agent discovers tools

When the agent processes a user message, it queries connected devices and merges their commands into the tool list. Each device command appears as a tool named device__{deviceName}__{commandName}.
4

Device disconnects, tools disappear

When a device goes offline (intentional disconnect, network loss, or missed heartbeats), its tools are removed from the agent. No stale tools remain.

​
Command Delivery Path

When the agent decides to use a device tool, the command flows through the gateway: Each command carries a unique commandId for idempotency. If the device receives the same command twice (due to retry or redelivery), it returns the cached response.

​
Trigger Flow

Triggers go in the opposite direction — from device to agent:
Triggers are fire-and-forget from the device’s perspective. The device gets an acknowledgment that the gateway received the trigger, but does not wait for the agent to finish processing it.

​
Transport Comparison

FeatureSocket.IOMQTT
ProtocolWebSocket over HTTPSMQTT 3.1.1 over TLS
Default URLhttps://api.heylua.aiwss://mqtt.heylua.ai/mqtt
ReconnectionBuilt-in with jitterBuilt-in with backoff
Message orderingGuaranteed (single socket)Guaranteed per topic (QoS 1)
Offline queueingNoYes (persistent session)
Last Will (LWT)Not applicableAutomatic offline status on disconnect
Best forNode.js, desktops, serversMicrocontrollers, battery devices, flaky networks
RAM footprint~10 MB (Node.js)~30 KB (MicroPython on Pico W)

​
Security Model

API Key Authentication

Every device connection requires a valid API key. The key is validated against the Lua auth service during the connection handshake.

Agent Scoping

A device can only interact with the agent it authenticates against. Cross-agent communication is not possible.

TLS Encryption

All transports use TLS. Socket.IO connects over HTTPS. MQTT connects over port 443 (WebSocket) with TLS.

Heartbeat Monitoring

The gateway expects a heartbeat every 30 seconds. Missed heartbeats trigger disconnect detection. MQTT additionally uses Last Will and Testament (LWT) for instant offline notification.

​
Connection Lifecycle

1. Client opens WebSocket to https://api.heylua.ai/devices
2. Auth handshake: { apiKey, agentId, deviceName, commands[] }
3. Server validates, emits 'connected'
4. Client starts heartbeat (every 30s)
5. Bidirectional command/trigger exchange
6. On disconnect: auto-reconnect with jittered exponential backoff
7. On reconnect: re-sends auth (commands may have changed)
8. On SIGTERM/SIGINT: graceful disconnect, no reconnect

​
Next Steps

Self-Describing Commands

Deep dive into how devices declare their capabilities

Triggers

Understand device-to-agent event flow

MQTT Transport

Configure MQTT for constrained devices

Agent Tools

How device commands become agent tools