> ## Documentation Index
> Fetch the complete documentation index at: https://docs.harbinge.rs/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway Management

> Deploying and monitoring Raven Gateway concentrators

Gateways are LilyGO T-SIM7080G-S3 devices that listen for ESP-NOW broadcasts from Raven beacons and forward them to Forager over LTE-M. Each Gateway covers an area of roughly 50–80 meters line-of-sight indoors (walls reduce range).

<Note>
  Gateway firmware setup and registration requires IT or super-admin access. See [Gateway Firmware Setup](/super-admin/gateway-firmware) for initial provisioning steps.
</Note>

***

## How Gateways work

A Gateway self-registers with Forager on first boot using Zero-Touch Provisioning (ZTP): it sends its hardware MAC to the `gateway-claim` endpoint and receives a cryptographic API key, which it stores in non-volatile storage (NVS). No manual key entry is required.

Once claimed, the Gateway:

1. Initializes ESP-NOW immediately on boot to capture Raven broadcasts during LTE attach
2. Connects to the cellular network via the Hologram SIM
3. Batches incoming Raven check-ins in a ring buffer
4. Uploads all buffered check-ins to Forager every 5 minutes over LTE-M

***

## Gateway Fleet screen

**Raven Fleet → Gateways tab** shows all registered Gateways for your company:

| Column           | Description                                             |
| ---------------- | ------------------------------------------------------- |
| **Name**         | Admin-assigned label                                    |
| **MAC**          | Hardware ID of the Gateway                              |
| **Last seen**    | Most recent upload to Forager                           |
| **Signal**       | Cellular RSSI in dBm at last upload                     |
| **Ravens heard** | Count of distinct Ravens this Gateway has received from |

### Signal quality guide

| RSSI              | Quality                               |
| ----------------- | ------------------------------------- |
| −70 dBm or better | Strong                                |
| −70 to −85 dBm    | Good                                  |
| −85 to −95 dBm    | Fair — consider repositioning         |
| Below −95 dBm     | Poor — likely causing upload failures |

***

## Placement guidelines

* **One Gateway per floor** is usually sufficient for most facilities. Add a second if the floor has large concrete sections or RF-blocking server rooms.
* Mount at a central point on the floor, elevated (above false ceiling tiles works well).
* Keep the LTE antenna unobstructed — avoid metal enclosures.
* Power via USB-C wall adapter or PoE injector with USB-C adapter. The Gateway has no battery — it requires continuous power.
* The Gateway needs cellular coverage. Check Hologram's coverage map for your address if signal is poor.

***

## LED status

The Gateway has a single status LED on GPIO 12:

| Pattern                       | Meaning                                               |
| ----------------------------- | ----------------------------------------------------- |
| 3 slow blinks at boot         | LTE-M connected successfully                          |
| 5 rapid blinks then solid off | Modem power-on failed — check antenna and SIM         |
| 1 blink every \~5 min         | Successful upload batch                               |
| No activity                   | Idle, waiting for Raven broadcasts or upload interval |

***

## SIM management

Gateways use Hologram eUICC SIMs on the Global-3 plan. Manage SIMs at [dashboard.hologram.io](https://dashboard.hologram.io):

* **Connected** — Gateway is active and has a data session open
* **Idle** — SIM is active but no current data session (normal between uploads)
* **Deactivated** — SIM needs to be reactivated

Data usage is minimal — each upload batch is under 2 KB. A fleet of 20 Ravens uploading every 5 minutes uses less than 10 MB/month per Gateway.

***

## Troubleshooting

**Gateway shows Offline in the fleet view**

* Check the SIM status in Hologram dashboard
* Confirm the LTE antenna is attached
* Connect via USB and check serial output (115200 baud) — `SHOW_SIGNAL` shows live RSSI

**Ravens not appearing on Gateway**

* Both Raven and Gateway must be on WiFi channel 1 — this is locked in firmware on both sides
* The Gateway initializes ESP-NOW before connecting to LTE. If Ravens broadcast before the Gateway has finished booting, reset the Raven manually once the Gateway serial output shows `[gw] ESP-NOW receiver ready`
* Check serial output on the Gateway — incoming ESP-NOW packets print `[gw] rx mac=...`

**Upload failures (HTTP error in serial)**

* `HTTP 401` — API key mismatch. The Gateway may need to be re-claimed: clear `api_key_hash` in the database and power-cycle the Gateway to trigger ZTP again
* `HTTP 500` — Edge Function error. Check Supabase function logs
* Connect error — cellular issue. Run `SHOW_SIGNAL` and check SIM status in Hologram dashboard