Skip to main content
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.
Gateways must be deployed and registered before Ravens can report. See Gateway Management for Gateway setup.

​
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

​
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)
  • An NTAG215 anti-metal NFC sticker
  • The Forager Android app (admin role)
1

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).
2

Open Raven Fleet in the app

In the Forager Android app, tap Raven Fleet on the home screen, then tap the + button.
3

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

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

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).
6

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.

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

​
Changing the scan interval

Shorter intervals mean more frequent check-ins but faster battery drain.
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.

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