Skip to main content

​
DeviceClient

The main class for connecting a device to a Lua AI agent. Extends EventEmitter. 
import { DeviceClient } from '@lua-ai/device-client';

const client = new DeviceClient(config: DeviceClientConfig);

​
Constructor

​
config
DeviceClientConfig
required
Configuration object for the device client. See DeviceClientConfig below.

​
DeviceClientConfig

​
agentId
string
required
Agent ID to connect to.
​
apiKey
string
required
API key for authentication.
​
deviceName
string
required
Unique name for this device. Lowercase with hyphens.
​
commands
DeviceCommandDefinition[]
Commands this device supports. Sent to the server at connect time.
​
transport
'socketio' | 'mqtt'
default:"socketio"
Transport protocol.
​
serverUrl
string
default:"https://api.heylua.ai"
Server URL for Socket.IO transport.
​
mqttUrl
string
default:"mqtts://mqtt.heylua.ai:8883"
MQTT broker URL. Required when transport is 'mqtt'.
​
cdnUrl
string
default:"https://cdn.heylua.ai"
CDN URL for file uploads and downloads.
​
group
string
Optional device group name.

​
Methods

​
connect()

Connect to the device gateway. Resolves when the connection is established and authenticated. Automatically reconnects on disconnect unless disconnect() was called. 
await client.connect(): Promise<void>

​
disconnect()

Disconnect from the device gateway. Stops auto-reconnection. 
await client.disconnect(): Promise<void>

​
isConnected()

Check if the client is currently connected. 
client.isConnected(): boolean

​
onCommand()

Register a handler for a specific command name. The handler receives the command payload and must return a result (or throw an error). 
client.onCommand(name: string, handler: CommandHandler): void
​
name
string
required
Command name to handle.
​
handler
(payload: any) => Promise<any>
required
Async function that executes the command. Return value is sent back to the agent. Thrown errors are sent as error responses.
client.onCommand('read_temperature', async (payload) => {
  return { temperature: 22.5, unit: 'celsius' };
});

​
trigger()

Fire a trigger event to the agent. Resolves when the server acknowledges receipt (not execution completion). 
await client.trigger(name: string, payload: any): Promise<DeviceTriggerAckMessage>
​
name
string
required
Trigger name.
​
payload
any
required
Trigger payload data.
await client.trigger('temperature_alert', {
  temperature: 42.1,
  threshold: 40,
});

​
onTriggerResult()

Listen for trigger execution results from the agent. Optional — triggers are fire-and-forget by default. 
client.onTriggerResult(name: string, handler: TriggerResultHandler): void
​
name
string
required
Trigger name to listen for.
​
handler
(result: any) => void
required
Callback function receiving the trigger execution result.

​
Properties

​
cdn

CDN client for uploading and downloading files. Available immediately after construction. 
client.cdn: CDN

​
CDN

The CDN class provides file upload and download capabilities.

​
cdn.upload()

Upload a file to the Lua CDN. 
await client.cdn.upload(
  data: Buffer | Blob,
  filename: string,
  contentType?: string
): Promise<CdnUploadResult>
​
data
Buffer | Blob
required
File content.
​
filename
string
required
Filename with extension.
​
contentType
string
MIME type. Defaults to application/octet-stream.
Returns: CdnUploadResult 
interface CdnUploadResult {
  fileId: string;
  mediaType: string;
  extension: string;
  url: string;
}

​
cdn.download()

Download a file from the CDN. 
await client.cdn.download(fileId: string): Promise<Buffer>

​
cdn.getUrl()

Get the public URL for a file. 
client.cdn.getUrl(fileId: string): string

​
Events

The DeviceClient extends EventEmitter and emits the following events:
EventPayloadDescription
connected(none)Initial connection established
reconnected(none)Reconnected after a disconnect
disconnectedreason: stringConnection lost
errorerror: anyConnection or protocol error
trigger_ackDeviceTriggerAckMessageServer acknowledged a trigger
trigger_errorerror: anyTrigger delivery error
client.on('connected', () => console.log('Online'));
client.on('disconnected', (reason) => console.log('Offline:', reason));
client.on('error', (err) => console.error('Error:', err));

​
DeviceCommandDefinition

Describes a command the device supports.
​
name
string
required
Command name.
​
description
string
required
Human-readable description shown to the AI agent.
​
inputSchema
Record<string, any>
JSON Schema for input parameters.
​
timeoutMs
number
default:"30000"
Command timeout in milliseconds.
​
retry
{ maxAttempts: number; backoffMs: number }
Retry configuration for failed commands.

​
Type Exports

The package exports the following types: 
import type {
  DeviceClientConfig,
  DeviceCommandDefinition,
  DeviceCommandMessage,
  DeviceResponseMessage,
  DeviceTriggerAckMessage,
  CommandHandler,
  TriggerResultHandler,
} from '@lua-ai/device-client';

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

​
Next Steps

Node.js Client Guide

Usage guide with examples

MicroPython Client

API reference for the MicroPython client

Quickstart

Get started in 5 minutes

Examples

Full working examples