Skip to content

Commit 77e4656

Browse files
MattboxxMattboxx
committed
new
1 parent ef7f639 commit 77e4656

24 files changed

Lines changed: 1435 additions & 1 deletion

‎.gitattributes‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,8 @@
1-
# Auto detect text files and perform LF normalization
21
* text=auto
2+
*.cpp text eol=lf
3+
*.h text eol=lf
4+
*.ini text eol=lf
5+
*.json text eol=lf
6+
*.md text eol=lf
7+
*.yml text eol=lf
8+

‎.github/workflows/build.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: Build and validate
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
permissions:
8+
contents: read
9+
10+
jobs:
11+
esp32-builds:
12+
runs-on: ubuntu-latest
13+
strategy:
14+
fail-fast: false
15+
matrix:
16+
environment: [esp32, esp32c3, esp32s3, esp32c6]
17+
steps:
18+
- uses: actions/checkout@v6
19+
- uses: actions/setup-python@v6
20+
with:
21+
python-version: "3.12"
22+
cache: pip
23+
- run: python -m pip install platformio==6.1.19
24+
- run: pio run -d ci -e ${{ matrix.environment }}
25+
26+
package:
27+
runs-on: ubuntu-latest
28+
steps:
29+
- uses: actions/checkout@v6
30+
- uses: actions/setup-python@v6
31+
with:
32+
python-version: "3.12"
33+
cache: pip
34+
- run: python -m pip install platformio==6.1.19
35+
- run: pio pkg pack . --output FindMyAdv.tar.gz
36+
- uses: actions/upload-artifact@v7
37+
with:
38+
name: FindMyAdv-package
39+
path: FindMyAdv.tar.gz

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
.pio/
2+
*.tar.gz
3+
*.zip
4+
FindMyAdv-configured.zip
5+

‎CHANGELOG.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Changelog
2+
3+
All notable changes to FindMyAdv are documented here. The format follows
4+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
5+
[Semantic Versioning](https://semver.org/).
6+
7+
## [1.0.0] - 2026-07-14
8+
9+
### Added
10+
11+
- Apple Find My and Google Find Hub legacy advertising.
12+
- Automatic Apple/Google provider rotation.
13+
- ESP32/ESP32-C3/ESP32-S3 Bluedroid backend.
14+
- ESP32-C6/ESP32-H2 NimBLE backend.
15+
- Background FreeRTOS scheduler with optional manual polling.
16+
- Runtime `setKeys()` and complete `reconfigure()` APIs.
17+
- Optional LIS3DH/LIS2DH/LIS2DH12 dynamic advertising rate.
18+
- Pluggable motion callback for any other sensor or application state.
19+
- English and Italian documentation and three integration examples.

‎CONTRIBUTING.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# Contributing
2+
3+
Contributions are welcome through GitHub issues and pull requests.
4+
5+
## Before opening an issue
6+
7+
- Remove all real Apple advertisement keys, Google EIDs, account details, and
8+
private network addresses from logs and examples.
9+
- State the exact ESP chip, board, Arduino core, PlatformIO platform, and
10+
whether another component initializes or advertises BLE.
11+
- Include the return value of `begin()`, `status()`, and `lastError()`.
12+
13+
## Development checks
14+
15+
Build the standalone integration project for every maintained environment:
16+
17+
```bash
18+
pio run -d ci -e esp32
19+
pio run -d ci -e esp32c3
20+
pio run -d ci -e esp32s3
21+
pio run -d ci -e esp32c6
22+
```
23+
24+
New public API must be documented in `docs/API.md`, and behavior changes must
25+
be added to `CHANGELOG.md`. Examples must use empty placeholder keys.
26+
27+
## Compatibility policy
28+
29+
Patch releases fix bugs without changing the public API. Minor releases add
30+
backward-compatible options. Breaking API or configuration changes require a
31+
new major version.
32+

‎LICENSE‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Find_My_Web contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.
22+

‎README.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# FindMyAdv
2+
3+
Reusable Apple Find My and Google Find Hub BLE advertising for Arduino on
4+
BLE-capable ESP32 chips. Add one `begin()` call to an existing firmware; the
5+
library runs its scheduler in a private FreeRTOS task and does not require code
6+
in `loop()`.
7+
8+
`begin()` may be called from `setup()` or later, after the host application has
9+
loaded credentials or completed its own initialization. `end()` stops the
10+
module, and a later `begin()` starts it again.
11+
12+
FindMyAdv is an unofficial, open-source interoperability project. It is not
13+
affiliated with or endorsed by Apple, Google, or Espressif.
14+
15+
Italian documentation: [`docs/README.it.md`](docs/README.it.md)
16+
Complete API reference: [`docs/API.md`](docs/API.md)
17+
18+
Additional references:
19+
20+
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
21+
- [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md)
22+
- [`docs/RELEASING.md`](docs/RELEASING.md)
23+
- [`CONTRIBUTING.md`](CONTRIBUTING.md)
24+
- [`SECURITY.md`](SECURITY.md)
25+
26+
## Supported hardware
27+
28+
| Chip | Bluetooth | Backend | Status |
29+
| --- | --- | --- | --- |
30+
| ESP32 | BLE 4.2 | Bluedroid | Supported |
31+
| ESP32-C3 | BLE 5 | Bluedroid | Supported |
32+
| ESP32-S3 | BLE 5 | Bluedroid | Supported |
33+
| ESP32-C6 | BLE 5 | NimBLE | Supported |
34+
| ESP32-C2 | BLE 5 | Selected from Arduino core | Compatible; not yet in the release build matrix |
35+
| ESP32-C5 / ESP32-C61 | BLE | Selected from Arduino core | Compatible; requires a supporting Arduino core |
36+
| ESP32-H2 | BLE 5 | NimBLE | Compatible; build with a supporting Arduino core |
37+
| ESP8266 / ESP32-S2 / ESP32-P4 | No Bluetooth radio | — | Not possible |
38+
39+
The current standalone firmware validates the ESP32, C3, S3, and C6 targets.
40+
Backend selection uses `CONFIG_BT_NIMBLE_ENABLED` or
41+
`CONFIG_BT_BLUEDROID_ENABLED`, rather than a hard-coded chip list. New ESP32
42+
variants therefore work when their Arduino core exposes one of those supported
43+
BLE hosts.
44+
45+
## Installation
46+
47+
### PlatformIO project
48+
49+
After the first public Registry release, installation is a single dependency:
50+
51+
```ini
52+
lib_deps = mattbox03/FindMyAdv@^1.0.0
53+
```
54+
55+
The GitHub source can also be used directly:
56+
57+
```ini
58+
lib_deps = https://github.com/mattbox03/FindMyAdv.git
59+
```
60+
61+
For a local checkout, copy the complete `FindMyAdv` directory into the
62+
project's `lib` directory:
63+
64+
```text
65+
your-project/
66+
|-- lib/
67+
| `-- FindMyAdv/
68+
| |-- library.json
69+
| `-- src/
70+
`-- src/
71+
`-- main.cpp
72+
```
73+
74+
### Arduino IDE
75+
76+
Put the `FindMyAdv` directory in the Arduino libraries directory, or create a
77+
ZIP whose root directory is named `FindMyAdv` and use **Sketch > Include
78+
Library > Add .ZIP Library**.
79+
80+
## Minimal integration
81+
82+
```cpp
83+
#include <Arduino.h>
84+
#include <FindMyAdv.h>
85+
86+
void setup() {
87+
FindMyAdvConfig tracking;
88+
tracking.appleAdvertisementKeyBase64 = "APPLE_BASE64_KEY_OR_EMPTY";
89+
tracking.googleAdvertisementEidHex = "GOOGLE_40_HEX_EID_OR_EMPTY";
90+
tracking.advertisingIntervalMs = 2000;
91+
tracking.txPowerDbm = 0;
92+
93+
if (!FindMyAdv.begin(tracking)) {
94+
Serial.println(FindMyAdv.lastError());
95+
}
96+
}
97+
98+
void loop() {
99+
// Existing application code: FindMyAdv needs no calls here.
100+
}
101+
```
102+
103+
Either key may be empty. With both keys configured, the library time-slices
104+
the Apple and Google legacy advertising frames. With one key, it advertises
105+
only that provider.
106+
107+
## Change keys or settings at runtime
108+
109+
The library copies all input strings, so temporary `String` values and values
110+
read from a web form, MQTT, Preferences/NVS, or a configuration file are safe:
111+
112+
```cpp
113+
String appleFromWeb = request->arg("apple_key");
114+
String googleFromWeb = request->arg("google_eid");
115+
116+
if (!FindMyAdv.setKeys(appleFromWeb.c_str(), googleFromWeb.c_str())) {
117+
Serial.println(FindMyAdv.lastError());
118+
}
119+
```
120+
121+
To change intervals, TX power, accelerometer settings, and keys together:
122+
123+
```cpp
124+
FindMyAdvConfig updated;
125+
updated.appleAdvertisementKeyBase64 = appleFromWeb.c_str();
126+
updated.googleAdvertisementEidHex = googleFromWeb.c_str();
127+
updated.advertisingIntervalMs = 1000;
128+
updated.txPowerDbm = 3;
129+
FindMyAdv.reconfigure(updated);
130+
```
131+
132+
Persistence deliberately remains under application control. Save the values
133+
with `Preferences`, your existing settings manager, or another secure storage
134+
mechanism, then pass them to `begin()` at boot. This avoids imposing a Wi-Fi
135+
portal, filesystem, network service, or credential format on the host firmware.
136+
137+
## Optional motion-based advertising
138+
139+
LIS3DH, LIS2DH, and LIS2DH12 accelerometers are supported at I2C address `0x18`
140+
or `0x19`. Set address `0` to probe both automatically:
141+
142+
```cpp
143+
tracking.accelerometerEnabled = true;
144+
tracking.accelerometerWire = &Wire; // use &Wire1 for a separate application bus
145+
tracking.initializeAccelerometerBus = true;
146+
tracking.accelerometerSda = 8;
147+
tracking.accelerometerScl = 9;
148+
tracking.accelerometerAddress = 0;
149+
tracking.motionIntervalMs = 200;
150+
tracking.motionHoldMs = 30000;
151+
tracking.motionThreshold = 320;
152+
```
153+
154+
If the host firmware already initialized that I2C bus, set
155+
`initializeAccelerometerBus = false` so the library does not change its pins or
156+
clock configuration.
157+
158+
Any other motion sensor is supported through a callback, without modifying the
159+
library:
160+
161+
```cpp
162+
bool moved() {
163+
return myImu.motionInterruptActive();
164+
}
165+
166+
tracking.motionDetectedCallback = moved;
167+
```
168+
169+
## Integration limits
170+
171+
- Wi-Fi, sensors, displays, MQTT, web servers, and normal application tasks can
172+
run alongside FindMyAdv.
173+
- The library owns the controller's legacy BLE advertising while running. An
174+
application that already advertises a BLE GATT service must coordinate that
175+
advertising explicitly; two independent modules cannot transparently own the
176+
same legacy advertising set.
177+
- BLE connections may interrupt or alter advertising depending on the chip,
178+
controller resources, and application stack.
179+
- No radio can advertise during ESP deep sleep. Stop the library before sleep
180+
and call `begin()` again after wake-up.
181+
- Advertising two providers is time-slicing, not two simultaneous legacy radio
182+
packets. `providerWindowMs` controls the rotation window.
183+
184+
## Security
185+
186+
Apple advertisement keys and Google EIDs identify a tracker. Do not publish
187+
real keys in source control, logs, examples, issue reports, or public binaries.
188+
The library never sends keys over Wi-Fi and does not persist them by itself.
189+
190+
## Examples
191+
192+
- `Minimal`: one-call integration.
193+
- `DynamicKeys`: load keys from Preferences and replace them at runtime.
194+
- `ManualPolling`: disable the FreeRTOS scheduler task and call `poll()` from
195+
an existing cooperative loop.
196+
- `CustomMotionSource`: use any IMU, GPIO, or application event for dynamic
197+
advertising speed.
198+
199+
## License
200+
201+
MIT. See [`LICENSE`](LICENSE).

‎SECURITY.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Security policy
2+
3+
Tracker advertisement keys are sensitive identifiers. Never include real keys
4+
in public issues, pull requests, screenshots, logs, example sketches, or test
5+
binaries.
6+
7+
For a suspected vulnerability, contact the repository owner privately through
8+
the security-reporting mechanism shown on GitHub. Include the affected library
9+
version, ESP target, and a minimal reproduction using synthetic keys.
10+
11+
FindMyAdv does not persist or transmit configuration over IP. Security of web
12+
forms, MQTT, Preferences/NVS, filesystems, and remote update mechanisms remains
13+
the responsibility of the host firmware.
14+

‎ci/platformio.ini‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
[platformio]
2+
default_envs = esp32c3
3+
src_dir = src
4+
lib_extra_dirs = ..
5+
6+
[env]
7+
framework = arduino
8+
monitor_speed = 115200
9+
build_flags = -DCORE_DEBUG_LEVEL=0
10+
11+
[env:esp32]
12+
platform = espressif32@7.0.1
13+
board = esp32dev
14+
15+
[env:esp32c3]
16+
platform = espressif32@7.0.1
17+
board = esp32-c3-devkitm-1
18+
19+
[env:esp32s3]
20+
platform = espressif32@7.0.1
21+
board = lolin_s3_mini
22+
23+
[env:esp32c6]
24+
platform = https://github.com/pioarduino/platform-espressif32/releases/download/55.03.39/platform-espressif32.zip
25+
platform_packages =
26+
framework-arduinoespressif32 @ https://github.com/espressif/arduino-esp32/releases/download/3.3.9/esp32-core-3.3.9.tar.xz
27+
board = esp32-c6-devkitc-1
28+
board_upload.flash_size = 4MB
29+

‎ci/src/main.cpp‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#include <Arduino.h>
2+
#include <FindMyAdv.h>
3+
4+
void setup() {
5+
FindMyAdvConfig config;
6+
config.appleAdvertisementKeyBase64 = "";
7+
config.googleAdvertisementEidHex = "";
8+
config.backgroundTask = false;
9+
FindMyAdv.begin(config);
10+
}
11+
12+
void loop() {
13+
FindMyAdv.poll();
14+
delay(25);
15+
}
16+

0 commit comments

Comments
 (0)