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

# What are Devices?

> Give your AI agent a remote control for the physical world

## What are Devices?

**Devices** let your AI agent reach beyond the cloud and into the physical world. A device is any hardware -- a barcode scanner, a temperature sensor, a kiosk display -- that connects to your agent over the internet and exchanges commands and triggers in real time.

<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, no middleware required
</Card>

<Note>
  **No compile or push needed.** Devices are self-describing. When a device connects, it tells the agent what commands it supports. Those commands instantly become tools the agent can use. Disconnect the device and the tools disappear.
</Note>

## Why Devices?

<CardGroup cols={2}>
  <Card title="Real-Time Bidirectional" icon="arrows-left-right">
    Agent sends commands to devices. Devices fire triggers back to the agent. Both directions are instant over persistent connections.
  </Card>

  <Card title="No Middleware" icon="diagram-project">
    Devices connect directly to the agent gateway. No cron jobs, no polling APIs, no message queues to maintain.
  </Card>

  <Card title="Self-Describing Commands" icon="list-check">
    Devices declare their capabilities at connect time. The agent automatically gets tools for every command the device supports.
  </Card>

  <Card title="Runs on a Pico W" icon="microchip">
    The MicroPython client fits on a Raspberry Pi Pico W with 264KB of RAM. Full MQTT support, command handling, and triggers.
  </Card>
</CardGroup>

## Before and After

<Tabs>
  <Tab title="Before: Traditional IoT">
    ```
    Device  -->  MQTT Broker  -->  Middleware API  -->  Cron Job  -->  Agent
                                        |
                                   Database (polling)
                                        |
                                   Dashboard (manual)
    ```

    * Multiple systems to maintain
    * Polling delays (seconds to minutes)
    * Custom glue code for every device type
    * Agent has no direct control
  </Tab>

  <Tab title="After: Lua Device Gateway">
    ```
    Device  <-->  Agent
    ```

    * One persistent connection
    * Sub-second latency
    * Device describes itself -- no glue code
    * Agent sends commands and receives triggers directly
  </Tab>
</Tabs>

## Supported Transports

| Transport     | Best For                                                       | Protocol             | Library                                                                                               |
| ------------- | -------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------- |
| **Socket.IO** | Node.js devices, desktops, servers                             | WebSocket over HTTPS | `@lua-ai-global/device-client` (npm) or `lua-device-client` (pip)                                     |
| **MQTT**      | Microcontrollers, constrained devices, battery-powered sensors | MQTT 3.1.1 over TLS  | `@lua-ai-global/device-client` (Node), `lua-device-client` (Python), or `lua_device.py` (MicroPython) |

Both transports support the full feature set: commands, triggers, heartbeats, reconnection, and CDN uploads.

## What Can You Build?

<CardGroup cols={2}>
  <Card title="Warehouse Monitoring" icon="warehouse" href="/devices/examples/warehouse-inventory">
    Barcode scanners, weight sensors, gate controllers. Agent manages inventory in real time.
  </Card>

  <Card title="Smart Office" icon="building" href="/devices/examples/smart-office">
    Meeting room sensors, thermostats, desk occupancy. Agent acts as a facilities concierge.
  </Card>

  <Card title="Industrial IoT" icon="industry" href="/devices/examples/industrial-sensor">
    Vibration sensors, temperature probes, emergency stop buttons. Agent monitors factory health on a Pico W.
  </Card>

  <Card title="Retail Kiosks" icon="store" href="/devices/examples/retail-kiosk">
    Receipt printers, NFC readers, display screens. Agent powers customer-facing interactions.
  </Card>

  <Card title="Agriculture" icon="seedling">
    Soil moisture sensors, irrigation valves, weather stations. Agent optimizes crop management.
  </Card>

  <Card title="Your Hardware" icon="microchip">
    Any device that runs Node.js or MicroPython. If it can open a socket, it can talk to your agent.
  </Card>
</CardGroup>

## How It Works (30 Seconds)

<Steps>
  <Step title="Device connects">
    Your device opens a Socket.IO or MQTT connection to the Lua gateway and sends a list of commands it supports.
  </Step>

  <Step title="Agent gets tools">
    Each command becomes a tool the agent can call. The agent sees them just like any other skill tool.
  </Step>

  <Step title="Users talk to the agent">
    A user says "scan the next barcode". The agent picks the right device tool and sends the command.
  </Step>

  <Step title="Device responds">
    The device executes the command and returns the result. The agent uses the result in its response to the user.
  </Step>

  <Step title="Device fires triggers">
    The device can also push events to the agent -- "temperature exceeded 40C" -- which run server-side logic.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="5-Minute Quickstart" icon="rocket" href="/devices/quickstart">
    Connect your first device in under 5 minutes
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/devices/how-it-works">
    Understand the full command and trigger flow
  </Card>

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

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