About this project

PadSpan HA is a Home Assistant integration that provides room-level Bluetooth Low Energy (BLE) presence tracking, going beyond simple home/away detection. It updates device locations every 5 seconds and offers interactive floor plans, 3D multi-floor visualizations, a full calibration system, and 19 dedicated views. Key features include: - **Presence Tracking**: Room-level tracking with Kalman-filtered RSSI smoothing, home/away detection, follow mode with email alerts, and multi-device simultaneous tracking. - **Device Identity**: Stable device identity (padspan_id) that survives MAC rotation and iBeacon UUID changes, with O(1) resolution from volatile keys. - **Floor Plans & Maps**: Upload architectural plans, draw room boundaries, place scanners, and view 2D/3D maps with zoom/pan. - **Calibration**: Walk-around fingerprint collection, k-NN matching, OLS path-loss fitting, coverage heatmaps, and cross-validation. - **Multi-Floor Intelligence**: Floor-transition learning, cross-floor attenuation, and outdoor penalties. - **Phone & Watch Tracking**: Guided setup for Android (HA Companion App iBeacon), iPhone/iPad/Apple Watch (IRK via irk-capture), Tile/Chipolo (automatic), AirTag/SmartTag (probabilistic via MAC Rotation Bridging). - **Scanner Management**: Auto-discovery of HA Bluetooth proxies, Bermuda proxies, and ESPresense nodes via MQTT; tested with 20+ ESP32 boards. - **Alerts & Automation**: Email alerts, HA entities (area sensors, distance sensors, device trackers, binary sensors), and WebSocket API. - **Analytics**: Insights (time-in-room, entry counts), Busy Times (room occupancy by hour), and Locate (wayfinding). - **Atlas Device Map**: Place and control real devices (lights, locks, sensors) on an isometric map, with WLED control, doors/windows as RF barriers, and Automorph visual effects. - **UI & Experience**: Pure Live immersive dashboard, 19 views, onboarding wizard, training hub with 16 walkthroughs, sample mode, and 11 languages. Editions: PadSpan HA (free, GPL v3), PadSpan Pro (licence key unlocks gated features), PadSpan Bright (separate lighter HACS listing for Atlas only), PadSpan Bright Pro. Installation via HACS or manual. Requires Home Assistant 2024.1+ and at least one BLE scanner. Includes opt-in usage reporting with privacy controls.