Becoming a Hubble Scanner
Bring your own Bluetooth® Low Energy (BLE) scanning hardware onto the Hubble Terrestrial Network.
Who This Is For
Hubble's Terrestrial Network already detects devices through a large, growing population of partner and customer scanners. Because detection is probabilistic and depends on scanner density, adding your own scanners can add density to the network where you need it.
This guide is for people who want to scan for Hubble packets with your own custom hardware. All you need is a device with BLE scanning capabilities and internet access: a mobile device (iOS or Android), an embedded device, a Linux host, or anything else that can listen for BLE advertisements.
If you already have BLE scanning infrastructure in the field — gateways, asset trackers, access points, or a mobile app — or are deploying it soon, you can convert those devices instead of adding new hardware.
What a Scanner Actually Does
Three things:
- Scan (or listen) for Hubble BLE advertisements on the device's radio.
- Package what it heard, with a timestamp and the scanner's location.
- Deliver that to Hubble's backend.
Every integration option below does the same three things. They differ only in how much of the work Hubble's code does versus how much your code does, and in where the data leaves your network.
BLE Scanning Overview
The gateway must perform BLE passive scanning to receive advertising packets from Hubble devices. The gateway does not need to connect to or interact with Hubble devices — it only listens for advertisements.
Identifying Hubble Advertisements
For the packet structure and the rules that identify a Hubble advertisement, see Advertising Packet.
Two Integration Models
Model A — Gateway SDK
Hubble code runs on your device. It handles scanning, packet parsing, batching, retries, and authentication to the Gateway API. You give it a Gateway Client Key and a location, it does the rest.
Use the Gateway SDK when:
- Your device runs Android, iOS, or Linux with enough compute for Python, so it can run Hubble code directly.
- You do not already have a cloud pipeline for BLE scan data, or you would rather not build one.
- You want the fastest path to first data. This is the shorter integration.
- You want Hubble to handle protocol changes for you as the SDK updates.
Model B — Packets Endpoint (your own cloud)
Your devices scan and report to your existing cloud. Your cloud forwards the raw BLE observations to Hubble's packets endpoint. Hubble code never runs on your hardware.
Use the Packets Endpoint when:
- Your devices already report BLE scan data to your cloud and you do not want to change firmware or app code.
- Your hardware cannot run the SDK (constrained RTOS devices, locked-down firmware, iOS today) but can still report raw advertisements upstream.
- You have security or compliance requirements that mean no third-party code on the device.
- You want a single egress point to Hubble rather than every device talking out to the internet.
Recommendation: If you can change what runs on the device, use the SDK. If you can only change what runs in your cloud, use the packets endpoint.
Available SDKs
Hubble grants you a single Gateway Client Key. All of the following talk to the same underlying Gateway API, so one key works across form factors.
| SDK | Status |
|---|---|
| Android Hubble Gateway SDK | Available |
| Python Hubble Gateway SDK | Available |
| iOS Hubble Gateway SDK | Available |
Repositories
- gateway-service — a ready-to-run Linux daemon. Start here if you want something that works out of the box on a Linux host.
- gateway-sdk-python — the Python SDK the daemon is built on. Use this if you need a custom wrapper or want to embed scanning in your own application.
- quickstart-android — a sample Android app that scans and reports.
- quickstart-ios — a sample iOS app that scans and reports.
Releases
The Hubble gateway SDK is released for both iOS and Android:
Paths by Hardware Type
Fixed Gateways Embedded in a Warehouse or Facility
Supported and straightforward.
Run the Linux gateway daemon (gateway-service) or build directly against the Python SDK on any Linux host:
- Raspberry Pi
- Industrial PC
- Off-the-shelf IoT gateway
Reach out to BD@hubble.com to inquire about existing off-the-shelf options.
Mobile / Cellular Asset Trackers Acting as Scanners
The path depends on what the scanner runs:
| Scanner platform | Path | Status |
|---|---|---|
| Android | Android Gateway SDK | Supported |
| iOS | iOS Gateway SDK | Supported |
| Linux (with enough compute for Python) | Python Gateway SDK | Supported |
| RTOS / bare metal (no Python, no Android or iOS) | Custom integration | Not supported today |
For RTOS and bare metal targets, our firmware team is available to support a custom integration. This requires a scoping conversation, not a self-serve integration. The packets endpoint may also be viable if the device already reports advertisements to your cloud.
Wi-Fi-Connected Access Points in Your Facilities
There is no established spec for this path today. Treat it as scoping work, not integration work.
Whether an access point (AP) can act as a Hubble scanner depends on:
- Whether the AP has a usable BLE radio
- Whether the firmware is open enough to run or extend code, versus a locked-down commercial image
- The OS and compute available on the AP
- Vendor and model specifics
To move forward we need the specific AP models in use so we can scope and validate the architecture.
Book a scoping call before committing this path to a plan. Do not assume an AP fleet is convertible until Hubble has confirmed it.
Requesting a Gateway Client Key
- Create a Hubble account if you have not done so already: dash.hubble.com
- Contact Hubble at BD@hubble.com to provide these details:
- Organization ID
- Intended integration model (Gateway SDK or packets endpoint)
- Hardware types and approximate device count
- Deployment environment and target timeline
- Hubble issues a Gateway Client Key.
One key covers all SDK form factors. Treat the key as a provisioning secret: it needs to reach the device once, not live in every request.
What the SDK Does With Your Key
When you use the Gateway SDK, you never need to write authentication code. On first run, the SDK registers the scanner with the Gateway API using your Gateway Client Key, and the API returns an access token scoped to that one scanner. The SDK uses the token for all subsequent uploads, refreshes it before expiry, and re-registers automatically if a refresh fails. The token is cached on disk so restarts don't re-register.
- Each device registers separately and receives its own gateway ID and token, so a single Gateway Client Key can provision your whole fleet without becoming a shared device identity.
- The Gateway Client Key is only used at gateway registration. After that, the scanner authenticates with its token.
Integration Process
Suggested sequence. Adjust to your environment.
Step 1 — Scope
Confirm your hardware maps to a supported path in Paths by Hardware Type. If it lands in the RTOS or Wi-Fi AP categories, start with a scoping call instead.
Step 2 — Get your Gateway Client Key
See Requesting a Gateway Client Key.
Step 3 — Bench test with one device
Stand up a single scanner. For fixed gateways, the Linux daemon on a Raspberry Pi is the fastest bench setup even if it is not your production hardware. Confirm the log shows a successful registration and a gateway ID, and that the gateway reports.
Step 4 — Validate detections
Confirm Hubble is receiving your scanner's observations and that they are attributed to your organization.
Step 5 — Set locations
Every scanner needs an accurate location for proof of presence to be meaningful.
Step 6 — Scale
Roll out to the full fleet.
ℹ️ Was this page useful? Please give us feedback.