Match API defaults and interval fallback to the public implementation

Author: Mattboxx

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased — Publication consistency
 
+- Match the API reference to actual config defaults and invalid-interval fallback;
+  clarify that callers must serialize lifecycle updates. Implementation unchanged.
 - Align Arduino's NimBLE dependency range with PlatformIO (`>=2.5.0 && <3.0.0`).
 - Distinguish CI-built targets from experimental, unverified chips; retain all
   code paths without promising on-air verification or certification.

docs/API.md

@@ -6,17 +6,17 @@
 | --- | ---: | --- |
 | `appleAdvertisementKeyBase64` | `""` | 28-byte Apple public advertisement key encoded as 40 Base64 characters; empty disables Apple |
 | `googleAdvertisementEidHex` | `""` | 20-byte Google advertisement EID encoded as 40 hexadecimal characters; empty disables Google |
-| `advertisingIntervalMs` | `2000` | BLE interval while stationary, clamped to the controller range 20–10240 ms |
+| `advertisingIntervalMs` | `2000` | Stationary BLE interval: valid range 20–10240 ms; out-of-range values reset to 2000 ms, not the nearest bound |
 | `txPowerDbm` | `0` | Requested advertising power, mapped to the nearest ESP controller level |
 | `providerWindowMs` | `6000` | Requested provider window; clamped to at least three stationary advertisement intervals (and at least 1 second) |
 | `accelerometerEnabled` | `false` | Enables LIS3DH/LIS2DH/LIS2DH12 motion detection |
-| `accelerometerWire` | `&Wire` | I2C bus instance; point it to `Wire1` or another initialized bus when required |
+| `accelerometerWire` | `nullptr` | Null selects `Wire` when the built-in driver is enabled; pass `&Wire1` or another bus when required |
 | `initializeAccelerometerBus` | `true` | Calls `begin(SDA, SCL)` on the selected bus; set false if the host firmware already initialized it |
 | `accelerometerSda` | `8` | I2C SDA pin |
 | `accelerometerScl` | `9` | I2C SCL pin |
 | `accelerometerAddress` | `0` | `0` probes `0x18`/`0x19`; otherwise forces the supplied address |
 | `motionThreshold` | `320` | Motion delta threshold; raise it to reject small vibrations |
-| `motionIntervalMs` | `200` | BLE interval while movement is active |
+| `motionIntervalMs` | `200` | Motion BLE interval: valid range 20–10240 ms; out-of-range values reset to 200 ms |
 | `motionHoldMs` | `30000` | Time to keep the motion interval after the last detected movement |
 | `motionDetectedCallback` | `nullptr` | Optional no-argument callback returning true on motion; supports any external sensor or application state |
 | `backgroundTask` | `true` | Runs the scheduler in an internal FreeRTOS task |
@@ -88,7 +88,7 @@ when another module needs scanning, client, or GATT-server roles.
 
 ## Threading and ownership
 
-Configuration updates are serialized by `reconfigure()`. Do not call
+Configuration updates stop and restart the private scheduler. Do not call
 `reconfigure()`, `setKeys()`, and `end()` concurrently from multiple tasks;
 serialize them in the host application when several configuration sources are
 present. The library owns legacy advertising while it is running but does not

test/check_metadata.py

@@ -18,4 +18,12 @@
 minimum = dependency[1:]
 next_major = int(minimum.split(".")[0]) + 1
 assert properties["depends"] == f"NimBLE-Arduino (>={minimum} && <{next_major}.0.0)"
+
+# Compare documented defaults with the public header, not a second value list.
+header = (ROOT / "src/FindMyAdv.h").read_text(encoding="utf-8")
+api = (ROOT / "docs/API.md").read_text(encoding="utf-8")
+fields = re.findall(r'^\s*(?:const char\s*\*|TwoWire\s*\*|u?int(?:8|16|32)_t|bool)\s*(\w+)\s*=\s*([^;]+);', header, re.M)
+for name, default in fields:
+    assert f"| `{name}` | `{default.strip()}` |" in api, f"API default drift: {name}"
 print("FindMyAdv metadata: names, version, canonical URLs and dependency ranges agree")
+print(f"FindMyAdv API: {len(fields)} documented defaults match the public header")