DeviceClient API

DeviceClient

The main class for connecting a device to a Lua AI agent. Extends EventEmitter.

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

const client = new DeviceClient(config: DeviceClientConfig);

Constructor

DeviceClientConfig

required

Configuration object for the device client. See DeviceClientConfig below.

DeviceClientConfig

At least one credential field, deviceCredential or apiKey, is required.

string

required

Agent ID to connect to.

string

Device credential for new provisioning. See Device credentials.

string

Existing compatibility field, supported indefinitely. Non-dotted legacy keys also remain valid indefinitely.

string

required

Unique name for this device. Lowercase with hyphens.

DeviceCommandDefinition[]

Commands this device supports. Sent to the server at connect time.

'socketio' | 'mqtt'

default:"socketio"

Transport protocol.

string

default:"https://api.heylua.ai"

Server URL for Socket.IO transport.

string

default:"wss://mqtt.heylua.ai/mqtt"

MQTT broker URL. Required when transport is 'mqtt'.

string

default:"https://cdn.heylua.ai"

CDN URL for file uploads and downloads.

string

Optional device group name.

Provide either credential field. If you provide both, their values must match.

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

string

required

Command name to handle.

(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>

string

required

Trigger name.

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

string

required

Trigger name to listen for.

(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>

Buffer | Blob

required

File content.

string

required

Filename with extension.

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:

Event	Payload	Description
`connected`	(none)	Initial connection established
`reconnected`	(none)	Reconnected after a disconnect
`disconnected`	`reason: string`	Connection lost
`error`	`error: any`	Connection or protocol error
`trigger_ack`	`DeviceTriggerAckMessage`	Server acknowledged a trigger
`trigger_error`	`error: any`	Trigger 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.

string

required

Command name.

string

required

Human-readable description shown to the AI agent.

Record<string, any>

JSON Schema for input parameters.

number

default:"30000"

Command timeout in milliseconds.

{ 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-global/device-client';

import type { CdnUploadResult } from '@lua-ai-global/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

Getting Started

Device Client

Agent Integration

Examples

Advanced

CLI Commands

DeviceClient API

DeviceClient

Constructor

DeviceClientConfig

Methods

connect()

disconnect()

isConnected()

onCommand()

trigger()

onTriggerResult()

Properties

cdn

CDN

cdn.upload()

cdn.download()

cdn.getUrl()

Events

DeviceCommandDefinition

Type Exports

Next Steps

Node.js Client Guide

MicroPython Client

Quickstart

Examples

​DeviceClient

​Constructor

​DeviceClientConfig

​Methods

​connect()

​disconnect()

​isConnected()

​onCommand()

​trigger()

​onTriggerResult()

​Properties

​cdn

​CDN

​cdn.upload()

​cdn.download()

​cdn.getUrl()

​Events

​DeviceCommandDefinition

​Type Exports

​Next Steps

Node.js Client Guide

MicroPython Client

Quickstart

Examples

DeviceClient

Constructor

DeviceClientConfig

Methods

connect()

disconnect()

isConnected()

onCommand()

trigger()

onTriggerResult()

Properties

cdn

CDN

cdn.upload()

cdn.download()

cdn.getUrl()

Events

DeviceCommandDefinition

Type Exports

Next Steps