Construire une sonde ThreadMapper

Une sonde est une petite carte électronique sur votre Wi-Fi qui mesure la radio que partage votre maison connectée : à quel point chaque canal Thread est occupé, quels réseaux Wi-Fi s’y trouvent et, là où elle peut rejoindre votre maillage Thread, le maillage tel que ses propres routeurs le rapportent. ThreadMapper la lit sur votre propre réseau.

Un seul composant, une dizaine de minutes, aucune soudure. La sonde fait partie de ThreadMapper Pro.

Élément	Remarques
Seeed Studio XIAO ESP32C6	Environ 5 à 8 $. Le micrologiciel est conçu pour cette carte et aucune autre : il pilote le commutateur d’antenne de cette carte, son voyant et son bouton.
Un câble USB-C qui transporte les données	Beaucoup de câbles fournis avec des chargeurs ne transportent que l’alimentation. Si l’ordinateur ne voit pas la carte, essayez d’abord un autre câble.
Un ordinateur avec Chrome, Edge ou Firefox	Uniquement pour l’installation. Safari ne peut pas accéder à un port série USB, et un iPhone ou un iPad non plus.
Du Wi-Fi en 2,4 GHz	La carte n’a pas de radio 5 GHz. Un réseau qui propose les deux bandes sous un même nom convient.
Un chargeur USB	N’importe lequel. C’est là que la sonde reste une fois configurée.

Votre maison	Le bruit des canaux, et le Wi-Fi sur chaque canal	Le maillage Thread lui-même
Des routeurs de bordure Apple ou Google, et rien d’autre	Oui	Non. Ni Apple ni Google ne vous laissent sortir les identifiants de votre réseau Thread. Apple ne donne à une app le droit de les lire que si son éditeur fabrique aussi un routeur de bordure certifié, et celui de ThreadMapper n’en fabrique pas.
Les mêmes, avec Home Assistant	Oui	Oui. L’app Companion de Home Assistant peut y copier les identifiants, et vous les copiez de là vers la sonde (étape 5).
Un routeur de bordure OpenThread à vous	Oui	Oui. Lisez-les directement dessus (étape 5).

Étape 1 — Installer le micrologiciel

Branchez la carte sur l’ordinateur.
Cliquez sur Installer le micrologiciel de la sonde ci-dessous et choisissez le port nommé USB JTAG/serial debug unit.
Cliquez sur Install ThreadMapper Probe. Le programme d’installation demande s’il faut effacer l’appareil : pour une carte neuve, cochez Erase device. Puis Next, et Install.

Uniquement pour une carte neuve. L’effacement emporte tout ce qu’une sonde a reçu : son Wi-Fi, sa clé et son réseau Thread. Une sonde qui fonctionne déjà se met à jour à la place (voir Mise à jour), et si le programme d’installation pose cette question pour l’une d’elles, laissez la case décochée.

Ce navigateur ne peut pas accéder à un port série USB. Ouvrez cette page dans Chrome, Edge ou Firefox, sur un ordinateur. Le programme d’installation ne fonctionne que sur une page ouverte en HTTPS.

L’opération prend une minute ou deux et se termine par Installation complete! Cliquez sur Next. La fenêtre du programme d’installation est en anglais.

Si le port n’est pas dans la liste, c’est presque toujours le câble. Sinon, maintenez le bouton B de la carte enfoncé pendant que vous la branchez, puis réessayez.

Aucun de ces navigateurs ? esptool, d’Espressif, fait la même chose. Une première installation, qui efface tout ce que contenait la carte :

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

Une mise à jour, qui laisse à la sonde ce qu’elle a reçu :

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

Les deux images sont threadmapper-probe-full.bin et threadmapper-probe.bin. Ouvrez ensuite le port série de la carte avec n’importe quel programme de terminal, et donnez son Wi-Fi à la sonde en le tapant (étape 2, Sans la liste).

Étape 2 — Lui donner votre Wi-Fi

Après une première installation, avec Erase device coché, le programme d’installation passe de lui-même à Configure Wi-Fi. Si vous voyez plutôt sa liste de choix, cliquez-y sur Connect to Wi-Fi.

La sonde liste les réseaux qu’elle entend.

Sous Network, choisissez le vôtre.
Saisissez son mot de passe.
Cliquez sur Connect.

Le programme d’installation affiche Trying to connect, ce qui peut durer presque une minute, puis Device connected to the network! Le voyant de la sonde est alors allumé et le reste. Cliquez sur Continue.

La sonde ne garde un réseau qu’une fois qu’elle l’a rejoint. Unable to connect signifie qu’elle a essayé sans y parvenir : presque toujours le mot de passe, parfois un routeur trop éloigné. L’essai n’a rien changé : une sonde qui avait un réseau auparavant l’a toujours, et y retourne. Réessayez.

Votre réseau n’est pas dans la liste ? La sonde n’a pas de radio 5 GHz : un réseau uniquement en 5 GHz n’y figure donc pas. Un réseau qui masque son nom non plus : choisissez Join other… et saisissez le nom.

Le champ du mot de passe masque ce que vous saisissez. Le nom et le mot de passe descendent par le câble jusqu’à la carte, qui les garde dans sa propre mémoire et n’écrit le mot de passe dans aucun journal.

Sans la liste

Si le programme d’installation ne propose pas Connect to Wi-Fi, c’est qu’il n’a pas entendu la sonde répondre : fermez sa fenêtre, cliquez de nouveau sur le bouton d’installation et choisissez le port.

La sonde peut aussi recevoir son réseau depuis sa console, dans Logs & Console ou dans n’importe quel programme de terminal ouvert sur son port. Tapez wifi et appuyez sur Entrée. Les lignes qui commencent par > sont ce que vous tapez :

> 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.

Rien n’a besoin de guillemets, et les lettres accentuées comme é, à ou ç ne posent pas de problème. La sonde ne réaffiche pas le mot de passe. La page, elle, l’affiche pendant que vous le tapez, et le garde dans son journal jusqu’à ce que vous fermiez la fenêtre : c’est votre propre écran, alors regardez d’abord par-dessus votre épaule.

Quand elle reçoit un réseau de cette façon, la sonde redémarre pour le rejoindre sans l’avoir essayé au préalable. Si son voyant revient à un bref clignotement toutes les deux secondes, c’est qu’elle a essayé dix fois, n’a pas pu le rejoindre et a oublié le réseau.

Étape 3 — Connecter l’app

Attendez que le voyant reste allumé. Sur l’iPhone, ouvrez ThreadMapper et allez dans Réglages → Sonde ThreadMapper. Quand le téléphone est sur le même Wi-Fi, la sonde figure sous Sur ce réseau : choisissez-la. Tester la connexion indique alors ce qu’est la sonde et où elle en est.

Si l’app ne la liste pas, demandez à la sonde où elle se trouve : fermez la fenêtre du programme d’installation, cliquez de nouveau sur le bouton d’installation, choisissez le port, ouvrez Logs & Console et tapez status. L’une de ses lignes est l’adresse à saisir dans l’app :

in the app: http://192.168.1.50:8099

Votre routeur donnera peut-être un jour une autre adresse à la sonde. L’app connaît la sonde par autre chose que son adresse : une fois ouverte, et avec le téléphone sur le même Wi-Fi, elle retrouve la sonde toute seule.

Le câble a fait son travail. Débranchez la carte et mettez-la sur un chargeur, quelque part au milieu de la maison plutôt que derrière le routeur : la sonde entend ce qui est près d’elle.

Étape 4 — Donner la clé à votre iPhone

Une sonde sans clé répond à n’importe qui sur votre Wi-Fi. Cela comprend les noms des réseaux Wi-Fi qu’elle entend, et des demandes qui éloignent sa radio du canal de votre maillage pendant plusieurs secondes à chaque fois.

Appuyez deux fois sur le bouton B de la carte, coup sur coup. (Pas R : celui-là redémarre la sonde.) Le voyant clignote deux fois par seconde, pendant trois minutes ou jusqu’à ce qu’un téléphone ait pris la clé. Dans l’app, sous Réglages → Sonde ThreadMapper, touchez Obtenir la clé.

Dès lors, la sonde ne fait ce qui coûte du temps à sa radio que pour un téléphone qui détient la clé. La clé prouve qui demande ; elle ne cache rien. Les réponses continuent de traverser votre Wi-Fi sans être chiffrées, et la clé aussi, une fois, quand un téléphone la reçoit.

Un seul téléphone détient la clé à la fois. Un second téléphone qui la reçoit la prend au premier.

Étape 5 — Lui donner votre réseau Thread

Passez cette étape si votre maison est la première ligne du tableau ci-dessus.

La sonde rejoint un réseau Thread avec le jeu de données actif (« active dataset ») de ce réseau, une chaîne de quelque deux cents chiffres hexadécimaux qui contient la clé du réseau.

Home Assistant : ouvrez sa page Thread, Settings → Connectivity → Thread, ou dans les versions plus anciennes Settings → Devices & services → Thread → Configure (ce sont les noms de menus de Home Assistant en anglais). À côté de votre réseau se trouve un bouton d’information, et ce qu’il affiche se termine par Active dataset TLVs : copiez cela. Si le réseau appartient à Apple Home, il faut d’abord le donner à Home Assistant : ouvrez la même page dans l’app Companion sur votre iPhone et choisissez Send credentials to Home Assistant.
Routeur de bordure OpenThread : sudo ot-ctl dataset active -x

Rebranchez la sonde sur l’ordinateur, cliquez sur le bouton d’installation ci-dessus, choisissez son port et ouvrez Logs & Console sans rien installer. Tapez thread dataset, appuyez sur Entrée, et collez le jeu de données quand la sonde le demande :

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

En quelques minutes, Réglages → Sonde ThreadMapper, dans l’app, indique que la sonde est sur son maillage Thread.

Le jeu de données est la clé de votre réseau Thread. La sonde ne le réaffiche pas, mais la page dans laquelle vous le collez l’affiche, et le garde dans son journal jusqu’à ce que vous fermiez la fenêtre. La sonde le garde dans sa propre mémoire, qui n’est pas chiffrée : quelqu’un qui emporte la carte peut l’en extraire.

Ce que vous obtenez

Dans l’app	Avec le Wi-Fi seul	Avec votre réseau Thread en plus
Scanner de canaux : le bruit mesuré sur les seize canaux Thread	Oui	Oui
Les réseaux Wi-Fi derrière le bruit, par nom et par canal	Oui	Oui
Une journée de mesures de bruit, prises toutes les cinq minutes pendant que l’app était fermée	Oui	Oui
Mesures de la sonde : chaque routeur du maillage, les nœuds que la sonde entend avec leur signal mesuré, et la façon dont le maillage route entre eux	Non	Oui
Sur la page d’un appareil : qui l’entend et à quel point, et s’il répond	Non	Oui
Docteur Réseau, pour un appareil Thread sur secteur qu’Apple Home ne parvient pas à joindre : s’il répond malgré tout sur le maillage et, pour un appareil Matter, si un routeur de bordure détient encore son enregistrement	Non	Oui

Les noms des réseaux Wi-Fi sont affichés sur le téléphone et ne sont enregistrés nulle part.

Ce que dit le voyant

Voyant	Signification
Un bref clignotement toutes les deux secondes	Pas encore de réseau Wi-Fi. Étape 2.
Clignote lentement	Elle a un réseau et le rejoint.
Allumé	Elle est sur votre Wi-Fi. C’est ainsi que le voyant doit se présenter.
Deux clignotements par seconde	Vous avez appuyé deux fois sur le bouton : elle donnera la clé à un téléphone, pendant trois minutes ou jusqu’à ce que l’un d’eux l’ait prise.
Clignote rapidement	Vous avez appuyé une fois sur le bouton. Cela ouvre une fenêtre de trois minutes que cette version de l’app n’utilise pas. Elle se referme toute seule et la sonde redémarre, ce qui fait repartir de zéro sa journée de mesures.
Scintille	Vous maintenez le bouton enfoncé depuis trois secondes. À dix, tout ce que la sonde a reçu est effacé.

Mise à jour

Un nouveau micrologiciel arrive sur cette page. Branchez la sonde sur l’ordinateur, cliquez sur le bouton d’installation et choisissez le port. Le programme d’installation indique quel micrologiciel tourne sur la sonde et propose Update ThreadMapper Probe : cliquez dessus, puis sur Install. Une mise à jour n’efface rien : la sonde garde son Wi-Fi, sa clé et son réseau Thread.

Une sonde dont le micrologiciel est antérieur au 0.8.0 ne dit pas au programme d’installation ce qu’elle est. Celui-ci propose alors Install ThreadMapper Probe et demande s’il faut effacer l’appareil : laissez Erase device décoché.

Quand la sonde utilise déjà le micrologiciel le plus récent, le programme d’installation propose à la place Erase User Data. Cela efface tout ce que la sonde a reçu, comme le fait de maintenir son bouton enfoncé dix secondes.

Si cela ne fonctionne pas

Ce que vous voyez	Ce que c’est
Le bouton d’installation indique que le navigateur n’est pas pris en charge	Utilisez Chrome, Edge ou Firefox sur un ordinateur.
Le port n’est pas dans la liste	Le câble ne transporte que l’alimentation, ou un autre programme a ouvert le port.
Le programme d’installation affiche Unable to connect	Le mot de passe est faux, la sonde est trop loin du routeur, ou le réseau est uniquement en 5 GHz. Rien n’a été modifié. Réessayez.
Le programme d’installation ne propose pas Connect to Wi-Fi	Il n’a pas entendu la sonde répondre. Fermez sa fenêtre, cliquez de nouveau sur le bouton d’installation et choisissez le port.
Le voyant est revenu à un bref clignotement toutes les deux secondes	Un réseau saisi dans la console n’a pas pu être rejoint : le mot de passe est faux, ou le réseau est uniquement en 5 GHz. Après dix essais, la sonde l’a oublié. Redonnez-lui le réseau (étape 2).
Le voyant continue de clignoter lentement	La sonde a déjà rejoint ce réseau et ne parvient plus à le joindre : le routeur est éteint ou trop loin, ou son mot de passe a changé. Si c’est le cas, redonnez-lui le réseau (étape 2).
La sonde dit que le jeu de données est tronqué, ou de la mauvaise longueur	Un long collage peut perdre un morceau en route. Collez-le une nouvelle fois.
L’app ne liste pas la sonde	Le téléphone est sur un autre Wi-Fi, ou sur un réseau invité qui isole les appareils les uns des autres. Saisissez l’adresse donnée par `status`.
L’app indique que la sonde a une clé que cet iPhone ne détient pas	Un autre téléphone a pris la clé, ou la sonde est repartie de zéro. Appuyez deux fois sur B et touchez de nouveau Obtenir la clé.
L’app indique que la sonde est hors de son maillage Thread	Elle a un jeu de données et ne trouve pas le réseau : le jeu de données est celui d’un autre réseau, ou aucun routeur n’est à portée.
Vous voulez tout recommencer	Maintenez le bouton B enfoncé pendant dix secondes.

À savoir

La sonde n’ouvre aucune connexion vers Internet. Elle répond sur votre propre réseau, sur le port 8099, en simple HTTP, et s’y annonce par son nom.
Elle garde ce qu’elle a reçu, le nom et le mot de passe de votre Wi-Fi, la clé, et le jeu de données Thread si vous lui en avez donné un, dans sa propre mémoire, non chiffrée. Maintenir le bouton enfoncé dix secondes efface le tout.
Sa journée de mesures se trouve dans une mémoire qu’un redémarrage vide, tout comme une coupure de courant.
C’est un montage pour qui en veut un, pas un produit. Elle n’est pas certifiée Thread.
Le programme d’installation de cette page est ESP Web Tools, d’ESPHome, sous Apache License 2.0. Il s’exécute dans votre navigateur et est servi depuis ce site. Il récupère le micrologiciel sur ce site et n’envoie rien nulle part. Ce que vous lui donnez pour le Wi-Fi de la sonde descend par le câble jusqu’à la carte ; il note aussi ce qu’il envoie, sous forme de nombres, dans la console de développement du navigateur, jusqu’à la fermeture de l’onglet.
Le micrologiciel repose sur des logiciels open source d’Espressif et d’autres. Leurs licences se trouvent dans NOTICES.txt, et les conditions de l’image elle-même dans LICENSE.txt.