Hubble Gateway Service

Ready-to-run BLE gateway daemon for Hubble Network. Scans for Bluetooth Low Energy devices and uploads sightings to the Hubble cloud. Built on the hubble-gateway SDK.

Install

One-line install (Raspberry Pi / Linux)

curl -fsSL https://raw.githubusercontent.com/HubbleNetwork/gateway-service/main/scripts/install.sh \
  | sudo bash -s -- --sdk-key <YOUR_SDK_KEY>

The installer downloads a single pre-built binary (no Python required), writes your config, and registers a systemd service. Falls back to pip if no binary is available for your architecture.

With GPS:

curl -fsSL https://raw.githubusercontent.com/HubbleNetwork/gateway-service/main/scripts/install.sh \
  | sudo bash -s -- --sdk-key <YOUR_SDK_KEY> --gps --gps-port /dev/ttyAMA0

Uninstall:

curl -fsSL https://raw.githubusercontent.com/HubbleNetwork/gateway-service/main/scripts/install.sh \
  | sudo bash -s -- --uninstall

Download binary directly

Pre-built binaries for each release — no Python needed:

# Raspberry Pi (aarch64)
curl -fsSL https://github.com/HubbleNetwork/gateway-service/releases/latest/download/hubble-gateway-aarch64-linux \
  -o /usr/local/bin/hubble-gateway && chmod +x /usr/local/bin/hubble-gateway

# x86_64 Linux
curl -fsSL https://github.com/HubbleNetwork/gateway-service/releases/latest/download/hubble-gateway-x86_64-linux \
  -o /usr/local/bin/hubble-gateway && chmod +x /usr/local/bin/hubble-gateway

pip / uv

pip install hubble-gateway-service
# or
uv pip install hubble-gateway-service

Usage

hubble-gateway --sdk-key hsk_your_key_here

Or with environment variables:

export HUBBLE_SDK_KEY=hsk_your_key_here
hubble-gateway

Configuration

All settings via CLI flags, environment variables (prefixed HUBBLE_), or a .env file.

GPS Support

USB BLE Dongle

hciconfig                          # find your adapter
hubble-gateway --sdk-key $KEY --adapter hci1

Running as a systemd service

The one-line installer handles this automatically. For manual setup:

# /etc/systemd/system/hubble-gateway.service
[Unit]
Description=Hubble Network BLE Gateway
After=network-online.target bluetooth.target
Wants=network-online.target

[Service]
Type=simple
EnvironmentFile=/opt/hubble-gateway/.env
ExecStart=/opt/hubble-gateway/venv/bin/hubble-gateway
Restart=always
RestartSec=10
WatchdogSec=300

[Install]
WantedBy=multi-user.target

Architecture

hubble-gateway-service (this repo)
  ├─ daemon.py            orchestration, signal handling, stats loop
  ├─ cli.py               argument parsing, env wiring
  ├─ install.sh           one-line installer (binary or pip)
  └─ release.yml          GitHub Actions → PyApp single-binary builds

hubble-gateway SDK (gateway-sdk-python)
  ├─ Scanner              BLE scanning via bleak
  ├─ GatewaySender        packet batching + dedup + upload
  ├─ GatewayAuth          SDK key registration + token lifecycle
  ├─ LocationProvider      GPS (NMEA, UBX, gpsd) + fixed
  ├─ Settings             pydantic-settings config
  └─ BLEPacket, Location  data models

The service binary is built with PyApp — a Rust wrapper that embeds a Python distribution. First run bootstraps the environment (~5s), subsequent runs start instantly.

Building a custom gateway

If you need more control, use the SDK directly:

pip install hubble-gateway

from hubble_gateway import Scanner, GatewaySender, GatewayAuth

# See https://github.com/HubbleNetwork/gateway-sdk-python

License

Apache License 2.0 — see LICENSE.