> ## 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.

# Raven Fleet (Admin)

> Provisioning Raven beacons, managing intervals, and monitoring fleet health

Ravens are battery-powered ESP32 beacons that attach to assets and broadcast their identity over ESP-NOW radio to nearby Gateway concentrators. The Gateway forwards check-ins to Forager over LTE-M. This enables passive, continuous presence confirmation without any tech involvement.

<Note>
  Gateways must be deployed and registered before Ravens can report. See [Gateway Management](/admin/gateway-management) for Gateway setup.
</Note>

***

## How Ravens work

1. A Raven wakes on a configurable interval (default 6 hours)
2. It passively scans nearby Wi-Fi access points and BLE devices
3. It signs the payload with a per-device HMAC secret and broadcasts via ESP-NOW
4. A nearby Gateway receives the broadcast and batches it with others
5. Every 5 minutes the Gateway POSTs the batch to Forager over LTE-M
6. Forager verifies the HMAC, records a check-in, and updates the asset's **Last Seen** timestamp

***

## Raven Fleet screen

In the Forager Android app, **Raven Fleet** lists all Ravens for your company. Each row shows:

* **Primary label** — the assigned asset's name when a Raven has an asset, or the Raven's own name when unassigned
* **Secondary label** — the Raven's own name (when an asset is assigned) or its hardware ID
* **Status chip** — Online / Late / Offline with time-to-next-check-in
* **Battery icon** — appears when the last reported battery level is low

### Status thresholds

| Status      | Condition                                             |
| ----------- | ----------------------------------------------------- |
| **Online**  | Last seen within `interval × 1.5`                     |
| **Late**    | Last seen between `interval × 1.5` and `interval × 3` |
| **Offline** | Last seen more than `interval × 3` ago, or never      |

***

## Provisioning a Raven

Provisioning creates a Forager record for a new Raven beacon and writes its identity to an NFC sticker. You need:

* The Raven hardware (ESP-WROOM-32 dev board or production unit), powered on
* The Raven firmware flashed (see [Raven Firmware Setup](/super-admin/raven-firmware))
* An NTAG215 anti-metal NFC sticker
* The Forager Android app (admin role)

<Steps>
  <Step title="Get the Raven's MAC address">
    Connect the Raven to a computer via USB and open Serial Monitor (115200 baud). Within 5 seconds of boot, type `SHOW_MAC`. Note the MAC address (e.g. `00:4b:12:2e:97:10`).
  </Step>

  <Step title="Open Raven Fleet in the app">
    In the Forager Android app, tap **Raven Fleet** on the home screen, then tap the **+** button.
  </Step>

  <Step title="Enter the MAC address and name">
    Type the MAC address exactly as shown by `SHOW_MAC` (lowercase, colon-separated). Give the Raven a descriptive name.

    Tap **Create Raven + Write NFC**. The button activates once both fields are filled in.
  </Step>

  <Step title="Write the NFC sticker">
    Forager generates a unique HMAC secret, stores it in the database, and prompts you to tap the NFC sticker. Hold the NTAG215 sticker near the back of your phone. The app writes the Raven's identity to the sticker and confirms success.

    <Warning>
      Note the HMAC secret shown on screen — you need to enter it on the Raven hardware before it can report. Copy it and complete the serial step before closing the app.
    </Warning>
  </Step>

  <Step title="Set the secret on the Raven hardware">
    In Serial Monitor, type `SET_SECRET:<64-char-hex>` and paste the secret from the app. Confirm with `SHOW_CONFIG`.

    Power-cycle the Raven and verify the serial output shows `[raven] broadcast: sent`. The first check-in should appear in Raven Fleet within one Gateway upload cycle (\~5 minutes after the Gateway receives the packet).
  </Step>

  <Step title="Attach the NFC sticker to the asset">
    Stick the programmed NTAG215 sticker on or adjacent to the asset. The sticker allows anyone with the Forager app to tap it and identify the asset.
  </Step>
</Steps>

***

## Assigning a Raven to an asset

A Raven doesn't need to be assigned to an asset to report check-ins, but assignment is required for:

* The asset's name to appear as the primary label in Raven Fleet
* The Raven badge (📡) to appear on the asset card
* The `last_seen` field on the asset detail to update

To assign: open the Raven's detail in the app → tap **Assign to asset** → search for the asset by tag or name.

Once assigned, the Raven row in the fleet list displays the asset name as its primary label and the Raven name as secondary. Unassigned Ravens show their own name as the primary label.

***

## Raven Detail screen

Tap any Raven to open its detail view. This screen shows hardware ID, scan interval, pending interval (if an OTA update is queued), battery, temperature, last seen, and next check-in estimate. The screen title shows the assigned asset name when applicable.

### Actions

**Change scan interval** — Sets a new interval. The value is delivered to the Raven on its next check-in via an OTA config push from the Gateway. Until the Raven confirms receipt, the pending interval is shown separately.

**Replace Raven** — Decommissions the current hardware and provisions a replacement. Asset history and attestation log are preserved.

**Rewrite NFC sticker** — Rewrites the NTAG215 sticker using the credentials already stored in the database. Use when:

* The sticker was damaged and replaced with a blank one
* You need a second sticker for the same Raven
* The hardware was reflashed and the MAC changed

Flow: tap the button → dialog appears → hold the sticker to the phone. The Raven's HMAC secret in firmware NVS is not changed.

**Read NFC tag** — Reads the sticker and checks whether the hardware ID on it matches this Raven's record.

| Result                 | Meaning                                                                   |
| ---------------------- | ------------------------------------------------------------------------- |
| **Tag matches**        | Sticker is correct for this Raven                                         |
| **Tag mismatch**       | Sticker belongs to a different Raven — use **Rewrite NFC sticker** to fix |
| **Could not read tag** | Sticker is blank, damaged, or not an NTAG215 provisioned by Forager       |

***

## Changing the scan interval

Shorter intervals mean more frequent check-ins but faster battery drain.

| Interval | Battery life (est.) | Use case                       |
| -------- | ------------------- | ------------------------------ |
| 15 min   | \~2 weeks           | High-value or mobile equipment |
| 60 min   | \~6 weeks           | Standard equipment             |
| 6 hours  | \~6 months          | Fixed, rarely-moved equipment  |

<Note>
  Interval changes are queued and delivered the next time the Raven checks in. The Raven must receive the update before the new interval takes effect.
</Note>

***

## Hardware Swap

When a Raven beacon needs to be replaced (dead battery, lost device):

1. Open the Raven's detail in the app
2. Tap **Replace Raven**
3. Enter the new Raven's MAC address
4. Hold the NFC sticker to write the new identity
5. Set the new secret on the replacement hardware via `SET_SECRET:<key>`

The Forager record (name, assigned asset, interval, history) is preserved. The old hardware MAC is decommissioned.