mirror of https://github.com/meshcore-dev/MeshCore
Stefan Alfredsson
4 days ago
committed by
Stefan Alfredsson
Stefan Alfredsson
9 changed files with 380 additions and 7 deletions
@ -0,0 +1,113 @@ |
|||||
|
# FindMy / OpenHaystack Beacon |
||||
|
|
||||
|
This document describes the experimental FindMy locator beacon for nRF52 MeshCore nodes. |
||||
|
|
||||
|
## Purpose |
||||
|
|
||||
|
When enabled, a node advertises an Apple [FindMy](https://support.apple.com/find-my) / |
||||
|
[OpenHaystack](https://github.com/seemoo-lab/openhaystack) "offline finding" beacon alongside |
||||
|
its normal mesh duties. Nearby iPhones anonymously relay its encrypted location to Apple's |
||||
|
servers, letting you locate a deployed node through the global Find My network — no extra |
||||
|
infrastructure, GPS, or cellular needed. |
||||
|
|
||||
|
This is particularly useful for repeater nodes. To maximise coverage they are often deployed in |
||||
|
exposed, unattended, hard-to-reach spots — rooftops, towers, hilltops, remote solar sites — which |
||||
|
makes them especially prone to going missing, whether through theft, weather, a failed mount, or |
||||
|
simply being forgotten. A FindMy beacon gives you a way to locate (or recover) such a node, or at |
||||
|
least get a last-known position, without having to physically visit the site. |
||||
|
|
||||
|
The node only ever broadcasts a **public** advertising key. Decrypting the location reports |
||||
|
requires the matching **private** key, which you keep off-device on your own machine. |
||||
|
|
||||
|
## Supported hardware |
||||
|
|
||||
|
nRF52840 boards only (Adafruit Bluefruit BLE stack), |
||||
|
but the implementation is easily ported to ESP32 and other BLE capable chips. |
||||
|
The challenge is with concurrent BLE usage, ie. companion nodes. **TODO/Future work** check if |
||||
|
ble adverisements can be sent when the companion is disconnected from the phone, |
||||
|
and disable when reconnected. |
||||
|
|
||||
|
Pre-defined build environments: |
||||
|
|
||||
|
| Environment | Board | |
||||
|
|-------------|-------| |
||||
|
| `RAK_4631_repeater_findmy` | RAK4631 / RAK WisMesh (repeater, incl. Solar Repeater Mini) | |
||||
|
| `LilyGo_T-Echo_repeater_findmy` | LilyGo T-Echo | |
||||
|
|
||||
|
The feature is gated behind the `WITH_FINDMY_BEACON` build flag, so it adds nothing to other |
||||
|
builds. It is intended for always-on roles (repeater/sensor) where BLE is otherwise unused. It |
||||
|
is **not** for the phone-companion firmware, which needs BLE for its own link — a node can be a |
||||
|
FindMy beacon or a phone companion, not both at once. |
||||
|
|
||||
|
## Generating keys |
||||
|
|
||||
|
Keys are generated off-device with the OpenHaystack / macless-haystack tooling — see |
||||
|
[macless-haystack](https://github.com/dchristl/macless-haystack) (or the original |
||||
|
[OpenHaystack](https://github.com/seemoo-lab/openhaystack)). Its `generate_keys.py` produces |
||||
|
three values per key; use them as follows: |
||||
|
|
||||
|
| Value | Where it goes | Purpose | |
||||
|
|-------|---------------|---------| |
||||
|
| **Advertisement key** (public, 28 bytes) | the **node** (`set findmy.key`) | broadcast in the BLE advert + MAC | |
||||
|
| **Private key** | your **server only** | decrypts the location reports | |
||||
|
| **Hashed adv key** | your **server** (lookup id) | used to query Apple for reports | |
||||
|
|
||||
|
Only the advertisement (public) key goes on the node. Never load the private key onto the |
||||
|
device — it would be broadcast publicly and reports would not decrypt. (Note: the private key is |
||||
|
also 28 bytes, so the firmware cannot tell them apart by length — pick the value labelled |
||||
|
*advertisement*.) |
||||
|
|
||||
|
## Node configuration |
||||
|
|
||||
|
Configure over the local USB serial console (115200 baud) or remotely from the MeshCore app's |
||||
|
Command Line tab when logged in as admin. Configuration is stored in `/findmy` on the node's |
||||
|
internal filesystem (independent of the normal node preferences). |
||||
|
|
||||
|
``` |
||||
|
set findmy.key <base64-advertisement-key> -> OK - reboot to apply |
||||
|
set findmy on -> OK - on, reboot to apply |
||||
|
get findmy -> > on, mac DF:41:B5:D7:F3:BF |
||||
|
reboot |
||||
|
``` |
||||
|
|
||||
|
- `set findmy.key` must decode to exactly 28 bytes, otherwise it reports |
||||
|
`Error: decoded N bytes, expected 28`. |
||||
|
- `get findmy` shows the enabled state and the derived BLE MAC (it never echoes the key). The |
||||
|
MAC is `key[0]|0xC0 : key[1] : key[2] : key[3] : key[4] : key[5]`. |
||||
|
- The beacon starts only at boot, so `reboot` (or a power cycle) is required to apply changes. |
||||
|
On boot the node prints `FindMy beacon started`. |
||||
|
- `set findmy off` then `reboot` stops advertising (the stored key is kept). |
||||
|
|
||||
|
### Verifying |
||||
|
|
||||
|
1. **On air:** scan with a BLE tool (e.g. nRF Connect). You should see a non-connectable |
||||
|
advertiser at the address `get findmy` reported (address type *Random*) carrying Apple |
||||
|
manufacturer data beginning `4C 00 12 19 …`. |
||||
|
2. **Key sanity:** run heystack's `tools/showmac.py` on the advertisement key you loaded — it |
||||
|
must print the same MAC as `get findmy`. A mismatch means the wrong key was loaded. |
||||
|
|
||||
|
## Retrieving location data |
||||
|
|
||||
|
Use your own server with the **private** key — the node cannot retrieve anything itself. With |
||||
|
macless-haystack, query and decrypt reports using its scripts, e.g. `fetch_reports.py` (a |
||||
|
`findmy.py`-style query), which authenticates to Apple (via Anisette), pulls the encrypted |
||||
|
reports for the hashed adv key, and decrypts them with the private key. See the |
||||
|
[macless-haystack](https://github.com/dchristl/macless-haystack) README for setup |
||||
|
(Anisette/Apple-ID requirements) and exact invocation. |
||||
|
|
||||
|
## Notes and caveats |
||||
|
|
||||
|
- **Latency:** Find My is deliberately latency-tolerant. Reports appear only after the node is |
||||
|
near a passing iPhone and can take minutes to a few hours. |
||||
|
- **Power:** continuous BLE advertising keeps the SoftDevice awake, so idle current is higher |
||||
|
than a node with BLE off. The advertising interval defaults to ~2 s; override with |
||||
|
`-D FINDMY_ADV_INTERVAL=<0.625ms-units>`. |
||||
|
- **Privacy:** the key is static (no rotation), so anyone holding it can track the node. |
||||
|
- **Static key may be rate-limited / blocked (TODO):** genuine AirTags rotate their advertising |
||||
|
key roughly daily, and Apple's network is tuned for that. A single never-changing key can be |
||||
|
treated as anomalous and may have its reports throttled or dropped over time, so long-term |
||||
|
reliability is not guaranteed. **Future work:** add key rotation — store a sequence of keys and |
||||
|
advance the index on a daily schedule (matching AirTag behaviour), and extend the key generator |
||||
|
to emit a batch of keys with daily-incrementing indices that the server side can resolve. |
||||
|
- **OTA:** the beacon coexists with `start ota` — triggering a firmware update reuses the |
||||
|
running BLE stack and switches to the DFU advertiser automatically. |
||||
@ -0,0 +1,138 @@ |
|||||
|
#include "FindMyBeacon.h" |
||||
|
|
||||
|
// Gated on the opt-in feature flag so the unit stays inert even if a variant's build_src_filter
|
||||
|
// happens to glob helpers/nrf52/*.cpp.
|
||||
|
#ifdef WITH_FINDMY_BEACON |
||||
|
|
||||
|
#include <string.h> |
||||
|
#include <stdio.h> |
||||
|
#include <bluefruit.h> |
||||
|
#include <InternalFileSystem.h> |
||||
|
#include <base64.hpp> |
||||
|
#include "ble_gap.h" |
||||
|
#include "../NRF52Board.h" |
||||
|
|
||||
|
using namespace Adafruit_LittleFS_Namespace; |
||||
|
|
||||
|
// Advertising interval in units of 0.625 ms. ~2s by default to keep idle current low;
|
||||
|
// override per-build with -D FINDMY_ADV_INTERVAL=<units>.
|
||||
|
#ifndef FINDMY_ADV_INTERVAL |
||||
|
#define FINDMY_ADV_INTERVAL 3200 |
||||
|
#endif |
||||
|
|
||||
|
#define FINDMY_FILE "/findmy" |
||||
|
|
||||
|
FindMyBeacon findmy_beacon; |
||||
|
|
||||
|
bool FindMyBeacon::load() { |
||||
|
_enabled = 0; |
||||
|
memset(_key, 0, sizeof(_key)); |
||||
|
if (!InternalFS.exists(FINDMY_FILE)) return false; |
||||
|
File f = InternalFS.open(FINDMY_FILE); |
||||
|
if (!f) return false; |
||||
|
f.read((uint8_t *)&_enabled, sizeof(_enabled)); |
||||
|
f.read(_key, sizeof(_key)); |
||||
|
f.close(); |
||||
|
return true; |
||||
|
} |
||||
|
|
||||
|
void FindMyBeacon::save() { |
||||
|
InternalFS.remove(FINDMY_FILE); |
||||
|
File f = InternalFS.open(FINDMY_FILE, FILE_O_WRITE); |
||||
|
if (!f) return; |
||||
|
f.write((uint8_t *)&_enabled, sizeof(_enabled)); |
||||
|
f.write(_key, sizeof(_key)); |
||||
|
f.close(); |
||||
|
} |
||||
|
|
||||
|
void FindMyBeacon::begin(int8_t tx_dbm) { |
||||
|
if (_started) return; |
||||
|
|
||||
|
load(); |
||||
|
if (!_enabled) return; |
||||
|
|
||||
|
bool key_set = false; |
||||
|
for (size_t i = 0; i < sizeof(_key); i++) { if (_key[i]) { key_set = true; break; } } |
||||
|
if (!key_set) return; |
||||
|
|
||||
|
// Bring up the SoftDevice/Bluefruit stack (shared one-shot guard - see NRF52Board).
|
||||
|
if (!NRF52Board::beginBluefruitOnce()) return; |
||||
|
|
||||
|
Bluefruit.setTxPower(tx_dbm); |
||||
|
|
||||
|
// Static-random BLE address derived from the first 6 key bytes. ble_gap_addr_t.addr is
|
||||
|
// little-endian (addr[0] = LSB); the MSB's top two bits mark a static random address.
|
||||
|
ble_gap_addr_t addr; |
||||
|
memset(&addr, 0, sizeof(addr)); |
||||
|
addr.addr_type = BLE_GAP_ADDR_TYPE_RANDOM_STATIC; |
||||
|
addr.addr[5] = _key[0] | 0xC0; |
||||
|
addr.addr[4] = _key[1]; |
||||
|
addr.addr[3] = _key[2]; |
||||
|
addr.addr[2] = _key[3]; |
||||
|
addr.addr[1] = _key[4]; |
||||
|
addr.addr[0] = _key[5]; |
||||
|
sd_ble_gap_addr_set(&addr); |
||||
|
|
||||
|
// 31-byte OpenHaystack advertisement payload.
|
||||
|
uint8_t adv[31]; |
||||
|
adv[0] = 0x1E; // length: 30 bytes follow
|
||||
|
adv[1] = 0xFF; // AD type: manufacturer specific data
|
||||
|
adv[2] = 0x4C; // company id: Apple (0x004C), little-endian
|
||||
|
adv[3] = 0x00; |
||||
|
adv[4] = 0x12; // Apple payload type: offline finding
|
||||
|
adv[5] = 0x19; // length of remaining offline-finding payload (25)
|
||||
|
adv[6] = 0x00; // status byte
|
||||
|
memcpy(&adv[7], &_key[6], 22); // public key bytes 6..27
|
||||
|
adv[29] = _key[0] >> 6; // top two bits of key[0]
|
||||
|
adv[30] = 0x00; // hint
|
||||
|
|
||||
|
Bluefruit.Advertising.stop(); |
||||
|
Bluefruit.Advertising.clearData(); |
||||
|
Bluefruit.ScanResponse.clearData(); |
||||
|
Bluefruit.Advertising.setType(BLE_GAP_ADV_TYPE_NONCONNECTABLE_NONSCANNABLE_UNDIRECTED); |
||||
|
Bluefruit.Advertising.setData(adv, sizeof(adv)); |
||||
|
Bluefruit.Advertising.restartOnDisconnect(false); |
||||
|
Bluefruit.Advertising.setInterval(FINDMY_ADV_INTERVAL, FINDMY_ADV_INTERVAL); |
||||
|
Bluefruit.Advertising.setFastTimeout(0); |
||||
|
|
||||
|
_started = Bluefruit.Advertising.start(0); // 0 = advertise forever
|
||||
|
} |
||||
|
|
||||
|
void FindMyBeacon::stop() { |
||||
|
if (_started) { |
||||
|
Bluefruit.Advertising.stop(); |
||||
|
_started = false; |
||||
|
} |
||||
|
} |
||||
|
|
||||
|
bool FindMyBeacon::handleCommand(const char* command, char* reply) { |
||||
|
if (memcmp(command, "set findmy.key ", 15) == 0) { |
||||
|
const char* b64 = &command[15]; |
||||
|
uint8_t decoded[40]; // 28-byte key encodes to 40 base64 chars
|
||||
|
unsigned int len = decode_base64((unsigned char *)b64, strlen(b64), (unsigned char *)decoded); |
||||
|
if (len == sizeof(_key)) { |
||||
|
memcpy(_key, decoded, sizeof(_key)); |
||||
|
save(); |
||||
|
strcpy(reply, "OK - reboot to apply"); |
||||
|
} else { |
||||
|
sprintf(reply, "Error: decoded %u bytes, expected 28", len); |
||||
|
} |
||||
|
return true; |
||||
|
} |
||||
|
if (memcmp(command, "set findmy ", 11) == 0) { |
||||
|
_enabled = memcmp(&command[11], "on", 2) == 0; |
||||
|
save(); |
||||
|
strcpy(reply, _enabled ? "OK - on, reboot to apply" : "OK - off, reboot to apply"); |
||||
|
return true; |
||||
|
} |
||||
|
if (memcmp(command, "get findmy", 10) == 0) { |
||||
|
// derived static-random MAC is key[0]|0xC0 : key[1] : ... : key[5]
|
||||
|
sprintf(reply, "> %s, mac %02X:%02X:%02X:%02X:%02X:%02X", |
||||
|
_enabled ? "on" : "off", |
||||
|
_key[0] | 0xC0, _key[1], _key[2], _key[3], _key[4], _key[5]); |
||||
|
return true; |
||||
|
} |
||||
|
return false; |
||||
|
} |
||||
|
|
||||
|
#endif |
||||
@ -0,0 +1,41 @@ |
|||||
|
#pragma once |
||||
|
|
||||
|
#include <stdint.h> |
||||
|
|
||||
|
// Apple FindMy / OpenHaystack locator beacon for nRF52 (Adafruit Bluefruit).
|
||||
|
//
|
||||
|
// Advertises a static, non-connectable OpenHaystack payload derived from a 28-byte
|
||||
|
// advertising public key. The matching private key is held off-device (in the user's
|
||||
|
// OpenHaystack / macless-haystack setup) and is required to actually locate the device.
|
||||
|
//
|
||||
|
// The algorithm is ported from https://github.com/pix/heystack-nrf5x (nRF5 SDK) and
|
||||
|
// reimplemented here on the Bluefruit advertising API used by MeshCore.
|
||||
|
//
|
||||
|
// Self-contained: it persists its own config to "/findmy" on the internal filesystem and
|
||||
|
// parses its own "set/get findmy" CLI commands, so it needs no changes to the shared
|
||||
|
// NodePrefs/CommonCLI code. Provisioning: `set findmy.key <base64>`, `set findmy on`, reboot.
|
||||
|
//
|
||||
|
// Intended for always-on roles (repeater/sensor) where BLE is otherwise unused. It is not
|
||||
|
// meant to run alongside the phone-companion firmware, which needs BLE for its own link.
|
||||
|
class FindMyBeacon { |
||||
|
bool _started = false; |
||||
|
uint8_t _enabled = 0; |
||||
|
uint8_t _key[28] = {0}; // OpenHaystack advertising public key
|
||||
|
|
||||
|
bool load(); // read "/findmy" into _enabled/_key
|
||||
|
void save(); // write "/findmy"
|
||||
|
|
||||
|
public: |
||||
|
// Load persisted config and, if enabled with a key set, start advertising. Call once at
|
||||
|
// boot after the internal filesystem is mounted. tx_dbm is the advertising TX power.
|
||||
|
void begin(int8_t tx_dbm = 4); |
||||
|
void stop(); |
||||
|
bool isRunning() const { return _started; } |
||||
|
|
||||
|
// Handle "set findmy.key <b64>", "set findmy on|off", "get findmy".
|
||||
|
// Returns true if the command was recognised (and reply filled), false otherwise.
|
||||
|
bool handleCommand(const char* command, char* reply); |
||||
|
}; |
||||
|
|
||||
|
// Single shared instance (defined in FindMyBeacon.cpp).
|
||||
|
extern FindMyBeacon findmy_beacon; |
||||
Loading…
Reference in new issue