Build a ThreadMapper probe

A probe is a small board on your Wi-Fi that measures the radio your smart home shares: how busy each Thread channel is, which Wi-Fi networks sit on it, and, where it can join your Thread mesh, the mesh as its own routers report it. ThreadMapper reads it over your own network.

One part, about ten minutes, no soldering. The probe is part of ThreadMapper Pro.

Read this before you buy the board

What you need

Part	Notes
Seeed Studio XIAO ESP32C6	About $5–8. The firmware is built for this board and no other: it drives this board's antenna switch, its light and its button.
A USB-C cable that carries data	Many cables that come with chargers carry power only. If the computer does not see the board, try another cable first.
A computer with Chrome, Edge or Firefox	For the install only. Safari cannot reach a USB serial port, and neither can an iPhone or an iPad.
Wi-Fi on 2.4 GHz	The board has no 5 GHz radio. A network that offers both bands under one name is fine.
A USB charger	Any. That is where the probe lives once it is set up.

What it can read in your home

The measuring works in every home. Reading the mesh needs the probe to join your Thread network, and whether it can depends on what runs that network.

Your home	Channel noise, and the Wi-Fi on each channel	The Thread mesh itself
Border routers from Apple or Google, and nothing else	Yes	No. Neither lets you take your Thread network's credentials out. Apple gives an app the right to read them only when its maker also makes a certified border router, and ThreadMapper's does not.
The same, with Home Assistant	Yes	Yes. Home Assistant's Companion app can copy the credentials in, and you copy them from there to the probe (step 5).
An OpenThread Border Router of your own	Yes	Yes. Read them off it (step 5).

If the first row is your home, the probe will not draw your mesh. It still measures what no phone can: the noise on each of the sixteen Thread channels, every five minutes, and which Wi-Fi networks are behind it. Decide on that before you buy.

Step 1 — Install the firmware

Plug the board into the computer.
Press Install the probe firmware below and choose the port named USB JTAG/serial debug unit.
Press Install ThreadMapper Probe. It asks whether to erase the device: for a new board, tick Erase device. Then Next, and Install.

Only for a new board. Erasing takes everything a probe was told with it: its Wi-Fi, its key and its Thread network. A probe that already works is updated instead (see Updating), and if the installer asks this of one, leave the box unticked.

This browser cannot reach a USB serial port. Open this page in Chrome, Edge or Firefox, on a computer. The installer only works on a page opened over HTTPS.

It takes a minute or two and ends with Installation complete! Press Next. The installer's own window is in English.

If the port is not in the list, it is nearly always the cable. Failing that, hold the board's B button while you plug it in, and try again.

None of those browsers? Espressif's esptool does the same. A first install, which erases whatever the board held:

esptool.py --chip esp32c6 write_flash 0x0 threadmapper-probe-full.bin

An update, which leaves the probe what it was told:

esptool.py --chip esp32c6 write_flash 0x20000 threadmapper-probe.bin

The two images are threadmapper-probe-full.bin and threadmapper-probe.bin. Then open the board's serial port with any terminal program, and give the probe its Wi-Fi by typing (step 2, Without the list).

Step 2 — Give it your Wi-Fi

After a first install, with Erase device ticked, the installer goes on to Configure Wi-Fi by itself. If you are looking at its list of choices instead, press Connect to Wi-Fi there.

The probe lists the networks it hears.

Under Network, choose yours.
Type its password.
Press Connect.

The installer says Trying to connect, which can take most of a minute, and then Device connected to the network! The probe's light is then on and stays on. Press Continue.

The probe keeps a network only once it has joined it. Unable to connect means it tried and did not get on: nearly always the password, sometimes a router too far away. The try changed nothing: a probe that had a network before still has it, and goes back to it. Try again.

Your network is not in the list? The probe has no 5 GHz radio, so a network on 5 GHz only is not there. Neither is a network that hides its name: choose Join other… and type the name.

The password field hides what you type. The name and the password go down the cable to the board, which keeps them in its own memory and writes the password in no log.

Without the list

If the installer offers no Connect to Wi-Fi, it did not hear the probe answer: close its window, press the install button again and choose the port.

The probe can also be given its network at its console, in Logs & Console or in any terminal program on its port. Type wifi and press Return. The lines that begin with > are what you type:

> wifi
Network name? Type it and press Return.
> My network
Password? The probe does not write it back. Return alone for a network without one.
> my password
stored: "My network", with a password of 11 characters.
Restarting to join it. The light stays on once it has.

Nothing needs quotes, and letters such as å, ä and ö are fine. The probe does not write the password back. The page does show it as you type, and keeps it in its log until you close the window: it is your own screen, so look over your shoulder first.

Given a network this way, the probe restarts to join it and has not tried it first. If its light goes back to one short flash every two seconds, it tried ten times, could not join, and has forgotten the network.

Step 3 — Connect the app

Wait for the light to stay on. On the iPhone, open ThreadMapper and go to Settings → ThreadMapper Probe. With the phone on the same Wi-Fi, the probe is listed under On This Network: choose it. Test Connection then says what the probe is and where it stands.

If the app does not list it, ask the probe where it is: close the installer's window, press the install button again, choose the port, open Logs & Console and type status. One of its lines is the address to type into the app:

in the app: http://192.168.1.50:8099

Your router may give the probe another address one day. The app knows the probe by more than its address: open, and with the phone on the same Wi-Fi, it finds the probe again by itself.

The cable has done its work. Unplug the board and put it on a charger, somewhere in the middle of the home rather than behind the router: the probe hears what is near it.

Step 4 — Give your iPhone the key

A probe with no key answers anyone on your Wi-Fi. That includes the names of the Wi-Fi networks it hears, and requests that take its radio off your mesh's channel for seconds at a time.

Press the board's B button twice, one press right after the other. (Not R: that one restarts the probe.) The light flashes twice a second, for three minutes or until a phone has taken the key. In the app, under Settings → ThreadMapper Probe, tap Get the Key.

From then on the probe does what costs its radio time only for a phone that holds the key. The key proves who is asking; it hides nothing. Answers still cross your Wi-Fi unencrypted, and so does the key, once, when a phone is given it.

One phone holds the key at a time. A second phone that is given it takes it from the first.

Step 5 — Give it your Thread network

Skip this if your home is the first row of the table above.

The probe joins a Thread network with that network's active dataset, a string of some two hundred hex digits that holds the network's key.

Home Assistant: open its Thread page, Settings → Connectivity → Thread, or in older versions Settings → Devices & services → Thread → Configure. Beside your network is an information button, and what it shows ends with Active dataset TLVs: copy that. If the network belongs to Apple Home, Home Assistant has to be given it first: open the same page in the Companion app on your iPhone and choose Send credentials to Home Assistant.
OpenThread Border Router: sudo ot-ctl dataset active -x

Plug the probe into the computer again, press the install button above, choose its port, and open Logs & Console without installing anything. Type thread dataset, press Return, and paste the dataset when the probe asks for it:

> thread dataset
Dataset, as hex? The probe does not write it back.
> 0e080000000000010000000300001935060004001fffe0...
stored: "MyHome", channel 25. Restarting to join it.

Within a few minutes the app's Settings → ThreadMapper Probe says the probe is on its Thread mesh.

The dataset is the key to your Thread network. The probe does not write it back, but the page you paste it into shows it, and keeps it in its log until you close the window. The probe keeps it in its own memory, which is not encrypted: somebody who takes the board can read it out.

What you get

In the app	With Wi-Fi only	With your Thread network as well
Channel Scanner: the measured noise on all sixteen Thread channels	Yes	Yes
The Wi-Fi networks behind the noise, by name and channel	Yes	Yes
A day of noise readings, taken every five minutes while the app was closed	Yes	Yes
Probe Readings: every router in the mesh, the nodes the probe hears with their measured signal, and how the mesh routes between them	No	Yes
On a device's page: who hears it and how well, and whether it answers	No	Yes
Network Doctor, for a mains-powered Thread device Apple Home cannot reach: whether it answers on the mesh all the same, and, for a Matter device, whether a border router still has its registration	No	Yes

The names of the Wi-Fi networks are shown on the phone and saved nowhere.

What the light says

Light	Meaning
One short flash every two seconds	No Wi-Fi network yet. Step 2.
Blinking slowly	It has a network and is joining it.
On	It is on your Wi-Fi. This is how it should look.
Two flashes a second	You pressed the button twice: it will give a phone the key, for three minutes or until one has taken it.
Blinking quickly	You pressed the button once. That opens a three-minute window this version of the app does not use. It closes by itself and the probe restarts, which starts its day of readings again.
Flickering	You have held the button for three seconds. At ten it erases everything the probe was told.

Updating

A new firmware arrives on this page. Plug the probe into the computer, press the install button and choose the port. The installer says which firmware the probe runs and offers Update ThreadMapper Probe: press it, and then Install. An update erases nothing: the probe keeps its Wi-Fi, its key and its Thread network.

A probe on a firmware before 0.8.0 does not tell the installer what it is. The installer then offers Install ThreadMapper Probe and asks whether to erase the device: leave Erase device unticked.

When the probe already runs the newest firmware the installer offers Erase User Data instead. That erases everything the probe was told, as holding its button for ten seconds does.

If it does not work

What you see	What it is
The install button says the browser is not supported	Use Chrome, Edge or Firefox on a computer.
The port is not in the list	The cable carries power only, or another program has the port open.
The installer says Unable to connect	The password is wrong, the probe is too far from the router, or the network is on 5 GHz only. Nothing was changed. Try again.
The installer offers no Connect to Wi-Fi	It did not hear the probe answer. Close its window, press the install button again and choose the port.
The light is back to one short flash every two seconds	A network typed at the console did not join: the password is wrong, or the network is on 5 GHz only. After ten tries the probe forgot it. Give it the network again (step 2).
The light keeps blinking slowly	The probe has joined this network before and cannot reach it now: the router is off or too far away, or its password has changed. If it has, give it the network again (step 2).
The probe says the dataset is cut short, or the wrong length	A long paste can lose a piece on the way. Paste it once more.
The app does not list the probe	The phone is on another Wi-Fi, or on a guest network that keeps devices apart. Type the address from `status`.
The app says the probe has a key this iPhone does not hold	Another phone took the key, or the probe was started again from nothing. Press B twice and tap Get the Key again.
The app says the probe is off its Thread mesh	It has a dataset and cannot find the network: the dataset is another network's, or no router is in range.
You want to start again	Hold the B button for ten seconds.

What to know

The probe opens no connection to the internet. It answers on your own network, on port 8099, over plain HTTP, and announces itself there by name.
It keeps what it was told, your Wi-Fi's name and password, the key, and the Thread dataset if you gave it one, in its own memory, not encrypted. Holding the button for ten seconds erases all of it.
Its day of readings is in memory that a restart empties, and so does a power cut.
It is a build for people who want one, not a product. It is not Thread certified.
The installer on this page is ESP Web Tools, by ESPHome, under the Apache License 2.0. It runs in your browser and is served from this site. It fetches the firmware from this site and sends nothing anywhere. What you give it for the probe's Wi-Fi goes down the cable to the board; it also notes what it sends, as numbers, in the browser's developer console, until the tab is closed.
The firmware is built on open-source software from Espressif and others. Their licences are in NOTICES.txt, and the terms for the image itself in LICENSE.txt.