# SDK Access

SDK Access connects real hardware to a Device Agent. After the device-side program connects over MQTT, it can report state and events, respond to commands, and appear as a real device in the device list. `namespace` identifies the current runtime space; its default value is `default`.

## Choose an Access Path

Click **Connect device** in a Device Agent workspace. The console provides three entry points:

| Path | Best for |
| --- | --- |
| SDK toolkit | You need a runnable device-side project and will add hardware logic yourself |
| Agent-enhanced SDK | Generate device-side business logic on top of the SDK toolkit, then run or refine it |
| Existing device | You already have firmware, a gateway, or a backend service and only need to adapt it to MQTT topics and payloads |

The first two entry points produce device-side code packages. Existing device access does not generate code; it provides connection details and payload examples.

![Choose an SDK access path](../images/docs/device-access/sdk-generation/en/01-connect-device.png)

## SDK Toolkit

An SDK toolkit is a runnable device-side project. It already includes MQTT, device identity, command responses, state reports, and event reports. Real hardware logic is added in the device logic entry point.

File names vary by language, but the structure is consistent:

```text
SDK toolkit
├── .env.example        Connection settings: MQTT, namespace, productId, deviceId
├── device-spec.json    Current DeviceSpec: commands, telemetry, events
├── README.md           Setup, configuration, run, and development guide
├── src/
│   ├── main.*          Startup entry: load config and connect to MQTT
│   └── device.*        Business logic entry: handle commands, update state, emit events
├── Voice code           Connect device-side voice through /ws/voice
├── Vision code          Upload images and run photo recognition
└── SDK runtime layer    Subscribe to commands, send responses, report status, telemetry, events
```

`device-spec.json` is the source of truth for device-side implementation. Keep command names, parameter names, telemetry fields, and event fields aligned with it.

## Voice and Vision Code

SDK toolkits also include optional voice and vision code. Use it to connect microphones, speakers, cameras, or image sources on a real device to the Device Agent.

- **Voice**: the device opens a WebSocket connection to `/ws/voice`, sends 16 kHz mono Int16LE PCM audio, and receives ASR text, agent replies, and TTS audio.
- **Vision**: for photo recognition commands, the device captures one image, uploads it to `/api/vision/frames`, then calls `/api/chat` with the returned `visionRefs`.

`VOICE_CHAT_HOST` in `.env.example` is the shared host entry point for voice and vision APIs. Voice and vision do not replace MQTT device control; MQTT still handles commands, state, telemetry, and events.

| Language | Voice code | Vision code |
| --- | --- | --- |
| C | `voice_client.h`, `voice_client.c`, `examples/voice_chat.c` | `vision_client.h`, `vision_client.c` |
| Python | `src/voice_client.py` | Photo recognition command handling in `src/main.py` |
| Node.js | `VoiceClient` | `VisionClient` and `captureLocalVisionImage()` |

## Download an SDK Toolkit

When creating an SDK toolkit, confirm:

- **SDK language**: the console currently supports C, Node.js, and Python.
- **Device name**: used to identify the device in the console.
- **Device ID**: the unique identifier for this real device under the current Device Agent.

Start with the README to bring the device online, then replace the default logic with real sensors, actuators, or business service calls. The package keeps `device-spec.json`, `README.md`, and `.env.example`. Node.js toolkits also include `AGENTS.md`, `CLAUDE.md`, and device implementation guidance for Claude Code, Cursor, or Codex.

The usual flow is:

1. Unzip the package.
2. Configure connection settings from `.env.example`.
3. Install dependencies or build the project.
4. Start the device-side program.

After startup and the first state report, the device appears in the current Device Agent's device list.

See the language-specific SDK pages:

- [C SDK](./sdk-generation/c.md)
- [Python SDK](./sdk-generation/python.md)
- [Node.js SDK](./sdk-generation/nodejs.md)

## Use an Agent-Enhanced SDK

Use an Agent-enhanced SDK when device-side business logic has not been written yet. It starts from the SDK toolkit, then uses your description to generate state reporting, command handling, event triggers, and device-side flows.

You can provide:

- Device-side behavior, such as how to read sensors, control actuators, or emit alert events.
- Business requirements, such as reporting interval, threshold events, and how state should update after commands.
- Optional hardware context, such as chip, system, driver documentation links, interface docs, or protocol files.

![Enter device-side logic](../images/docs/device-access/sdk-generation/en/03-agent-enhanced-input.png)

After submission, the Device Agent returns a downloadable code package in the conversation. If the result needs adjustment, continue the conversation: add a driver call, change event trigger logic, or simplify telemetry reporting.

![Generated enhanced SDK package](../images/docs/device-access/sdk-generation/en/04-agent-enhanced-result.png)

## Connect an Existing Device

If firmware, a gateway, or a backend service already exists, choose **Existing device**. This entry point does not generate SDK code. It shows the MQTT broker, device identity, topics, and payload examples so your existing system can adapt directly.

Existing device access is about subscribing to commands, responding to commands, and reporting state and events over MQTT. See [MQTT Access](./mqtt.md) for the full guide.

## Run and Verify

After the device-side program starts, return to the Device Agent workspace and confirm:

1. The new real device appears in the device list.
2. The device is online.
3. Current state shows reported telemetry fields.
4. A conversation control request reaches the device and returns a result.
5. If the device emits events, recent events show the reported records.

![Device status after real device access](../images/docs/device-access/sdk-generation/en/02-device-status.png)

If the device does not appear, check whether the device-side program is connected to MQTT, whether `productId` and `deviceId` are correct, and whether it has reported status or telemetry. See [Configuration](../operate-reference/configuration.md) for related settings.

## Next Steps

- Read [MQTT Access](./mqtt.md) to adapt existing devices directly to topics and payloads.
- Read [Voice Interaction](../usage/voice.md) to connect device-side voice interaction.
- Read [Camera and Vision](../usage/multimedia.md) to connect cameras and image input.
- Read [Simulated Display](../usage/simulated-display.md) to validate visual device output.