Fonek

fonek

Track your own things through Apple's Find My network and see them on your own map, with hardware you can build yourself.

fonek is three parts that work together:

• A tag (fonek/): an open KiCad design for a rechargeable ESP32 BLE tag with USB-C charging, plus the firmware instructions to turn any ESP32 dev board into a beacon.
• A backend (backend/): a FastAPI service that fetches the encrypted location reports from Apple with FindMy.py, decrypts them with the tag's private key and stores them in SQLite. No Mac required.
• A web app (web/): a Next.js + Leaflet dashboard showing each tag's latest position and history.

Status: prototype. The software runs today with an ESP32 dev board. The rev A PCB passes KiCad ERC/DRC but has not been built and tested yet; see its release checks. fonek is not an Apple-certified Find My accessory and relies on an unofficial Apple API.

How it works

flowchart LR
  TAG["Tag<br>ESP32 + OpenHaystack firmware"] -- "BLE advertisement<br>(public key)" --> PHONE[Nearby iPhones]
  PHONE -- "encrypted location report" --> APPLE[(Apple Find My)]
  APPLE -- "reports for our keys" --> BACKEND["backend<br>FastAPI + FindMy.py"]
  BACKEND --> DB[(data/fonek.db)]
  WEB["web<br>Next.js + Leaflet"] -- "/api" --> BACKEND

Each tag has a key pair. The tag broadcasts the public key over Bluetooth. Any iPhone that passes by encrypts its own location with that key and uploads it to Apple. Only the holder of the private key can decrypt the report, and that key never leaves your backend. docs/architecture.md goes into the details.

Quick start

You need Docker, an ESP32 with Bluetooth LE, and an Apple ID with two-factor authentication. Use a dedicated Apple ID, not your personal one (see Things to know).

git clone https://github.com/lodjim/fonek.git && cd fonek
docker compose up -d --build
docker compose run --rm backend python -m app.cli login   # Apple ID + 2FA, once

Then:

1. Open http://localhost:3000 and click Add device. fonek generates a key pair and shows the advertisement key.
2. Flash that key onto the ESP32, following firmware/README.md.
3. Carry the tag near iPhones. Reports are fetched every 15 minutes, or on demand with Refresh.

docs/setup.md covers configuration, backups, updating and troubleshooting.

Things to know

• Use a dedicated Apple ID with 2FA enabled. fonek talks to a private Apple API; an account could be rate-limited or locked. Keep the poll interval conservative.
• Locations are not live. They arrive only when an iPhone passes near the tag, and typically lag by minutes to hours.
• data/ holds secrets. It contains every tag's private key and the Apple session, unencrypted. Back it up and keep it private.
• There is no login on the web app. Keep it on your LAN and do not expose ports 3000 or 8000 to the internet.
• The tag's key is static. Anyone nearby can recognise the same tag over time.
• Only track things you own. Tracking people without their consent is illegal in many places and is not what this project is for.

Repository layout

Documentation

• Architecture: how the pieces fit, the data model, the poller
• Setup and operation: configuration, Apple login, backups, troubleshooting
• API reference: the REST endpoints the web app uses
• Firmware: building and flashing the beacon
• Hardware: the rev A tag, its electrical design and verification status
• Contributing: development setup and tests

Development

# backend
cd backend && python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
FONEK_DATA_DIR=../data .venv/bin/uvicorn app.main:app --reload
FONEK_DATA_DIR=../data .venv/bin/python -m app.cli seed   # demo device with a fake track
.venv/bin/pytest

# web (proxies /api to http://localhost:8000)
cd web && npm install && npm run dev

More in CONTRIBUTING.md.

Acknowledgements

fonek stands on other people's work:

• OpenHaystack by the Secure Mobile Networking Lab at TU Darmstadt, which reverse-engineered the Find My protocol and provides the ESP32 firmware the tag runs.
• FindMy.py, which handles the Apple login and report decryption.
• Map tiles and data from OpenStreetMap contributors.

fonek is an independent project. It is not affiliated with or endorsed by Apple. Find My and AirTag are trademarks of Apple Inc.