> ## 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.

# Devices

> Connect physical hardware to your AI agent for bidirectional real-time control

## What are Devices?

**Devices** are physical hardware -- sensors, scanners, displays, controllers -- that connect directly to your AI agent over the internet. When a device connects, it tells the agent what commands it supports. Those commands instantly become tools the agent can use. No compile, no push, no middleware.

<Card title="Think of it as:" icon="satellite-dish">
  A remote control for your agent to reach into the physical world -- send commands to hardware, receive sensor data back, all in real time
</Card>

## How It Works

<Steps>
  <Step title="Device connects">
    A device client (Node.js or MicroPython) opens a persistent connection to the Lua gateway and declares its capabilities.
  </Step>

  <Step title="Agent gets tools">
    Each device command becomes a tool the agent can call, just like skill tools.
  </Step>

  <Step title="Bidirectional communication">
    The agent sends commands to devices. Devices fire triggers back to the agent. Both directions are instant.
  </Step>
</Steps>

## Key Features

<CardGroup cols={2}>
  <Card title="Self-Describing" icon="list-check">
    Devices declare their commands at connect time. No server-side schema to maintain.
  </Card>

  <Card title="Two Transports" icon="arrows-left-right">
    Socket.IO for Node.js devices. MQTT for microcontrollers and constrained hardware.
  </Card>

  <Card title="Triggers" icon="bolt">
    Devices push events to the agent (e.g., "temperature exceeded threshold") with server-side handler logic.
  </Card>

  <Card title="Runs on Pico W" icon="microchip">
    The MicroPython client fits on a Raspberry Pi Pico W with 264KB of RAM.
  </Card>
</CardGroup>

## Quick Example

```typescript theme={null}
import { DeviceClient } from '@lua-ai-global/device-client';

const device = new DeviceClient({
  agentId: 'your-agent-id',
  apiKey: 'your-api-key',
  deviceName: 'temp-sensor',
  commands: [
    { name: 'read_temperature', description: 'Read current temperature in celsius' },
  ],
});

device.onCommand('read_temperature', async () => {
  return { temperature: 22.5, unit: 'celsius' };
});

await device.connect();
```

The agent can now say: "The temperature is 22.5 degrees celsius" when a user asks.

## Learn More

<CardGroup cols={2}>
  <Card title="Devices Overview" icon="book" href="/devices/overview">
    Full introduction to the Device Gateway
  </Card>

  <Card title="5-Minute Quickstart" icon="rocket" href="/devices/quickstart">
    Connect your first device
  </Card>

  <Card title="Node.js Client" icon="node-js" href="/devices/node-client">
    Complete Node.js device client reference
  </Card>

  <Card title="MicroPython Client" icon="microchip" href="/devices/micropython-client">
    Run on a Raspberry Pi Pico W
  </Card>

  <Card title="Examples" icon="layer-group" href="/devices/examples/warehouse-inventory">
    Full working examples across industries
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/devices/how-it-works">
    How commands and triggers flow through the system
  </Card>
</CardGroup>