Skip to main content
← HomeMapper

Frequently Asked Questions

HomeMapper for iPhone, iPad, and Mac. Also see Help.

What is HomeMapper?

HomeMapper is a discovery and inventory tool for your smart home. It scans your local network using multiple protocols (HomeKit, Home Assistant, IP Network, Thread, and Matter) and shows everything it finds in one list. You can see which devices are on your network, how they connect, what protocols they use, and how your Thread mesh is structured. HomeKit scanning is free; the other protocols are part of Pro.

Can HomeMapper control my devices?

No. HomeMapper finds and lists devices. It never turns anything on or off, changes a device's settings, or adds a device to a home. The one exception is Identify Device when you scan or enter a setup code: it makes a HomeKit device flash or chime so you can find it.

Does HomeMapper run on Android or Windows?

No. HomeMapper runs on iPhone, iPad, and Mac. Apple's HomeKit framework only exists on Apple devices, and that's where HomeMapper starts, so there's no Android or Windows version planned.

What do I get with HomeMapper Pro?

Free gives you HomeKit scanning, the device list with core columns, the room view, and one home at a time, with no scan limits and no ads. You don't need Home Assistant or anything else to use it. Pro adds the parts that depend on more network access and more data: multi-protocol scanning beyond HomeKit, Home Assistant integration, the Topology map of your Thread mesh and bridges, all data columns, protocol filtering, Places with every home in a Place together, CSV export, backup and restore, and setup code saving.

Pro comes two ways: an annual subscription with a 7-day free trial, or Lifetime Access as a one-time purchase. The trial includes everything in Pro and starts when you choose it. See What is HomeMapper Pro? for the full breakdown.

Why a subscription?

HomeMapper has no ads and doesn't sell your data. Pro pays for keeping up with each iOS, macOS, HomeKit, Matter, Thread, and Home Assistant release, fixing bugs, and adding features.

Is there a one-time purchase option?

Yes. Lifetime Access is a one-time purchase that gives you HomeMapper Pro forever, with no renewals and no expiration. It works on every device signed into the same Apple ID. The subscription sheet shows the current price.

There is no free trial on Lifetime Access, because Apple's free trials only work on subscriptions. To try before you buy: start the 7-day trial, turn off auto-renew, then buy Lifetime Access while the trial keeps running.

How do I cancel Pro?

In HomeMapper, tap Settings › Subscription › Manage Subscription. On Mac, use the App Store app. Cancel any time, including during the trial, and keep Pro until the billing period ends.

Lifetime Access has nothing to cancel. It's a one-time purchase with no renewal.

What permissions does HomeMapper need?

Two permissions:

  1. HomeKit: Access to your Home app's accessory database. Without this, HomeMapper can't discover HomeKit devices.
  2. Local Network: Permission to browse your local network for IP Network services. Without this, HomeKit and Home Assistant still scan, but IP Network discovery and Thread Border Router detection don't.

Both are requested during first launch. If you denied one, tap Settings › Support Configuration › App Permissions in HomeMapper, which opens HomeMapper's page in the Settings app. You can also go there yourself: Settings › Apps › HomeMapper. On Mac, use System Settings › Privacy & Security.

How long should a scan take?

A typical scan takes 20–30 seconds for a home with 20–50 devices. On a large network it can take up to 3 minutes. If a scan seems stuck, check your network connection and permissions.

What happens if I leave the app while a scan is running?

A scan keeps running when you switch to another app or lock your screen, and HomeMapper still finds your Apple Home and IP Network devices normally. The one thing that doesn't run in the background is Thread mesh mapping, because iOS requires HomeMapper to be open to map your Thread mesh. So after a background scan your Thread devices still appear in the list, but their mesh connections are missing from the Topology map.

To map your Thread mesh, keep HomeMapper open while the scan runs. When you come back to the app after a background scan, HomeMapper shows Map Thread Now: tap it to run a scan with the app open and fill in the connections. With Places, Map Thread Now is shown only when HomeMapper detects that you're at the Place that was scanned. Anywhere else, a note shows that Thread can be mapped the next time you scan at that Place.

Why are some of my devices missing?

Several possible reasons:

  • Permissions: HomeMapper needs both HomeKit and Local Network access. Check App Permissions in System Settings.
  • Network: You must be on the same Wi-Fi as your devices. VPNs can block local discovery.
  • Device is offline: Unplugged or out-of-range devices won't respond.
  • Scan too short: Battery-powered devices respond slowly and may not respond within a single scan. Running two or three scans in a row usually catches them.
  • Not in HomeKit: Devices not added to your Home app won't appear in the HomeKit scan (but may appear via IP Network discovery).
  • Large network: On larger networks HomeMapper scales back its IP scan so scans don't hang, so devices that don't advertise themselves may not show up. HomeKit and Bonjour/mDNS devices still appear.
  • Filters (Pro): Check the protocol bar and make sure the right protocol icons are active (colored, not gray).

If a device is still missing after a few scans, use Settings > Send Feedback and describe the device.

Why did my device count change between scans?

Battery-powered devices, especially Thread sensors, often turn their radio off and miss a scan, so counts go up and down. Filter changes, app updates, and changes to your network can also shift them. See "Why are some of my devices missing?" above.

What does "Found via IP Network" vs "Found via HomeKit" mean?

HomeKit and IP Network are two different ways HomeMapper discovers your devices. HomeKit queries your Home app's database, so it includes device names, rooms, and reachability. IP Network scans your local network directly to find devices advertising themselves.

A device can be found by both. Many HomeKit accessories and hubs, like a Hue Bridge, also advertise themselves on your network, so the IP Network scan picks them up too. With Pro, each colored badge on a device is a protocol that found it. On Free, devices show only the HomeKit badge. Icons shows every badge with its color. See Understanding Protocols for the full explanation.

What does IP Network discovery include?

IP Network looks at your local network directly. It finds devices that advertise themselves, like AirPlay speakers and HomeKit accessories; devices that don't, like routers and NAS boxes; and media servers and smart TVs. It also finds each device's IP address and measures how quickly it responds. IP Network discovery is part of Pro. Turn it on or off in Settings. See Understanding Protocols for details.

Why are some filter icons gray on Devices or Rooms?

The protocol bar is part of Pro. Gray icons mean devices from that protocol are hidden. Tap a gray icon to make that protocol visible (it becomes colored). All protocols are visible by default. IP Network discovery finds many non-smart-home services too (printers, NAS devices, media servers), so hide IP Network when you want a cleaner smart-home-only view. See Understanding Protocols for what each protocol reveals.

Why does the same device appear twice in my list?

HomeMapper merges observations from different sources into one row when they share an identifier the device itself reports, such as its MAC address. Some devices don't report anything that links their HomeKit identity to their network advertisements, like Sonos speakers, some smart TVs, and devices behind HomeKit-bridge integrations. With nothing to match on, they show up as two rows: one for HomeKit and one for IP Network. Both rows are accurate.

The same happens with Home Assistant's HomeKit Bridge integration, which exposes Home Assistant devices to Apple Home: those devices appear in both the HomeKit and Home Assistant scans with no shared identifier to link them. These duplicates are harmless. Devices using Home Assistant's HomeKit Controller integration (where Home Assistant controls a HomeKit device) are matched automatically. See How Device Correlation Works for the full picture.

Why does my device show the wrong icon?

Icons explains how HomeMapper picks a device's icon. If one of your devices shows the wrong icon, send feedback with the device name and we'll add it.

Why is my device icon gray?

Icons explains what gray means. A device can drop out of a scan when it's powered off, off the network, or out of range. Open the device's details: "Reachability Issue" lists which sources stopped reporting it and when each last saw it. If the device is gone for good, tap the trash button there to remove it.

What's the difference between "Last Scanned" and "Last Online"?

Last Scanned is when HomeMapper last included the device in any scan result. Last Online (labeled "Online" in the table) is when the device was last confirmed reachable, meaning it actually responded. A device can appear in scan results (from database history) without being currently reachable.

How do I remove devices that aren't there anymore?

HomeMapper keeps every device until you remove it. A device missing from your last scan shows as stale (Icons).

  • One device: open its details, tap the red trash icon, then Delete.
  • All at once: Settings > Advanced > Purge Unreachable Devices removes unreachable devices that have no setup code. The row only appears when there's something to purge.

Devices from another location belong in their own Place.

What does "Reset Scan Data" do?

It clears your discovered devices and scan history, so your next scan starts fresh. Your saved setup codes are kept, and your settings, permissions, and theme aren't affected. Useful after major network changes or if you want a clean slate. It's in Settings > Advanced.

Why are my HomePods and Apple TVs in "Unassigned"?

Apple doesn't share HomePod or Apple TV details with third-party apps through HomeKit, even though they show up normally in the Apple Home app. HomeMapper finds them through Bonjour and Thread instead, neither of which includes room assignments. This is an Apple limitation: the devices are fine, HomeMapper just has no room assignment for them.

Why doesn't my device show a Matter badge?

If it sits behind a bridge, like a Hue light, that's expected. The bridge is the Matter device: it's the one that was added to Apple Home over Matter. The lights, plugs, and sensors behind it use the bridge's Matter connection rather than having one of their own, which is why they carry no Matter badge, why they don't appear under Matter in iPhone Settings, and why you can't pair them to another Matter controller. If the bridge itself has no Matter badge, it was added to Apple Home the older HomeKit way.

Otherwise, the badge appears only when Apple Home or Home Assistant reports the device as Matter. A device set up in Apple Home with its Apple Home code instead of its Matter code isn't reported as Matter, even if it supports it. Send feedback with the device name if you know it should have the badge.

Why isn't my Apple TV or HomePod shown as a Matter controller?

Matter doesn't publish which device is a controller, so a controller and a light bulb look the same on the network. HomeKit doesn't say which device is the hub either. Instead, HomeMapper shows the Thread role and Border Router label on devices like Apple TV and HomePod, in the Devices list and on the Topology map.

What is the Signal column?

Signal shows a device's connection strength as bars. Four readings can appear, and the one closest to the connection the device depends on wins. A Thread device shows the signal to its parent router, whether Apple Home or Home Assistant measured it. A device that reported its own Wi-Fi signal shows that instead, labelled "Wi-Fi" so you can tell them apart. A Zigbee device in Home Assistant shows its own signal, labelled "Zigbee", with its link quality as "Zigbee LQI". Zigbee link quality runs from 0 to 255, unlike Thread's 0 to 3, so the two numbers aren't comparable. Otherwise it's how quickly the device responds over IP: faster responses get more bars. Devices with none of the four show a dash.

For Home Assistant devices, the Wi-Fi and Zigbee readings come from sensors Home Assistant ships switched off. See Getting more from Home Assistant to turn them on.

A device that is probably getting radio interference turns red and shows "interference suspected". Something near it may be causing radio interference; see Health for what was measured.

What are Thread roles (Router, Leader, End Device)?

See Thread Roles & Mesh Networking for the full explanation. In short: Routers forward data for other devices, Leaders manage the network (one per network, auto-elected), and End Devices are battery-powered nodes that turn their radio off most of the time to save power. Border Routers bridge between Thread and Wi-Fi.

Why doesn't my Thread device show a mesh role?

Many smart devices come with two setup codes printed on the box: a Matter code and an Apple Home code. If you set the device up using the Matter code, Apple hides its Thread role and network info, so it shows up as Matter only even though it's running on Thread underneath. Setting it up with the Apple Home code instead lets HomeMapper show the Thread role and network name. The catch: with an Apple Home code, Apple doesn't share who the device is connected to or its address, so it can't be placed on the Topology map and the devices that route through it show it as an "Unknown router". We've filed feedback with Apple and hope this gets addressed in a future release.

Other cases: third-party devices vary in what they expose, and devices found only via IP Network may show the Thread network name but not the role. See Thread Roles & Mesh Networking for more.

What is the Topology map?

Topology is a Pro map of how your smart home is connected: Thread meshes from border router to end device, Zigbee networks from Home Assistant, and HomeKit bridges with their accessories. Tabs at the top show everything, just Thread, just Zigbee, just bridges, or Health. Tap a device for its details, or a connection for its signal strength and how often the device has had to reconnect. Export the map as a PNG, PDF, or SVG. See the Topology screen guide.

Why can't some Thread devices be placed on the Topology map?

The map only shows a connection it has actually measured. Devices whose connections aren't reported go in a dashed box inside the box for the Thread network they belong to, instead of being placed with guessed connections.

There are three boxes, because they need different things from you.

Device Doesn't Report Connections: the device responded to the scan and doesn't report its connections (that part of the Matter spec is optional, and some devices skip it), or this scan never queried it. Either way there's nothing to do.

Not Shared by Apple Home: devices set up with an Apple Home code report their Thread role, but Apple doesn't share who they're connected to. See Why doesn't my Thread device show a mesh role?. Also nothing to do.

Out of Range or Offline: we queried this device directly and got no response at all, or, for a Home Assistant device, Home Assistant reports it as unavailable. This one is worth checking: it's unplugged, too far from a router, or stuck. It's the only one of the three that means something is wrong.

Border routers like HomePods and Apple TVs are the exception to all of this: they advertise themselves on your network, so they go on the map from their own advertisement whenever a scan detects one.

If your last scan ran with HomeMapper in the background, the Out of Range or Offline box leaves out your Apple Home devices. iOS blocks those queries in the background, so none of them would respond and the box would list your whole home. Home Assistant devices still go in it, because Home Assistant provides their status either way.

If a device was placed before and isn't now, a rescan with Thread Topology Scan enabled (Settings → Discovery) can pick up connections that were missed. See Thread Roles & Mesh Networking for more.

What is an "Unknown router" on the map?

A device in your home that relays Thread traffic, which HomeMapper couldn't match to anything else it found. Usually it's an accessory set up with an Apple Home code, which Apple doesn't share the address of. See Why doesn't my Thread device show a mesh role?.

Each one is named "Unknown router" with a number or the end of its address, like "Unknown router 2" or "Unknown router (…5B8D)". Those names can change between scans, so don't expect one to mean the same device next month. Two Thread networks can each have an "Unknown router 1"; the box it sits in shows which network.

There's nothing to do about them, and a mesh full of them is normal. Tap one for its Thread addresses.

What is the Health tab on the Topology screen?

It shows what's wrong with your mesh and what to fix first. The map shows how your home is connected and the device list shows what each device reported; neither one ranks anything. Health reads those same measurements and lists what needs attention, worst first, in plain sentences. Tap any device name in a row to open its details.

It covers five things: a device that didn't respond to the scan, a router that everything behind it depends on, a connection that's too weak, is losing traffic, or has had no recent traffic, a device that is probably getting radio interference, and a device that keeps restarting. Each row shows what to do about it: move a device, add a mains-powered Thread device, check a power supply.

Most homes have nothing wrong, and the tab shows "Everything looks healthy."

Health can't rate a mesh that hasn't been measured. If your last scan ran in the background, it shows the same "Thread wasn't mapped" message the map does. If you restored a backup and haven't scanned since, it shows a prompt to scan rather than showing you readings from whenever that backup was taken.

Health is part of the Topology tab, so it needs HomeMapper Pro.

How do I connect Home Assistant?

Go to Settings and look for the Home Assistant section under Discovery. HomeMapper can detect Home Assistant servers on your local network; if one is found, its URL appears automatically. You can also enter a URL manually. Tap Connect, then sign in through the browser sheet that appears.

Once you connect a second server, the list moves to its own Servers screen, reached from a row in the same place under Discovery. Everything you can do with a server (switch it off, sign in again, remove it, add another) is on that screen.

Home Assistant is optional. HomeMapper works on its own, and connecting Home Assistant is part of Pro.

Is my Home Assistant connection secure?

Yes. HomeMapper connects directly to each Home Assistant server on your local network; nothing is relayed through cloud servers. It upgrades to HTTPS when your server supports it. Sign-in happens in a secure system browser sheet, so HomeMapper never receives your password, only the OAuth tokens Home Assistant issues. Tokens are stored in the iOS Keychain, never in the database or logs, and disconnecting removes them and sends Home Assistant a request to invalidate them.

What Home Assistant devices show up in HomeMapper?

HomeMapper reads the devices from each Home Assistant server during each scan. You'll see all physical devices: Zigbee sensors, Z-Wave locks, Wi-Fi plugs, MQTT devices, and anything else Home Assistant manages. Home Assistant's own services and add-ons, helpers, and devices you've disabled aren't listed. Each device shows its Home Assistant integration type, area (room), and device class.

Why don't my Home Assistant Thread devices show on the map?

HomeMapper reads the Thread mesh from Home Assistant, and Home Assistant only shares it with an administrator account, on Home Assistant 2026.9 or later with the Matter Server add-on 9.2 or later. When the read doesn't work, the Topology screen and the Health tab show a line naming which of these to fix.

Once the map reads, a Home Assistant Thread device gets its Thread Role, Thread Network, Connected via and Signal from it. Signal for Zigbee and Wi-Fi devices, and Stability and Channel for Matter devices, come from diagnostic sensors Home Assistant ships switched off. See Getting more from Home Assistant for which ones to turn on and how.

What is the Primary Platform setting?

When you have both HomeKit and Home Assistant connected, one of them is set as your primary system. The Primary Platform setting (in Settings > Discovery) sets which source takes priority when both report information about the same device. The primary platform's data takes priority for room assignments, device naming, and display ordering. If you manage most devices through Apple Home, keep it on Apple Home (the default). If Home Assistant is your primary system and HomeKit is secondary, switch to Home Assistant. You can change this any time; it takes effect on the next scan.

I have more than one home. How does HomeMapper handle that?

HomeMapper picks up every home on your Apple Account. Free shows one home at a time: use the home menu on the Devices and Rooms tabs to switch between them. With Pro, homes are grouped into Places, and the whole app shows one Place at a time, with every home in it together and a Home column to tell them apart. Pick the Place from the Place menu on the Devices, Rooms, and Topology tabs, where you can also switch individual homes off. See Places.

The Topology tab has one exception: a Thread mesh is one radio network and does not follow home boundaries, so a border router from a home you've switched off in the Place menu still appears if your devices route through it, with that home's name under it in square brackets. See the Topology screen guide for what that looks like.

Home Assistant fits the same way: HomeMapper connects to more than one Home Assistant server, and each server belongs to a Place.

What is a setup code, and why save it?

Every HomeKit, Matter, and Z-Wave accessory ships with a setup code: the number printed on the device's sticker or box. You need it to pair the device, and again if you ever reset it or move it to a new home. A setup code never travels over the network, so a scan can't find it, and HomeMapper can't recover one you've lost. If the sticker is gone, so is the code. HomeMapper gives you a place to save each code with its device while you still have it. Saving setup codes is part of Pro. See Setup Codes.

How do I import a lot of setup codes at once?

Export your setup codes from Settings > Setup Codes. You'll get a spreadsheet listing every device that can hold a code, with a blank cell for the ones that don't have one yet. Fill in the codes you have, save the file, then import it from the same screen to load them all in at once. HomeMapper matches each row to the right device for you and only adds or updates codes, never changing your devices. See Setup Codes for the full walkthrough.

Can I have my setup codes on more than one device?

Yes. With Pro and iCloud Sync on, saved setup codes sync to your other devices automatically. Without sync, export a CSV on one device and import it on the other (see the import question above). To copy everything to a new device, restore a backup there. See iCloud Sync and Setup Codes.

Why can't I save a setup code for some devices?

Not every device has a code worth saving. HomePods, Apple TVs, and AirPlay speakers and TVs are added without one. For a bridged bulb or sensor, like Hue or Aqara, you pair the bridge rather than each device, so the bridge is the one with the code. Routers, printers, and other plain network gear aren't smart-home accessories and have no setup code at all. HomeMapper only offers the option where a code actually makes sense. See Setup Codes.

Where is my data stored, and does any of it leave my device?

Your scan data is stored on your device. With iCloud Sync on, your setup (room order, Places, Home Assistant connections, and setup codes) is also kept in your own iCloud, never on a HomeMapper server. HomeMapper has no analytics or tracking.

Your scan data leaves your device only when you send it, in one of two ways: a CSV export, where you choose what to include and where it goes, or Send Feedback in Settings, for support. See Privacy for a plain-language summary, with a link to the full Privacy Policy.

Does HomeMapper sync across my devices?

Some of it, through your own iCloud. While you're signed into iCloud, your room order, Places and their saved networks, and Home Assistant connections sync across your devices, and with Pro your saved setup codes do too. Your Home Assistant sign-in carries over through iCloud Keychain if you have that turned on. Scan results stay on each device. It's your own iCloud, never a HomeMapper server, and you can turn it off per device. See iCloud Sync.

How do I remove my synced data from iCloud?

Settings > Advanced > Delete iCloud Data removes HomeMapper's setup codes, room order, Places and their saved networks, and Home Assistant connections from iCloud and turns iCloud Sync off on that device. The data on the device itself is kept. Your other devices are also signed out of Home Assistant, since the sign-in no longer syncs through iCloud Keychain. Sign in again on each one. It works one device at a time: another device that still has iCloud Sync on can upload its copy back, so to clear it everywhere, run it on each of your devices. See iCloud Sync.

Can I back up my HomeMapper data?

Yes. Backup saves a copy of your scan data and settings to iCloud Drive or a folder on your device whenever you tap Backup Now, or after each scan if you turn on Post-scan Backup. Both are in Settings > Backup. Restoring replaces your data with the backup, and HomeMapper saves a safety backup of your current data first. Your Home Assistant sign-in is never included; it stays in the Apple Keychain. Backup and restore is part of Pro.

What do logs contain?

Logs include scan details, your devices and how they were matched, your Places and display settings, and errors with timestamps. They never include passwords, HomeKit credentials, or your Home Assistant sign-in, and the only personal details are the device, room, and home names you've set. Logs go only when you send them, through your mail app or the share sheet, so you can review them first. See Privacy for a plain-language summary of how we handle diagnostic data, with a link to the full Privacy Policy.