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

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

Onboard Your Devices

Register a new device to your Hubble organization to create a secret key. Store that key on your Bluetooth® capable device and use the Device SDK to start beaconing on Hubble Network.

Register New Devices​

For your device to be discoverable by Hubble Network, you need to first register a new device to your Hubble organization. (If you don't already have a Hubble Dashboard, you can sign up for one now.)

  • Generate a key directly in Dash using the "Add a Device" flow. Click "I just need a device key" and select your device encryption mode.
  • Or use the Cloud API to Register New Devices. Generate an API token and copy your Org ID from your Hubble Dashboard to call the API.

Try It: jump straight into Dash Quick Start. We handle device registration for you and help you flash a developer kit in minutes.

How It Works​

When you register a device you must specify the device encryption mode, based on your hardware's time-keeping capabilities and the encryption library you use in your firmware (see Device Security).

You may also provide device metadata that makes it easier to manage your devices in the Hubble Dashboard and through your backend integration.

Set Encryption Mode​

The Hubble Device SDK rotates through ephemeral IDs (EID) so that devices remain anonymous on the network. Learn more about encryption on the Device Security guide.

You must specify device encryption mode when you register a new device. These parameters factor into security on the network:

  • Key Size (256-bit or 128-bit)
  • Counter Source for EID Rotation (unix time or device uptime)
  • Only for InPlay IN100: Period Exponent (optional rotation period configuration)

Make sure to match encryption parameters against your firmware requirement when registering new devices, to avoid needing to reprovision your devices with a new key.

Encryption configurations are fixed for a device upon registration. They cannot be modified on the Hubble backend for an existing device.

Key Size​

Hubble supports Advanced Encryption Standard (AES) 256-bit keys (32 bytes) (recommended) and 128-bit keys (16 bytes). Select which key size is compatible with your firmware cryptographic library.

The API returns device key as base64 encoded string of raw binary data (16 or 32 bytes).

Counter Source​

You may choose between unix time for EID rotation (requires devices to maintain an accurate, synchronized clock) or device uptime, which does not require a real-time clock. Unix time is recommended for maximum privacy. When using device uptime as your counter source, EIDs rotate through a preset pool size of 128.

Period Exponent (IN100)​

When using the AES-128-EAX protocol with "DEVICE UPTIME" counter source for IN100, you can optionally override the EID rotation frequency using the period_exponent.

  • The rotation period is calculated as 2^n seconds, where n is the period_exponent.
  • For example, using the default value of 15, the period is 32,768 seconds (~9 hours).

Set Metadata​

You can optionally provide a custom name and custom tag(s) for each device at the time it is registered.

  • Use name parameter to assign a proprietary device ID to your device (uniqueness is not enforced by Hubble). For example, use this field for your UUID or device serial number.
  • Use tags to organize devices into your "sandbox" or "production" environment (these are mutually exclusive platform tags). Or create custom tags with unique key:value pairs to organize your devices and device data.

As a best practice, do not use any personally identifiable information (PII) in the device name or custom tags.

Bulk Registration Flow​

Request to provision keys for more than one device a time using the n_device parameter. You may register up to 10,000 devices per day.

When registering multiple devices, provide an array of names and/or tags in the request body. Names and tags are drawn down sequentially from both arrays and assigned to the next device that is registered.

Device registration is eventually consistent: when registering at scale, there may be a brief propogation delay between creation and the first successful packet decrypt.

Update Devices​

Manage names and tags for existing devices, either individually or in batch sets. Just like when you register multiple devices, provide an array of device names and/or tags in the request body when updating multiple devices.

Go further: Review Update Device and Batch Update Devices for example HTTP requests, parameter definitions and response bodies.

Delete Devices​

You may permanently delete a specific device or multiple devices from your organization. This action is not reversible. Data packets will no longer be delivered for deleted devices even if they continue to broadcast on the network.

Each delete request is idempotent. In the event of an internal error (i.e. 5xx) for a batch delete request, some deletions may be applied and others may not. The whole request can be retried again to ensure a consistent deletion across the batch.