Skip to main content
For the complete documentation index, see llms.txt.

Hubble Network developer documentation: integrate Bluetooth devices with terrestrial and satellite connectivity.

End Device Provisioning

This document outlines best practice approaches for securely provisioning an end device with a Hubble device ID and key, ensuring operational readiness and secure backend integration.

Provisioning Methods​

Provisioning can be accomplished through several mechanisms:

  1. Serial Interface: The device ID and key can be programmed via a physical serial connection (e.g., UART, USB-serial). This method is often used in manufacturing or lab environments for controlled provisioning.
  2. Over Bluetooth® Low Energy (BLE) with a Dedicated GATT Service: The end device hosts a provisioning GATT service that allows a provisioning tool (e.g., mobile app) to connect and write credentials. This service is advertised only in provisioning mode (to reduce attack surface).
  3. Pre-Merge into Firmware Image: Device ID and key can be embedded into a firmware image before flashing. This requires the firmware to read from a fixed memory location at runtime.

BLE Provisioning Workflow​

Advertising Mode​

  • A freshly programmed device should broadcast a connectable GATT service indicating it is awaiting a device ID and key.
  • Optionally, the device can remain in a non-connectable state until a button press triggers provisioning mode.

GATT Service Overview​

  • GATT (Generic Attribute Profile) defines how BLE devices exchange structured data.
  • A GATT service is a collection of characteristics (data items) and their properties (read, write, notify).
  • In provisioning mode, the device exposes characteristics for:
    • Reading the existing device ID/key (if present).
    • Writing new device ID/key values.

Mobile Device Role​

  • A provisioning-capable mobile app scans for the provisioning GATT service.
  • Upon connection:
    • It requests a new device ID/key pair from the backend.
    • It writes the pair to the device via the GATT service.
  • The mobile app must authenticate the user to ensure the device is provisioned into the correct organization.

Handling Devices with Existing Credentials​

A device may request provisioning even if credentials are already stored (e.g., after firmware reflashing). In such cases:

  • The app first reads the stored credentials.
  • The backend determines whether to keep or replace them.
    • This is called an update event.
    • Depending on policy, the device ID/key may remain unchanged or be replaced.