{"id":45143015,"url":"https://github.com/gbroeckling/padspanha","last_synced_at":"2026-06-12T03:01:23.068Z","repository":{"id":336591612,"uuid":"1150153711","full_name":"gbroeckling/padspanHA","owner":"gbroeckling","description":"The most comprehensive BLE room-presence tracking system for Home Assistant — room-level tracking, 3D floor plans, calibration, follow mode, 21 views","archived":false,"fork":false,"pushed_at":"2026-04-15T22:44:18.000Z","size":90466,"stargazers_count":136,"open_issues_count":3,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-15T23:32:38.496Z","etag":null,"topics":["ai-assisted","ble","bluetooth","claude","esp32","esphome","floor-plan","hacs","home-assistant","home-automation","iot","presence-detection","room-tracking","smart-home"],"latest_commit_sha":null,"homepage":"https://github.com/gbroeckling/padspanHA/discussions/2","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gbroeckling.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-05T00:10:53.000Z","updated_at":"2026-04-15T22:44:21.000Z","dependencies_parsed_at":"2026-04-20T09:01:17.036Z","dependency_job_id":null,"html_url":"https://github.com/gbroeckling/padspanHA","commit_stats":null,"previous_names":["gbroeckling/padspanha"],"tags_count":860,"template":false,"template_full_name":null,"purl":"pkg:github/gbroeckling/padspanHA","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbroeckling%2FpadspanHA","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbroeckling%2FpadspanHA/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbroeckling%2FpadspanHA/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbroeckling%2FpadspanHA/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gbroeckling","download_url":"https://codeload.github.com/gbroeckling/padspanHA/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbroeckling%2FpadspanHA/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32040353,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T00:18:06.643Z","status":"online","status_checked_at":"2026-04-20T02:00:06.527Z","response_time":94,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assisted","ble","bluetooth","claude","esp32","esphome","floor-plan","hacs","home-assistant","home-automation","iot","presence-detection","room-tracking","smart-home"],"created_at":"2026-02-20T01:00:42.803Z","updated_at":"2026-06-12T03:01:23.055Z","avatar_url":"https://github.com/gbroeckling.png","language":"JavaScript","funding_links":["https://www.paypal.com/donate/?hosted_button_id=W489P2RXBMXKW"],"categories":[],"sub_categories":[],"readme":"# PadSpan™ HA\n\n### The most comprehensive BLE room-presence system for Home Assistant\n\nPadSpan™ HA goes far beyond \"home or away.\" It tells you **which room** every Bluetooth device is in — updated every 5 seconds — with interactive floor plans, 3D multi-floor visualizations, a full calibration system, and 22 dedicated views. No other Home Assistant BLE integration comes close.\n\n![3D multi-floor tracking with live RSSI heatmap overlay](images/overview-3d-multifloor.jpg)\n\n---\n\n## Why PadSpan?\n\nMost BLE presence integrations give you a config flow and a sensor. PadSpan gives you a **complete tracking workstation** — floor plan editor, room boundary polygons, 3D isometric maps, walk-around calibration, follow mode with email alerts, a training hub, and a full sample/demo mode so you can explore every feature before plugging in hardware.\n\nIt works with your existing BLE scanners (ESPresense, Bermuda proxies, or any HA Bluetooth proxy). No custom firmware. No cloud dependency. Everything runs locally.\n\n---\n\n## Screenshots\n\n| 3D Multi-Floor Tracking | 3D Heatmap + Signal Overlay |\n|:-:|:-:|\n| ![Live multi-floor isometric view with tracked devices across 3 floors](images/overview-3d-multifloor.jpg) | ![3D overview with RSSI heatmap crosshatch and device positions](images/overview-3d-heatmap.jpg) |\n\n| Maps Library | Scanner-to-Device Graph |\n|:-:|:-:|\n| ![9 uploaded floor plans organized by floor](images/maps-library-live.jpg) | ![Bipartite graph showing scanner-device BLE connections with RSSI](images/bluetooth-scanner-graph.jpg) |\n\n| Traceback Playback + Distance Traveled | Beacon Tune Calibration |\n|:-:|:-:|\n| ![NVR-style playback timeline with per-device distance and reliability](images/traceback-distance.jpg) | ![3D beacon tune with floor stack, auto-cal, and live device positions](images/beacon-tune-calibration.jpg) |\n\n| Pure Live — Immersive Dashboard | Traceback — Movement Playback |\n|:-:|:-:|\n| ![Full-screen 3D map with pan/zoom, floating stats, scanner sonar, and tracked device strip](images/purelive-immersive.png) | ![NVR-style replay with 3D map, timeline scrubber, and distance travelled per device](images/traceback-playback-3d.png) |\n\n| Sandbox Developer Tools | Floor Plan Editor |\n|:-:|:-:|\n| ![Experimental playground — state inspector, floor towers, live signal bars, raw snapshot](images/sandbox-developer.png) | ![Room boundaries on architectural blueprint](images/floor-plan-edit.png) |\n\n---\n\n## Feature Highlights\n\n### Presence Tracking\n- Room-level BLE device tracking (5-second refresh)\n- **Follow mode** — animated room map + movement timeline for any tracked device\n- Multi-device simultaneous tracking with per-device email alerts (60 s rate limit)\n- Kalman-filtered RSSI smoothing (replaces simple moving averages)\n- Home/away detection with HA binary sensor entities\n- **Phone \u0026 watch tracking** — guided setup wizard with [irk-capture](https://github.com/DerekSeaman/irk-capture) integration, HA Companion App iBeacon for Android, and IRK resolution for Apple devices\n- Private BLE address resolution (iBeacon UUID + IRK support)\n- **Occupancy estimation** — hybrid people counting combining BLE devices, HA person entities, occupancy/motion sensors, and WiFi client counts with a trainable multiplier and RSSI co-location clustering\n\n### Device Identity\n- **Stable device identity (padspan_id)** — every physical device gets an immutable ID that survives MAC rotation, iBeacon UUID changes, and firmware updates\n- O(1) identity resolution from any volatile key (MAC, iBeacon, canonical_id)\n- Automatic migration from older object/tag systems\n- Interactive device registry: merge duplicates, add identities, relabel, delete\n\n### Floor Plans \u0026 Maps\n- Upload architectural floor plans (PNG/JPG) with auto-scaling\n- **Two-point measure tool** for precise real-world scale calibration with aspect ratio validation\n- Draw room boundary polygons directly over blueprints\n- Multi-floor **3D isometric visualization** with live object positions\n- **2D flat map mode** with zoom/pan and toggle filters (scanners, tagged, unknown, rooms)\n- Drag-and-place scanner markers with 3-digit radio IDs\n- Auto-detect stale or missing radios on your map\n- Master map alignment for multi-floor coordinate consistency\n\n### Calibration\n- Walk-around fingerprint collection with a **standalone phone-friendly panel**\n- k-NN fingerprint matching + OLS path-loss model fitting per scanner\n- Coverage heatmap with guided \"walk here next\" target suggestions\n- Leave-one-out cross-validation for model quality scoring\n- 3D isometric tune view with draggable receiver markers\n\n### Multi-Floor Intelligence\n- **Floor-transition learning** — adaptive dwell-based velocity gate prevents phantom floor changes\n- Learned cross-floor RSSI attenuation\n- Outdoor penalties (0.30× Gaussian damping) for exterior boundary rooms\n\n### Phone \u0026 Watch Tracking\n\nTracking phones is the hardest problem in BLE presence — they rotate their Bluetooth address every ~15 minutes specifically to prevent tracking. PadSpan offers multiple paths depending on your device:\n\n| Device | Easiest Method | What You Need |\n|--------|---------------|---------------|\n| **Android phone** | HA Companion App iBeacon | Install app, enable BLE Transmitter. Done. |\n| **iPhone / iPad** | IRK via [irk-capture](https://github.com/DerekSeaman/irk-capture) | Spare ESP32, flash irk-capture, pair once, paste IRK |\n| **Apple Watch** | IRK via irk-capture | Same as iPhone — pair watch to irk-capture ESP32 |\n| **Tile / Chipolo** | Automatic (iBeacon) | Stable UUID — just works, tag once and the name sticks across rotations |\n| **AirTag** | Probabilistic (experimental) | Enable **Apple Device Classification** + **MAC Rotation Bridging** in Settings → Features. AirTags rotate both MAC and Find My key every ~15 min and expose no stable identifier, so bridging links rotations by advertisement pattern — works while in continuous range, may mis-link in crowded RF environments |\n| **SmartTag** (Samsung) | Probabilistic | Same as AirTag — no stable identifier in the air, relies on MAC Rotation Bridging |\n| **AirPods** | Apple auto-classification | Detected and labeled automatically when feature enabled (display only — does not solve identity) |\n\nThe **Phone Setup Wizard** (experimental) guides you through each path with step-by-step instructions. If you have an irk-capture ESP32 on your network, PadSpan auto-detects captured IRKs — no manual hex pasting.\n\nFor devices where you can't get an IRK, the experimental **MAC Rotation Bridging** feature matches advertisement patterns across address rotations to maintain tracking continuity.\n\n\u003e **Acknowledgement:** The IRK extraction workflow is built on [Derek Seaman's irk-capture](https://github.com/DerekSeaman/irk-capture) — an ingenious ESP32 tool that emulates BLE peripherals to extract Identity Resolving Keys during pairing. It's what makes practical phone tracking in Home Assistant possible without rooting devices or owning a Mac.\n\n### Scanner Hardware \u0026 Management\n- **Tested with 20+ ESP32 boards** — the antenna matters more than the chip. Boards with full-size external antennas consistently outperform chip/PCB antennas for room-level accuracy\n- Top picks: ESP32-S3 with Ethernet + antenna, ESP32-S3 with WiFi + antenna, ESP32-C3 with antenna\n- Auto-discover BLE scanners from Home Assistant integrations\n- Per-scanner signal quality metrics and coverage analysis\n- WiFi SSID, IP address, and connection type display\n- Assign scanners to floors and rooms on the map\n\n### Alerts \u0026 Automation\n- Email alerts on room change (per device, 60-second rate limit)\n- HA entities: **area sensors**, **distance sensors**, **device trackers**, **binary sensors**\n- Full WebSocket API for custom dashboards and automation\n\n### UI \u0026 Experience\n- **Pure Live mode** — immersive full-screen 3D dashboard with pan/zoom, floating glass overlays, and collapsible info panels\n- **22 dedicated views** with Basic and Advanced modes\n- **5-step onboarding wizard** with auto-detection and progress tracking\n- Dark forest-green theme designed for always-on displays\n- Built-in **Training Hub** with 14 animated walkthroughs + full manual\n- **Sample mode** — fully functional demo with synthetic data, no hardware needed\n- **11 languages**: English, Spanish, French, German, Italian, Portuguese, Dutch, Chinese, Japanese, Korean, Russian\n- Standalone calibration panel optimized for phone use during walk-around collection\n- **NVR-style movement playback** — replay tracked device movement on the 3D map\n\n### Experimental Features (Settings → Features)\n- **Phone Setup Wizard** — guided flow for tracking phones and watches. Auto-detects [irk-capture](https://github.com/DerekSeaman/irk-capture) ESP32 devices on your network and walks through IRK extraction step by step. Also shows the easy Android path (HA Companion App iBeacon) and Apple IRK options. Credit to [Derek Seaman](https://github.com/DerekSeaman) for the excellent irk-capture tool that makes IRK extraction practical for everyone.\n- **MAC Rotation Bridging** — when a phone's Bluetooth address rotates (every ~15 min), PadSpan matches advertisement characteristics (company ID, services, signal pattern) to tentatively link old and new addresses. Bridges the tracking gap without requiring an IRK. Probabilistic — may occasionally link wrong devices.\n- **Apple Device Classification** — automatically labels Apple devices as iPhone, iPad, Apple Watch, AirPods, or AirTag by decoding Bluetooth Continuity protocol messages. Display-only — does not affect tracking or identity.\n- **Radio Map** — RSSI heatmap overlay using inverse distance weighting\n- **Distortion Map** — k-NN prediction vs reality mismatch visualization\n- **Trackability Rating** — per-device Easy/Medium/Hard scoring\n- **Walk-to-Identify** — discover unknown devices by correlating walking motion\n- **Compass Ring Calibration** — structured 360° RSSI collection\n- **Replay Timeline** — enhanced playback with scoring explainability\n\n---\n\n## How It Compares\n\n| Feature | PadSpan HA | Bermuda | Room Assistant | ESPresense |\n|:--------|:----------:|:-------:|:--------------:|:----------:|\n| Room-level tracking | ✅ | ✅ | ✅ | ✅ |\n| Phone tracking wizard | ✅ | — | — | — |\n| IRK capture integration | ✅ | — | — | ✅ |\n| MAC rotation bridging | ✅ | — | — | — |\n| Apple device auto-classify | ✅ | — | — | ✅ |\n| Visual floor plans | ✅ | — | — | — |\n| 3D multi-floor maps | ✅ | — | — | — |\n| 2D flat map + zoom/pan | ✅ | — | — | — |\n| Room boundary editor | ✅ | — | — | — |\n| Fingerprint calibration | ✅ | — | — | — |\n| Hybrid occupancy counting | ✅ | — | — | — |\n| Stable device identity | ✅ | — | — | — |\n| Training hub (14 walkthroughs) | ✅ | — | — | — |\n| Follow mode + email alerts | ✅ | — | — | — |\n| Onboarding wizard | ✅ | — | — | — |\n| Movement history playback | ✅ | — | — | — |\n| Sample/demo mode | ✅ | — | — | — |\n| Multi-language (11) | ✅ | — | — | — |\n| Dedicated UI views | 22 | Config flow | MQTT config | Web UI |\n| HA sensor entities | ✅ | ✅ | ✅ | ✅ |\n| Distance estimation | ✅ | ✅ | — | ✅ |\n| Kalman RSSI filtering | ✅ | — | — | — |\n| Works with ESPHome proxies | ✅ | ✅ | — | ✗ (own firmware) |\n\n---\n\n## Installation\n\n### Via HACS (recommended)\n\n1. Open HACS in your Home Assistant instance\n2. Add this repository as a **custom repository** (Integration type)\n3. Search for and install **PadSpan HA**\n4. **Restart Home Assistant completely** (Settings → System → Restart)\n5. Add the integration: Settings → Devices \u0026 Services → Add Integration → PadSpan HA\n\n### Manual\n\n1. Download the [latest release](https://github.com/gbroeckling/padspanHA/releases/latest)\n2. Extract `custom_components/padspan_ha/` into your HA `custom_components/` directory\n3. Restart Home Assistant\n4. Add the integration: Settings → Devices \u0026 Services → Add Integration → PadSpan HA\n\n---\n\n## Requirements\n\n- Home Assistant **2024.1** or newer\n- At least one BLE scanner (ESPresense, Bermuda proxy, or HA Bluetooth proxy)\n- HACS (recommended for easy installation and updates)\n\n---\n\n## Quick Start\n\n1. Install via HACS and restart HA\n2. Add the PadSpan HA integration\n3. Open the **PadSpan HA** panel in the sidebar\n4. The **onboarding wizard** guides you through 5 steps: upload a map, set scale, draw rooms, place scanners, calibrate\n5. Try **Sample mode** (top-right toggle) to explore every feature with demo data\n6. Switch to **Live mode** when ready — your BLE scanners are auto-discovered\n7. Tag your devices, upload a floor plan, and start tracking\n\n---\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Getting Started](docs/GETTING_STARTED.md) | First 30 minutes: install, explore, track |\n| [Floor Plan Setup](docs/FLOOR_PLAN_SETUP.md) | Upload, draw rooms, place scanners, set scale |\n| [Troubleshooting](docs/90_TROUBLESHOOTING.md) | Common issues and fixes |\n| [Architecture](docs/00_REPO_LOGIC_OVERVIEW.md) | High-level codebase architecture |\n| [WebSocket API](docs/02_WEBSOCKET_API.md) | API reference for custom integrations |\n| [Changelog](CHANGELOG.md) | Full version history |\n\nThe **Training Hub** inside PadSpan has 14 animated walkthroughs covering every feature — from BLE basics to Private BLE/IRK setup.\n\n---\n\n## Development\n\nPadSpan HA is built by [Garry Broeckling](https://github.com/gbroeckling) — a 30+ year veteran of coding and scripting who has never claimed to be a fast typist. All architecture, product decisions, testing, and releases are human-directed. Implementation is AI-assisted using [Claude](https://claude.ai) by Anthropic, which accelerates the write–test–ship cycle considerably. Think of it as one developer with strong opinions and a very patient pair-programming partner.\n\nThe result: a solo project that ships features at a pace that would normally require a team — without compromising on quality, security, or code review.\n\n---\n\n## Donate\n\nIf this project saved you time (or you just like knowing which room your cat is in), you can buy me a coffee:\n\n[![Donate with PayPal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/donate/?hosted_button_id=W489P2RXBMXKW)\n\n---\n\n## License\n\nCopyright (C) 2026 Garry Broeckling. Licensed under the [GNU General Public License v3.0](LICENSE).\n\nPadSpan is a trademark of Garry Broeckling.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbroeckling%2Fpadspanha","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgbroeckling%2Fpadspanha","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbroeckling%2Fpadspanha/lists"}