Install, configure, survive.

Contents

• Install
• Configure
• Hardware
• Troubleshoot
• API reference

1. Sign up and create a gateway. Create an account, then go to /settings/org/gateways and click Add gateway. Give it a name you'll recognize in logs ("Garage Pi", "Cabin"). We mint an API token on creation and show it exactly once. Copy it now or you'll have to mint another.

2. Install EE Gateway from the Umbrel App Store. In umbrelOS: open the App Store, search for EE Gateway, and click Install. Or open the listing directly:

apps.umbrel.com/app/ee-gateway

The image pull takes about two minutes on a Pi 5 with a typical connection. Prefer the community channel? Add https://github.com/Encrypted-Energy/umbrel-community-app-store under App Store, Community App Stores, Add app store. Same software, faster updates for testing builds.

3. Paste your credentials. Open the app from your umbrelOS dashboard (the port differs between the official and community stores, so launch it from the dashboard tile). Paste your ee_org_… and ee_live_…, then click Save and start gateway. The dashboard flips from Starting up to Running once the worker authenticates and reaches the EE API.

Installing on iPhone instead. Install EE Gateway from the App Store, open it, and paste your ee_live_… token. That's the whole setup — no org ID needed; the token identifies your gateway. The app explains each permission before iOS asks: Bluetooth to hear packets, location to stamp them (the network rejects packets without coordinates). Grant Always location if you want it forwarding with the screen locked.

Organization ID Format: ee_org_ followed by 22 characters. Stable, never rotates. Identifies your account on EE; never leaves our backend.

API token Format: ee_live_ followed by 48 hexadecimal characters. Per-gateway, revocable, shown exactly once at creation. If you lose the plaintext, mint a new token from your gateway's page; the old one stays valid until you click Revoke.

Rotating a token On the gateway's page, click Mint a new token. Paste the new value into the Umbrel app's setup wizard (Reconfigure link in the footer of the dashboard) and save. Within one ingest cycle (about five seconds) the worker's using the new token. Revoke the old one when you confirm the new one works. On iPhone: Settings tab, Replace token.

Raspberry Pi 5 (recommended) or Pi 4 Either works. The gateway uses about 3 watts idle. Pi 5 has better thermals if you plan to add a USB BLE dongle that pulls non-trivial current. An x86 mini-PC running Umbrel works too; BLE just has to be reachable through BlueZ.

USB BLE dongle (optional, recommended) The Pi's built-in BLE radio works but has a small internal antenna. Get a Sena UD100 (about $45) and screw on a 5–7 dBi external SMA antenna. EE only scans, so antenna gain is what matters; transmit power is irrelevant. A taller antenna placed near a window will out-hear the stock stub every time.

Location (no hardware required) Every forwarded packet needs a coordinate. The default path is the setup wizard: enter the gateway's lat/lon once, the worker stamps every packet with that location. Right-click Google Maps to grab decimal coordinates; the form accepts -90..90 and -180..180. Most operators set this once and never touch it again.

Optional: GPS for moving gateways If the gateway moves (vehicle-mounted, mobile asset, anything that won't sit still), a fixed coordinate won't reflect where each packet was actually heard. The easiest path is a USB GPS dongle (no soldering): the worker auto-discovers any device on /dev/ttyUSB* (PL2303 class like the GlobalSat BU-353N) or /dev/ttyACM* (u-blox NEO class like the VK-172) at boot. See the kit page for specific dongles. If you want integrated GPS instead, the Adafruit Ultimate GPS HAT stacks on the Pi's GPIO header but requires soldering the included pin header and configuring gpsd manually. Either way, GPS needs sky view to lock. Indoor cold-starts can take minutes or fail outright. If the gateway lives in a basement or interior room, use the fixed-location field instead.

Waiting for credentials The worker can't read its config file. Usually because you haven't finished the setup wizard yet. Paste your org ID and API token, click Save and start gateway. If it persists, SSH into umbrelOS and check that /home/umbrel/umbrel/app-data/encryptedenergy-ee-gateway/data/config.json exists and is readable by uid 1000.

Authentication failed EE rejected your token. Either it was mistyped, revoked, or belongs to a different organization. Open your gateway page, mint a fresh token, paste it into the wizard, save.

Bluetooth scan error The worker tried to scan and BlueZ rejected the request. Common causes: no Bluetooth radio present (e.g. running on Docker Desktop or OrbStack for testing), bluetoothd not running, or another process holding the radio exclusively. On a Pi: sudo systemctl status bluetooth and confirm it's active.

Starting up (forever) The worker's in a crash-restart loop. Most likely cause is a BLE radio that isn't present or isn't responding. Check the worker container's logs:

sudo docker logs --tail 50 encryptedenergy-ee-gateway_worker_1

Dashboard shows "Active" but no packets The worker's reaching EE (heartbeat's fine) but the BLE radio isn't hearing any compatible devices. Either none are in range, or your antenna placement's the problem. Move the antenna toward a window, or add a USB dongle with an external antenna (see Hardware above).

iPhone gateway states Your gateway page on encryptedenergy.com mirrors the app. Location permission needed: location is off for EE Gateway; enable it in iPhone Settings, Privacy & Security, Location Services. Position stale: iOS paused background location (While-Using permission); open the app to resume, or grant Always so positions stay fresh while locked. Low Power Mode pauses scanning; the app resumes on its own when it lifts. The app's Diagnostics tab has the packet-level log.

Authentication Every request carries an Authorization: Bearer ee_live_… header. The token's gateway and organization are looked up server-side; the client never sends them explicitly. The three gateway endpoints take gateway tokens only, minted from a gateway's page. Org keys from Settings authenticate the org API instead, and neither kind works on the other's endpoints. Any invalid, revoked, or wrong-scope token gets a 401 with {"ok": false, "error": "invalid_token"}.

Authorization: Bearer ee_live_acb94316b93a6dd637bfb8e59645c25a474af69cd0a19707
Content-Type: application/json
Accept: application/json

GET /api/v1/gateways/verify Read-only credential check. Call it once at setup, before you persist the token, so a typo fails loudly instead of surfacing as a mystery 401 later. No body. Returns 200 with the gateway and organization the token resolves to:

{
  "ok": true,
  "gateway": {
    "name": "Garage Pi",
    "public_id": "ee_gw_…",
    "organization_id": "ee_org_…",
    "organization_name": "My Org"
  }
}

POST /api/v1/gateways/heartbeat Periodic liveness ping. Updates the gateway's last_seen_at. Body fields are all optional; send an empty {} if you have nothing to report.

{
  "last_packet_at": "2026-06-08T22:31:00Z",
  "last_known_position_at": "2026-06-08T22:30:55Z",
  "gps_status": "fix",
  "platform": "umbrel",
  "os_version": "umbrelOS 1.4"
}

gps_status is one of fix, no_fix, dongle_missing. platform is one of umbrel, ios, android, linux — it drives platform-specific guidance on your gateway's dashboard page. The official worker also reports packet counters as deltas (packets_forwarded_delta and friends); send those only if you reset your local counter on a 2xx response, so a crash never double-counts. Returns 200 with the gateway's current state (uuid, status, last_seen_at, gps_status, packet totals), or 401 if the token's invalid or revoked. Cadence: the official worker heartbeats every 60 seconds. Keep yours under 15 minutes; gateways silent longer than that are marked down and the operator gets an alert email.

POST /api/v1/gateways/packets Forward a batch of BLE packets to the upstream network. EE proxies each packet using its wholesale relationship there. You never need to hold upstream credentials. At most 500 packets per request; the whole request is forwarded as one upstream batch, so every status code below applies to the batch, not to individual packets.

{
  "packets": [
    {
      "payload_b64": "BLE-payload-as-base64",
      "eid": "a1b2c3d4e5f6",
      "rssi": -53,
      "timestamp": 1717900000,
      "latitude": 47.6062,
      "longitude": -122.3321,
      "position_at": 1717899995,
      "accuracy_m": 8.5
    }
  ]
}

eid is the device identifier the worker decodes from the BLE payload (hex string). Required: a batch with a missing eid gets a 422, and bounties are keyed off it. timestamp and position_at are unix seconds (when the packet was heard, when the GPS fix was captured). position_at and accuracy_m are optional. Coordinates must be in range and not (0, 0); that's the unset fixed-location tell and the batch gets a 422. Returns:

• 200: batch accepted upstream. Drop it from your queue.
• 401: token invalid or revoked. Stop sending until you have a new one.
• 413: over 500 packets. Split the batch and resend.
• 422: malformed batch, or upstream rejected it (4xx). Drop it; retrying won't help. The body's invalid_reasons array says which packet and why.
• 502: upstream unreachable or returned 5xx. Leave the batch pending; retry on the next pass.

Payouts: a 200 means the batch was accepted, not that every packet earned sats. Bounties mint 1 sat per device per organization per UTC day, and the first gateway on the network to forward a given packet wins it.

Org API: scripted provisioning Deploying a fleet with Ansible or a shell script? Skip the dashboard. Authenticate with an org key from Settings, API tokens, same Bearer header as above. Gateway tokens get a 401 on every org endpoint.

GET    /api/v1/org/gateways                    list your gateways
POST   /api/v1/org/gateways                    create one: {"name": "Garage Pi"}
GET    /api/v1/org/gateways/:uuid              one gateway plus its tokens (masked)
POST   /api/v1/org/gateways/:uuid/tokens       mint another token
DELETE /api/v1/org/gateways/:uuid/tokens/:id   revoke a token

Create returns 201 with the gateway and its first token. token.key is the plaintext, shown exactly once, same contract as the dashboard:

{
  "ok": true,
  "gateway": { "uuid": "…", "public_id": "ee_gw_…", "name": "Garage Pi", "status": "pending" },
  "token": { "id": 42, "name": "Garage Pi initial token", "key": "ee_live_…" }
}

Feed that key straight to the worker's config and you've provisioned a gateway without opening a browser. :uuid accepts the bare uuid or the ee_gw_… form. Errors: 400 missing name, 404 not your gateway, 422 validation failed.