Get started with a device

Choose an SDK

Target

SDK directory

Use it for

Python 3

sdks/python/

reference integrations, Linux devices, and test automation

Android/Kotlin

sdks/android/

Android-based terminals and controllers

C11

sdks/fgai-mqtt-c/

embedded Linux, native controllers, and factory bootstrap software

Emulator

emulator/

repeatable virtual-device and failure scenarios

All SDKs use the same DDI-1 identity, HTTPS, MQTT, and OTA boundaries. Do not combine separate legacy device and Bazaar OTA clients. DDI is the sole terminal integration product; HawkBit compatibility is reached only through the DDI OTA prefix.

Integration sequence

  1. Configure https://things.flexgalaxy.ai as the HTTPS base URL and things.flexgalaxy.ai:8883 as the MQTT endpoint. Keep these settings configurable for customer-hosted deployments.

  2. Load the approved server trust anchors and the factory-issued bootstrap credential.

  3. Generate the production private key on the device, preferably in a TPM or secure element.

  4. Call POST /ddi/v1/identify, then POST /ddi/v1/provision with a CSR.

  5. Persist the returned leaf certificate and CA chain atomically. Delete the bootstrap credential after provisioning succeeds.

  6. Connect to MQTT 5 with mTLS, use the returned thing_id as the MQTT identity, and publish only to the documented device topics.

  7. Register inbound callbacks before connecting, then publish telemetry and the device-owned CLIENT attribute snapshot.

  8. Poll /ddi/v1/ota/ with the same device certificate when the product supports OTA.

Copy one of the repository’s minimal examples first, then adopt the robust example for production retry, persistence, and error handling. Never log the bootstrap bearer, enrollment token, private key, or raw authorization headers.

First operational session

The Python binding is the smallest executable reference. Install it from an authorized checkout:

python -m pip install ./sdks/python

After provisioning has persisted device.crt, device.key, and ca.crt, load the returned identity and register inbound handlers before connect():

from fgai_mqtt import FGAIDeviceClient, ProvisionedIdentity
from fgai_mqtt._proto import command_pb2

identity = ProvisionedIdentity(
    thing_id="<identify-issued thing_id>",
    cert_path="certs/device.crt",
    key_path="certs/device.key",
    ca_path="certs/ca.crt",
    mqtt_host="things.flexgalaxy.ai",
    mqtt_port=8883,
)
device = FGAIDeviceClient(identity.device_config())

device.set_shared_attribute_callback(lambda key, value: apply_setting(key, value))
device.set_command_callback(
    lambda command, respond: respond(
        status=command_pb2.COMMAND_STATUS_SUCCEEDED,
        result=b"ok",
        error=None,
    )
)
device.connect()
device.publish_telemetry({"temperature": 22.5}, tags={"site": "factory-a"})
device.report_client_attribute({"firmware_version": "1.0.0"})

apply_setting is application code: apply and persist the requested shared attribute before returning. The SDK then acknowledges it. See Device operations for the Android/Kotlin and C forms and for the managed-runtime status of each operation.

Retry rules

  • Retry transport failures, 408, 429, and 5xx with exponential backoff and full jitter.

  • Honor Retry-After when present.

  • Do not retry other 4xx responses without correcting the request or identity.

  • Treat DDI-1-403-IDENTITY-BLACKLISTED as terminal.

  • Reconnect MQTT with backoff and republish the client-attribute snapshot after a successful reconnect.

Manufacturing boundary

The SDK provisioning flow is not a replacement for the factory bootstrap process. A bootstrap mini-OS may first read the hardware descriptor, enroll through DDI, and use the DDI OTA route to obtain an assigned artifact. See the repository’s docs/factory-bootstrap-flow.md for the complete sequence.