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

# 5-Minute Quickstart

> Connect your first device to a Lua agent in under 5 minutes

## Connect Your First Device

Get a device connected and responding to agent commands in five steps.

<Steps>
  <Step title="Install the device client">
    <CodeGroup>
      ```bash npm theme={null}
      npm install @lua-ai-global/device-client
      ```

      ```bash yarn theme={null}
      yarn add @lua-ai-global/device-client
      ```

      ```bash pnpm theme={null}
      pnpm add @lua-ai-global/device-client
      ```

      ```bash pip theme={null}
      pip install lua-device-client
      ```
    </CodeGroup>
  </Step>

  <Step title="Create a device client">
    Create a file called `device.ts` (or `device.py`) and configure the client with your agent credentials:

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

      const device = new DeviceClient({
        agentId: 'your-agent-id',
        apiKey: 'your-api-key',
        deviceName: 'my-first-device',
        commands: [
          {
            name: 'ping',
            description: 'Check if the device is alive',
          },
          {
            name: 'read_sensor',
            description: 'Read the current temperature in celsius',
            inputSchema: {
              type: 'object',
              properties: {
                unit: { type: 'string', enum: ['celsius', 'fahrenheit'], default: 'celsius' },
              },
            },
          },
        ],
      });
      ```

      ```python Python theme={null}
      from lua_device import DeviceClient, DeviceCommandDefinition

      client = DeviceClient(
          agent_id="your-agent-id",
          api_key="your-api-key",
          device_name="my-first-device",
          commands=[
              DeviceCommandDefinition(
                  name="ping",
                  description="Check if the device is alive",
              ),
              DeviceCommandDefinition(
                  name="read_sensor",
                  description="Read the current temperature in celsius",
                  input_schema={
                      "type": "object",
                      "properties": {
                          "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"},
                      },
                  },
              ),
          ],
      )
      ```
    </CodeGroup>

    <Note>
      Find your `agentId` and `apiKey` in `.lua/lua.config.yaml` after running `lua init`, or in the [Lua dashboard](https://admin.heylua.ai).
    </Note>
  </Step>

  <Step title="Register command handlers">
    Tell the device what to do when the agent sends each command:

    <CodeGroup>
      ```typescript TypeScript theme={null}
      device.onCommand('ping', async () => {
        return { status: 'ok', timestamp: new Date().toISOString() };
      });

      device.onCommand('read_sensor', async (payload) => {
        // In a real device, read from hardware here
        const tempCelsius = 22.5;
        const temp = payload?.unit === 'fahrenheit'
          ? (tempCelsius * 9/5) + 32
          : tempCelsius;

        return { temperature: temp, unit: payload?.unit || 'celsius' };
      });
      ```

      ```python Python theme={null}
      from datetime import datetime, timezone

      @client.on_command("ping")
      async def handle_ping(payload):
          return {"status": "ok", "timestamp": datetime.now(timezone.utc).isoformat()}

      @client.on_command("read_sensor")
      async def handle_read_sensor(payload):
          # In a real device, read from hardware here
          temp_celsius = 22.5
          unit = (payload or {}).get("unit", "celsius")
          temp = (temp_celsius * 9 / 5) + 32 if unit == "fahrenheit" else temp_celsius
          return {"temperature": temp, "unit": unit}
      ```
    </CodeGroup>
  </Step>

  <Step title="Connect">
    <CodeGroup>
      ```typescript TypeScript theme={null}
      async function main() {
        await device.connect();
        console.log('Device connected and ready for commands');
      }

      main().catch(console.error);
      ```

      ```python Python theme={null}
      import asyncio

      async def main():
          await client.connect()
          print("Device connected and ready for commands")

      asyncio.run(main())
      ```
    </CodeGroup>

    Run your device:

    <CodeGroup>
      ```bash TypeScript theme={null}
      npx tsx device.ts
      ```

      ```bash Python theme={null}
      python device.py
      ```
    </CodeGroup>

    You should see:

    ```
    Device connected and ready for commands
    ```
  </Step>

  <Step title="Test with lua chat">
    In another terminal, start a chat session with your agent:

    ```bash theme={null}
    lua chat
    ```

    Try saying:

    ```
    > Ping my-first-device
    > What's the temperature reading from my-first-device?
    > Read the sensor in fahrenheit
    ```

    The agent will use the device tools to send commands and return the results.
  </Step>
</Steps>

<Note>
  **No compile or push needed.** Your device declared its commands at connect time. The agent already has tools for them. Change the commands array, restart the device, and the agent sees the new tools instantly.
</Note>

## Complete Working Example

Here is the full file in one piece:

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

  const device = new DeviceClient({
    agentId: 'your-agent-id',
    apiKey: 'your-api-key',
    deviceName: 'my-first-device',
    commands: [
      {
        name: 'ping',
        description: 'Check if the device is alive',
      },
      {
        name: 'read_sensor',
        description: 'Read the current temperature in celsius',
        inputSchema: {
          type: 'object',
          properties: {
            unit: { type: 'string', enum: ['celsius', 'fahrenheit'], default: 'celsius' },
          },
        },
      },
    ],
  });

  device.onCommand('ping', async () => {
    return { status: 'ok', timestamp: new Date().toISOString() };
  });

  device.onCommand('read_sensor', async (payload) => {
    const tempCelsius = 22.5;
    const temp = payload?.unit === 'fahrenheit'
      ? (tempCelsius * 9/5) + 32
      : tempCelsius;
    return { temperature: temp, unit: payload?.unit || 'celsius' };
  });

  async function main() {
    await device.connect();
    console.log('Device connected and ready for commands');
  }

  main().catch(console.error);
  ```

  ```python Python theme={null}
  import asyncio
  from datetime import datetime, timezone
  from lua_device import DeviceClient, DeviceCommandDefinition

  client = DeviceClient(
      agent_id="your-agent-id",
      api_key="your-api-key",
      device_name="my-first-device",
      commands=[
          DeviceCommandDefinition(
              name="ping",
              description="Check if the device is alive",
          ),
          DeviceCommandDefinition(
              name="read_sensor",
              description="Read the current temperature in celsius",
              input_schema={
                  "type": "object",
                  "properties": {
                      "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius"},
                  },
              },
          ),
      ],
  )

  @client.on_command("ping")
  async def handle_ping(payload):
      return {"status": "ok", "timestamp": datetime.now(timezone.utc).isoformat()}

  @client.on_command("read_sensor")
  async def handle_read_sensor(payload):
      temp_celsius = 22.5
      unit = (payload or {}).get("unit", "celsius")
      temp = (temp_celsius * 9 / 5) + 32 if unit == "fahrenheit" else temp_celsius
      return {"temperature": temp, "unit": unit}

  async def main():
      await client.connect()
      print("Device connected and ready for commands")

  asyncio.run(main())
  ```
</CodeGroup>

## Next Steps

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

  <Card title="Self-Describing Commands" icon="list-check" href="/devices/self-describing-commands">
    Learn how devices declare their capabilities
  </Card>

  <Card title="Triggers" icon="bolt" href="/devices/triggers">
    Let your device push events to the agent
  </Card>

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