@lua-ai/device-client

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

Install

npm install @lua-ai/device-client

Quick Start

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

const device = new DeviceClient({
  agentId: 'baseAgent_agent_abc123',
  apiKey: 'api_your_key_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
• Auto-reconnection -- exponential backoff with jitter
• 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',
  apiKey: 'api_your_key_here',
  deviceName: 'pico-sensor',
  transport: 'mqtt',
  mqttUrl: 'mqtts://mqtt.heylua.ai:8883',
  commands: [
    { name: 'read_temperature', description: 'Read current temperature in celsius' },
  ],
});

Documentation

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

License

MIT