@lua-ai-global/device-client

Connect physical devices to Lua AI agents via WebSocket or MQTT.

Install

npm install @lua-ai-global/device-client

Quick Start

Create a device credential with a renewable first-party session. The server binds the secret to the exact agent, device name, and selected operations:

curl -X POST https://api.heylua.ai/admin/users/me/credentials/device \
  -H "Authorization: Bearer $LUA_FIREBASE_SESSION" \
  -H "Content-Type: application/json" \
  -H "X-Lua-Client: web/unversioned" \
  -d '{"agentId":"baseAgent_agent_abc123","deviceName":"warehouse-scanner","operations":["commands","triggers","assets.upload"]}'

Save the returned secret once. It is not returned by later list calls.

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

const device = new DeviceClient({
  agentId: 'baseAgent_agent_abc123',
  deviceCredential: 'api_your_device_credential_here',
  deviceName: 'warehouse-scanner',
  commands: [
    { name: 'scan_barcode', description: 'Scan a barcode and return its value' },
    { name: 'get_status', description: 'Return device battery and connectivity status' },
  ],
});

// Register command handlers
device.onCommand('scan_barcode', async (payload) => {
  const result = await scanner.read();
  return { barcode: result.value, format: result.format };
});

device.onCommand('get_status', async () => {
  return { battery: 85, signal: 'strong' };
});

// Connect and start listening
await device.connect();
console.log('Device connected!');

// Fire a trigger to the agent
await device.trigger('barcode_scanned', { value: 'ABC-12345' });

Features

• Self-describing commands -- no server config needed, commands are sent at connect time
• Dual transport -- Socket.IO (default) + MQTT for constrained devices
• CDN uploads -- upload screenshots, files, and logs via device.cdn.upload()
• Device triggers -- fire events from device to agent
• Safe reconnection -- exponential backoff with jitter, terminal stop on rejected credentials, and server-directed rate-limit backoff
• MicroPython support -- lightweight client for Raspberry Pi Pico W

MQTT Transport

For constrained devices or environments where WebSocket is not available:

const device = new DeviceClient({
  agentId: 'baseAgent_agent_abc123',
  deviceCredential: 'api_your_device_credential_here',
  deviceName: 'pico-sensor',
  transport: 'mqtt',
  mqttUrl: 'mqtts://mqtt.heylua.ai:8883',
  commands: [{ name: 'read_temperature', description: 'Read current temperature in celsius' }],
});

Authentication lifecycle

deviceCredential is the default for new provisioning. The existing apiKey option remains supported indefinitely for devices that already use a non-dotted legacy key; the client never rewrites or revokes it.

Typed MQTT status messages do not contain the secret. The secret is sent only as the MQTT CONNECT password. Socket.IO sends it only in the handshake auth.apiKey slot. Both transports keep their existing wire field for compatibility.

For Socket.IO devices, AUTH_FAILED and MISSING_AUTH are terminal: the client disables reconnection and rejects an initial connect() attempt. Replace the credential and create a new client rather than retrying a key the gateway has rejected. RATE_LIMITED remains retryable and honors the gateway's advertised retry delay, with a 30-second fallback for older servers.

The client sends bounded device-node/<package version> attribution automatically. clientVersion remains available to stamp a packaged downstream build; attribution is never used for authorization and never includes a device name or credential.

Documentation

Full documentation, examples, and protocol reference: https://docs.heylua.ai/devices

License

MIT