SDK Access

The SDK connects real hardware or device-side services to an existing device record over MQTT, using its device ID to come online, report state and events, and respond to commands. Use it when developing or changing device software; devices already working through an IoT platform can use IoT Platform Integration without a new client.

Choose an Access Path

Create or select a device record in the Device Agent workspace, then click its Download access package action. The console provides three device-side paths for that selected record:

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

The package belongs to the selected device and current model. IoT platforms can use different credentials, topics, and payloads. Use generated values rather than copying another adapter's configuration.

Download an SDK project

1. Select the target and confirm its name and identity.
2. Choose an offered language, such as C, Python, Node.js, or Bun.
3. Download, unzip, and read the included README.md.
4. Check the generated .env and confirm that addresses are reachable from the device environment.
5. Install dependencies or build, start the program, and return to the workspace to verify.

Packages may contain device credentials. Keep the generated .env. Copy .env.example only when .env is absent, then complete its settings. Devices use their own credentials; platform administration credentials stay on the server. Preserve the selected device's identity when changing connection addresses.

Understand the project files

File	Purpose
.env	Generated runtime configuration, potentially including device credentials
.env.example	Configuration reference without full sensitive credentials
runtime-model.json	Adapter capabilities, state, actions, and events parsed from the native model
device-spec.json	Read-only model projection used by generated code for validation and field mapping
README.md	Installation, startup, and development instructions for this language and adapter

Use runtime-model.json as the semantic source for device-side implementation. It contains the selected Provider, capabilities, reported and desired state, actions, events, Agent tools, and SDK support. Generated code reads device-spec.json as a deterministic compatibility projection; do not edit either file. Change capabilities in the native model, regenerate the project, and merge completed hardware code into the new project.

Use the model's exact action, parameter, state, and event identifiers and JSON types. Send numeric enum values as numbers, strings as strings, and booleans as true or false; display labels do not replace protocol values. For structures and arrays, preserve the native model's nested fields and item types. The adapter determines which constraints its SDK supports, so check the generated README before implementing validation or hardware calls.

Language	Main extension point	Environment
C	src/main.c	CMake, gateways, or embedded Linux
Python	src/main.py	uv, gateways, or existing Python services
Node.js	src/device.ts and initialization callbacks	npm, TypeScript, or JavaScript services
Bun	src/device.ts and initialization callbacks	Bun, TypeScript, or JavaScript services

Add real device logic

Establish connectivity and an initial report first, then replace example behavior:

• Actions: call drivers or business interfaces and return the actual result.
• Writable state: apply requested values to hardware and report actual state, where supported by the model and adapter.
• State reports: read sensors and actuators and use the generated reporting interfaces.
• Events: report modeled event data when an alert, button press, or business change occurs.

Keep model validation and request correlation. Simulated state changes validate interactions but do not prove hardware execution. Follow the generated README and code for each adapter's extension points.

Review the SDK's example behavior separately from the browser simulator. ThingsNeural packages include declared simulation effects in device-spec.json; SDK projects for devices managed directly by Device Agent and for Fleets use their own generated example handling. Replace example effects with hardware execution and actual reports before using the project for real control.

Use an Agent-enhanced SDK

Choose Agent for Toolkit 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.

Read and report temperature every 30 seconds. Use the existing control interface to set a target and report the actual value after success. Return an error on read failure instead of reporting simulated values.

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.

Connect an Existing Device

If firmware, a gateway, or a backend service already exists, choose Existing. 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.

Subscribe to commands, return command responses, and report state and events over MQTT. See MQTT Access for the full guide.

Voice and vision

Some projects provide voice or vision examples. Availability depends on the adapter, model, and package. Follow its README to connect microphones, speakers, or cameras, then see Voice Interaction and Camera and Vision.

Device data connectivity does not confirm voice or vision configuration. Verify service addresses, authentication, and input/output separately.

Run and verify

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

1. The same device record shows as online.
2. Its current connection is the device-side client, not a browser simulator session.
3. Current state shows reported property 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.

If the record does not come online, 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 for related settings. Disconnect simulation before starting a real client with the same identity.