Welcome to PadSpan HA — Getting Started Guide

[gbroeckling]

Welcome!

Thanks for checking out PadSpan HA — the most comprehensive BLE room-presence tracking system for Home Assistant.

Whether you just installed PadSpan or you're evaluating it, this thread will help you get oriented.

---

Quick Start

1. Install via HACS — Add this repo as a custom repository, install, and restart HA
2. Add the integration — Settings → Devices & Services → Add Integration → PadSpan HA
3. Open the sidebar panel — Click "PadSpan HA" in your HA sidebar
4. Try Sample mode first — Toggle to Sample mode (top-right) to explore every feature with demo data
5. Switch to Live mode — Your BLE scanners are auto-discovered. You'll see real devices immediately.

First Steps in Live Mode

• Objects tab — See every Bluetooth device your scanners detect. Tag the ones you recognize (phones, AirTags, keys).
• Maps tab — Upload a floor plan, draw room boundaries, place your scanner markers.
• Follow tab — Select a tagged device and watch it move between rooms in real time.
• Calibration panel — Walk around your house collecting signal fingerprints for better accuracy.

Hardware You Need

• At least 1 BLE scanner (more = better room accuracy)
  • ESPresense boards
  • ESP32 Bluetooth Proxies (ESPHome)
  • Any HA-compatible Bluetooth adapter
• That's it. No cloud. No subscriptions. Everything runs locally.

Tips

• 3+ scanners gives you reliable room-level tracking
• Place scanners in the rooms you want to track, not in hallways
• Run the calibration walkthrough (Training Hub → Calibration) for best results
• Use Basic mode if the 21 views feel overwhelming — it shows a curated subset

Getting Help

• In-app help — Click the (?) buttons throughout the UI for contextual guidance
• Training Hub — Guided walkthroughs for every major feature
• Bug reports — Use the bug report template
• Feature requests — Use the feature request template
• General questions — Post in the Q&A category

---

Feel free to reply here with questions, first impressions, or your setup. Happy tracking!

[tbrasser]

I don't see any tabs, only the main view?

[gbroeckling]

Lot's of updates today, try again Best Garry I don't see any tabs, only the main view? — Reply to this email directly, view it on GitHub , or unsubscribe . You are receiving this because you authored the thread. Message ID: <gbroeckling/padspanHA/repo-discussions/4/comments/16014817 @ github . com>

[tbrasser]

It seems on desktop the menu works fine, but on mobile (app & browser, even on desktop mode) the menu is fully hidden. Could you create a button on the top of the main window (outside the menu) to toggle it?

[tbrasser]

Thanks! That was quick!

[gbroeckling]

No Problem

[ruhlmcu]

This is an awesome project. I have begun mapping using an architectural drawing of my home. I have marked the rooms and placed the sensors. I have added measurements converting from feet to meters. The drawings appear very small in my subsequent panels. Am i doing something wrong with the measurement tool?

[gbroeckling]

@ruhlmcu Thanks for the kind words — and no, you're not doing anything wrong with the measurement tool. You've hit a genuine confusion in the UI, and it's mine to fix. There are two independent scaling systems in PadSpan and the names don't make that obvious:

1. Measure (📏) sets real-world size. Two measurements at different angles → px/m → the map's true extent in metres. This feeds the positioning math only: path-loss distances, scanner coordinates, room centroids. It deliberately has no effect on how large anything looks anywhere.

2. The stack transform sets apparent size. Every panel renders in normalised 0–1 image coordinates, positioned by each map's stack scale / offset / rotation (the Alignment Overlay and Point Align controls under Maps → floor assignment). This is what controls how big your drawing appears relative to other floors. Converting feet to metres correctly — which you did — changes nothing here.

So when the plan looks tiny in later panels, the usual cause isn't the scale at all: it's that the panels fit the whole image file, and an architectural drawing is mostly paper. Title block, border, dimension lines, white margin — if the actual floor plan occupies the middle 40% of the sheet, it'll occupy the middle 40% of every PadSpan view too, with everything else as empty space around it.

The fix is to crop the image down to the building footprint: open the map and use the Trim Image panel (drag a region → Apply Trim). Your scanner pins and room polygons are remapped automatically, so you won't lose placement work.

One important ordering caveat: trim first, then run Measure. If you trim a map you've already scaled, the scale needs re-running — I dug into this while writing the reply and found the recompute path can't recover px/m for maps scaled with the current Measure tool, so it preserves the old real-world extent instead of the pixel density, which leaves the metre scale wrong by the crop ratio. That's a bug, not intended behaviour; I'm filing it and it'll get fixed. Until then: trim, then measure, and you're fine.

If cropping doesn't explain it, could you open a bug report with a screenshot of the Maps view next to one of the panels where it looks small, plus what the Measure panel reports as your current fabric scale (should read something like "Current fabric scale: 18.3m × 12.1m")? If that number is wildly off from your house's real dimensions, that's a different problem and I'd want to see it.