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

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

Control when devices go live

Register devices as not yet live while you test, store, or ship them, then go live when they're ready. Until then, the Live Network doesn't deliver their packets.

Go Live Control is limited to enterprise accounts. Contact Hubble Sales to get it added to your plan.

Overview​

Devices are often provisioned some time before they start doing their job. For example, devices provisioned at the factory may spend weeks in shipping before they are put into service. During that time they transmit, but you may not want to receive their packets.

With Go Live Control:

  • A device registered or updated with set_deploy: false is not yet live. You will not receive Live Network packets for it.
  • When you are ready, update the device with set_deploy: true. The device goes live at that moment, and all later packets are delivered through the API and webhooks.
  • Packets sent on the Live Network while a device is not yet live are not delivered after it goes live. There is no backfill.

Billable Device Usage​

Live-device billing starts the first time a device is heard on the Live Network after it goes live, not at the moment you send set_deploy: true. Not-yet-live devices may be billed differently from live devices, depending on your enterprise agreement. Ask Hubble Sales for details.

Self-provided packets are still delivered, even if the device is set as not yet live (set_deploy: false). This includes packets detected by the Hubble Connect mobile app and by your own BLE gateways using the Hubble Gateway SDK. A not yet live device can therefore appear as "Active" in your dashboard; only Live Network packets are withheld.

Manage go-live through the API​

At this time, go-live status can be managed only through the API, not in the Hubble Dashboard.

Go-live status​

Go-live status is stored on the device's protected _deploy tag. A device is in one of two states:

_deploy valueStateMeaning
"0"Not yet liveRegistered to your organization, but Live Network packets are not delivered.
"<epoch>"LiveAll packets are delivered. The value is the UNIX timestamp (in seconds) at which the device went live.

Devices with no _deploy tag don't use this feature. They are treated as live from registration, and all Live Network packets are delivered.

A device can "go live" only once. After it does, any further set_deploy request for that device returns HTTP 409, and the device cannot return to not yet live.

Device Lifecycle​

Register devices as not yet live​

Include set_deploy: false when you register one or more devices. The devices are created and keyed, but Live Network packets are not delivered until they go live. This works well when devices leave the factory but before they are put in use.

curl -X POST "$HUBBLE_API_HOST/v2/org/{org_id}/devices" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "n_devices": 10,
    "encryption": "AES-256-CTR",
    "set_deploy": false
  }'

Each returned device has "_deploy": "0" in its tags.

Omit set_deploy entirely if this feature isn't part of your workflow. No _deploy tag is added, and the device is live from registration.

Make an existing device not yet live​

Send set_deploy: false to a device that has no _deploy tag. This works whatever state the device is in (registered, active, or inactive). It can be done once only.

Check go-live status​

Registration and update responses return the full device object. Once set_deploy has been used on a device, its tags include _deploy. A value of "0" means not yet live. A UNIX timestamp means live as of that time.

To list not-yet-live devices, filter GET /v2/org/{org_id}/devices by tag:

curl "$HUBBLE_API_HOST/v2/org/{org_id}/devices?filter_tags=_deploy:0" \
  -H "Authorization: Bearer $API_TOKEN"

Go live​

Send set_deploy: true when the device should start delivering Live Network packets, for example when it is put into service. . You don't need to supply a timestamp; Hubble records the current time as the go-live time.

curl -X PATCH "$HUBBLE_API_HOST/v2/org/{org_id}/devices/{device_id}" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "set_deploy": true }'

The response shows "_deploy" set to the go-live timestamp.

To make many devices go live at once, use the batch endpoint, with one entry per device:

curl -X PATCH "$HUBBLE_API_HOST/v2/org/{org_id}/devices" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      { "device_id": "{device_id_1}", "set_deploy": true },
      { "device_id": "{device_id_2}", "set_deploy": true }
    ]
  }'

Errors Checklist​

StatusCause
400_deploy was included in set_tags. It is a protected tag. Use set_deploy instead.
403Your organization doesn't have the feature enabled. The message is the _deploy tag requires the factory_mode_enabled entitlement for this organization. Only requests that make a device not yet live (set_deploy: false) are affected.
409The device is already live, or the request would delete or change _deploy in a way that isn't allowed. The message is the _deploy tag may not be deleted or modified except for the one-time activation (0 -> activation timestamp).

Was this page useful? Please give us feedback.