Beakin Handbook¶

Welcome to the Beakin Handbook. This is the practical reference for anyone deploying, configuring, and managing a Beakin iBeacon navigation system.

Who this is for¶

This handbook is written for technical operators and deployment leads — people who are comfortable with a terminal and configuration files but who are not necessarily embedded engineers or software developers.

Contents¶

Guide	What it covers
User Guide	System overview, hardware status LEDs, daily operations, and the mobile app
Provisioning Guide	Adding beakins to the fleet, assigning location identity, and managing the provisioning lifecycle

Quick orientation¶

A Beakin deployment has three main parts:

Beakins — small BLE hardware units (XIAO boards) that continuously broadcast iBeacon signals from their shelf or aisle location.
Mobile app — an iOS/Android field app used to scan, identify, and provision beakins.
Server — a Docker-powered backend providing a central registry, dashboard, and MQTT event stream from gateway devices.

┌─────────────────┐     BLE advertisement
│   Beakin (HW)   │ ──────────────────────►  📱 Mobile App (iOS / Android)
│  iBeacon + OLED │                                       │
└─────────────────┘                                       │ GATT write (provision)
         │                                                 ▼
         │                            ┌──────────────────────────────┐
         │ BLE scan                   │  Provisioning Registry       │
         ▼                            │  (AsyncStorage on device)    │
┌─────────────────┐  MQTT             └──────────────────────────────┘
│  Gateway (HW)   │ ──────────────► 🖥  beakin-server
│  BLE scanner    │                   (Fastify API + SvelteKit UI)
└─────────────────┘

Before you start¶

Have your beacons.yaml fleet config file open (lives in beakin-fw/scripts/beacons.yaml).
Have VS Code + PlatformIO installed for firmware flashing.

Contributing / local preview¶

See Repo & CI Config for the full setup guide, including Cloudflare Pages secrets, CI workflows, and local preview instructions.

Have the Beakin mobile app installed on your iOS or Android device.
Know your site's site_id (e.g. heb-373).