yarbo-local 0.1.0.dev0__tar.gz

yarbo_local-0.1.0.dev0/.gitignore

@@ -0,0 +1,221 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# local captures contain serials and coordinates
+captures/

yarbo_local-0.1.0.dev0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yarbo-local
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yarbo_local-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: yarbo-local
+Version: 0.1.0.dev0
+Summary: Local-first asyncio library and tooling for Yarbo robots over their LAN MQTT broker. No cloud.
+Project-URL: Homepage, https://github.com/yarbo-local/yarbo-local
+Project-URL: Issues, https://github.com/yarbo-local/yarbo-local/issues
+Author: Yarbo Local contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,home-assistant,mqtt,robot-mower,yarbo
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: aiomqtt<3,>=2.5
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: aiohttp<4,>=3.10; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: studio
+Requires-Dist: aiohttp<4,>=3.10; extra == 'studio'
+Description-Content-Type: text/markdown
+
+# yarbo-local
+
+Local-first tooling and, later, the asyncio library behind a Home Assistant integration for Yarbo robots. It talks to the anonymous MQTT broker the robot runs on your LAN and to nothing else. No Yarbo account, no vendor servers, no telemetry.
+
+Status: **pre-alpha.** Phase 0 validated the protocol on real hardware (firmware 3.14.11) and produced the knowledge base in `protocol/`: 19 commands verified with captures, the rest marked as candidates that cannot be sent. The library core is in place: a registry-gated session, typed state, the map, a fixture-driven simulator and a small client. The Home Assistant integration ([yarbo-local-ha](https://github.com/yarbo-local/yarbo-local-ha)) shows the robot and its map but does not control it yet, and the dashboard card ([yarbo-local-card](https://github.com/yarbo-local/yarbo-local-card)) draws the map, the robot and plan progress. Next is plan control: pause, resume, stop and start, each verified against the robot first. Not on PyPI yet.
+
+## What is here
+
+| Path | Purpose |
+|---|---|
+| `src/yarbo_local/client.py` | `YarboRobot`: connect, read typed state, and run the verified reads. |
+| `src/yarbo_local/session.py` | The protocol layer: reconnect, reply correlation, encoding choice, wake and controller rules. |
+| `src/yarbo_local/registry.py` | The command allowlist loaded from `protocol/commands.yaml`. Forbidden names cannot be sent. |
+| `src/yarbo_local/models.py` | `RobotState` and the map, plan and GNSS parsers. No I/O. |
+| `src/yarbo_local/transport.py` | aiomqtt transport plus an in-memory fake for tests. |
+| `src/yarbo_local/simulator.py` | A robot built from fixtures, for tests and for developing without hardware. |
+| `src/yarbo_local/resolve.py` | Address resolution: last address, DNS name, subnet scan. |
+| `src/yarbo_local/fieldmap.py` | Builds `protocol/fields.yaml` from the curated seed and the fixtures. |
+| `src/yarbo_local/studio/` | The Studio: aiohttp server and Lit UI (`docs/studio.md`). |
+| `src/yarbo_local/codec.py` | zlib-or-plain JSON codec with the firmware rule and an observed-encoding fallback. |
+| `src/yarbo_local/capture.py` | `sniff`: subscribe to `snowbot/+/#` and write every message to JSONL, optionally redacted. |
+| `src/yarbo_local/probe.py` | `probe`: send one allowlisted command, show the correlated reply and the telemetry deltas. |
+| `src/yarbo_local/discover.py` | `discover`: find brokers carrying `snowbot` traffic, identified by the serial in their topics. |
+| `src/yarbo_local/dump.py` | `dump`: summarise a capture, including the full `DeviceMSG` key inventory. |
+| `src/yarbo_local/sitecheck.py` | `sitecheck`: check a site with one or several robots, reads only, and write a report that is safe to share (`docs/multi-robot.md`). |
+| `src/yarbo_local/redact.py` | Serial, MAC, IP, coordinate and Wi-Fi redaction for shareable fixtures. |
+| `protocol/` | The knowledge base: `commands.yaml`, `fields.yaml`, `codes.yaml`, `fixtures/`. |
+| `docs/phase0.md` | The twelve questions Phase 0 answers, with the exact commands. |
+
+## Quick start
+
+```bash
+git clone https://github.com/yarbo-local/yarbo-local
+cd yarbo-local
+uv sync --extra dev
+uv run yarbo-local discover 192.168.40.0/24
+uv run yarbo-local sniff 192.168.40.23 --out captures/idle.jsonl
+uv run yarbo-local dump captures/idle.jsonl --keys --app
+uv run yarbo-local probe 192.168.40.23 get_device_msg
+```
+
+`probe` only sends commands on a short allowlist of reads plus the wake-up command. It will not send anything that moves the robot, changes the map, or touches settings.
+
+## Using the library
+
+```python
+import asyncio
+from yarbo_local import YarboRobot
+
+
+async def main() -> None:
+    async with YarboRobot.for_host("192.168.50.184") as robot:
+        state = await robot.snapshot()
+        print(state.activity, state.battery, state.head_name)
+        for plan in await robot.plans():
+            print(plan.id, plan.name)
+        robot.on_state(lambda s: print("changed:", s.activity))
+        await asyncio.sleep(30)
+
+
+asyncio.run(main())
+```
+
+Rules the session enforces, on purpose:
+
+- Only commands in `protocol/commands.yaml` can be sent. Names in its `forbidden` section are not entries and can never be sent, with or without flags.
+- A command whose status is `candidate` is refused unless the session was opened with `allow_candidates=True`. The Home Assistant integration never does that; the Studio does.
+- A command with `risk: confirm` needs `confirmed=True` on the call.
+- The wake command and the controller role are used only when the command's flags say they are needed, and the controller is itself still a candidate.
+- Outbound encoding follows the robot's firmware, or what it has been seen sending, so a robot on 3.9 or later never silently drops a plaintext command.
+- The connection loop never returns on a dropped broker; it backs off with jitter and reconnects.
+
+The same CLI can show what the library sees, stand up a fake robot from a fixture for development without hardware, and open the Studio, a local web UI for watching the protocol, documenting fields and saving fixtures (see `docs/studio.md`):
+
+```bash
+uv run yarbo-local status yarbo.localdomain --watch 30
+uv run yarbo-local sim protocol/fixtures/3.14.11/get_device_msg-asleep.jsonl --broker 127.0.0.1
+uv run yarbo-local studio yarbo.localdomain
+```
+
+## Can't see the base station in your router or controller?
+
+You won't. The base station bridges the rover's HaLow link onto your LAN behind a locally administered MAC that never associates with an access point or asks your DHCP server for an address. It picks a static address for itself, inside your DHCP pool, and it has no management page. Network controllers such as UniFi list clients by association or wired port, so the base station simply does not exist to them, even while it answers on ports 1883, 8883 and 22.
+
+Do not spend an afternoon on this. Scan the subnet instead:
+
+```bash
+uv run yarbo-local discover 192.168.1.0/24 --wait 8
+```
+
+Every host carrying Yarbo traffic is listed with the serial it carries and its DNS name, if it has one. A robot is identified by its own topics and nothing else; the tool reads no ARP table and runs no other program. The rover and the base station both answer, with the same data. Then protect yourself from the address collision Yarbo set up for you: either shrink your DHCP pool so it starts above the base station's address, or put the Yarbo Wi-Fi association on an isolated VLAN so the whole bridge moves out of your main network.
+
+## Safety and privacy
+
+The robot's broker has no authentication. Anyone on its network segment can drive it. Put the robot on its own VLAN, allow only the machine running this tooling (and later Home Assistant) to reach port 1883, and think deliberately about whether the robot should have internet access at all. Captures contain your serial number, coordinates and network details; use `--redact` and review the file before sharing it.
+
+## Have more than one robot?
+
+Nobody on the project does. One command tells us what we cannot find out ourselves, without sharing a serial, an address or a position: see [docs/multi-robot.md](docs/multi-robot.md).
+
+## Contributing protocol knowledge
+
+Read `protocol/README.md`. A command becomes `verified` only with a fixture showing the request and the reply on real hardware, with the firmware version recorded. Pull requests that add knowledge without evidence are asked for a capture.
+
+## Releasing
+
+Releases are published to PyPI by GitHub Actions through trusted publishing, with a manual approval and no token anywhere. See `docs/releasing.md`.
+
+## License and trademark
+
+MIT. Protocol facts were assembled from the vendor's MIT-licensed SDK, from `python-yarbo`, `home-assistant-yarbo`, the `jtubb` and `briangann` forks of the vendor integration, and the `steves2j` map editor; see `protocol/commands.yaml` for per-entry sources. Yarbo is a trademark of its owner. This project is not affiliated with, endorsed by, or supported by Yarbo.

yarbo_local-0.1.0.dev0/README.md

@@ -0,0 +1,111 @@
+# yarbo-local
+
+Local-first tooling and, later, the asyncio library behind a Home Assistant integration for Yarbo robots. It talks to the anonymous MQTT broker the robot runs on your LAN and to nothing else. No Yarbo account, no vendor servers, no telemetry.
+
+Status: **pre-alpha.** Phase 0 validated the protocol on real hardware (firmware 3.14.11) and produced the knowledge base in `protocol/`: 19 commands verified with captures, the rest marked as candidates that cannot be sent. The library core is in place: a registry-gated session, typed state, the map, a fixture-driven simulator and a small client. The Home Assistant integration ([yarbo-local-ha](https://github.com/yarbo-local/yarbo-local-ha)) shows the robot and its map but does not control it yet, and the dashboard card ([yarbo-local-card](https://github.com/yarbo-local/yarbo-local-card)) draws the map, the robot and plan progress. Next is plan control: pause, resume, stop and start, each verified against the robot first. Not on PyPI yet.
+
+## What is here
+
+| Path | Purpose |
+|---|---|
+| `src/yarbo_local/client.py` | `YarboRobot`: connect, read typed state, and run the verified reads. |
+| `src/yarbo_local/session.py` | The protocol layer: reconnect, reply correlation, encoding choice, wake and controller rules. |
+| `src/yarbo_local/registry.py` | The command allowlist loaded from `protocol/commands.yaml`. Forbidden names cannot be sent. |
+| `src/yarbo_local/models.py` | `RobotState` and the map, plan and GNSS parsers. No I/O. |
+| `src/yarbo_local/transport.py` | aiomqtt transport plus an in-memory fake for tests. |
+| `src/yarbo_local/simulator.py` | A robot built from fixtures, for tests and for developing without hardware. |
+| `src/yarbo_local/resolve.py` | Address resolution: last address, DNS name, subnet scan. |
+| `src/yarbo_local/fieldmap.py` | Builds `protocol/fields.yaml` from the curated seed and the fixtures. |
+| `src/yarbo_local/studio/` | The Studio: aiohttp server and Lit UI (`docs/studio.md`). |
+| `src/yarbo_local/codec.py` | zlib-or-plain JSON codec with the firmware rule and an observed-encoding fallback. |
+| `src/yarbo_local/capture.py` | `sniff`: subscribe to `snowbot/+/#` and write every message to JSONL, optionally redacted. |
+| `src/yarbo_local/probe.py` | `probe`: send one allowlisted command, show the correlated reply and the telemetry deltas. |
+| `src/yarbo_local/discover.py` | `discover`: find brokers carrying `snowbot` traffic, identified by the serial in their topics. |
+| `src/yarbo_local/dump.py` | `dump`: summarise a capture, including the full `DeviceMSG` key inventory. |
+| `src/yarbo_local/sitecheck.py` | `sitecheck`: check a site with one or several robots, reads only, and write a report that is safe to share (`docs/multi-robot.md`). |
+| `src/yarbo_local/redact.py` | Serial, MAC, IP, coordinate and Wi-Fi redaction for shareable fixtures. |
+| `protocol/` | The knowledge base: `commands.yaml`, `fields.yaml`, `codes.yaml`, `fixtures/`. |
+| `docs/phase0.md` | The twelve questions Phase 0 answers, with the exact commands. |
+
+## Quick start
+
+```bash
+git clone https://github.com/yarbo-local/yarbo-local
+cd yarbo-local
+uv sync --extra dev
+uv run yarbo-local discover 192.168.40.0/24
+uv run yarbo-local sniff 192.168.40.23 --out captures/idle.jsonl
+uv run yarbo-local dump captures/idle.jsonl --keys --app
+uv run yarbo-local probe 192.168.40.23 get_device_msg
+```
+
+`probe` only sends commands on a short allowlist of reads plus the wake-up command. It will not send anything that moves the robot, changes the map, or touches settings.
+
+## Using the library
+
+```python
+import asyncio
+from yarbo_local import YarboRobot
+
+
+async def main() -> None:
+    async with YarboRobot.for_host("192.168.50.184") as robot:
+        state = await robot.snapshot()
+        print(state.activity, state.battery, state.head_name)
+        for plan in await robot.plans():
+            print(plan.id, plan.name)
+        robot.on_state(lambda s: print("changed:", s.activity))
+        await asyncio.sleep(30)
+
+
+asyncio.run(main())
+```
+
+Rules the session enforces, on purpose:
+
+- Only commands in `protocol/commands.yaml` can be sent. Names in its `forbidden` section are not entries and can never be sent, with or without flags.
+- A command whose status is `candidate` is refused unless the session was opened with `allow_candidates=True`. The Home Assistant integration never does that; the Studio does.
+- A command with `risk: confirm` needs `confirmed=True` on the call.
+- The wake command and the controller role are used only when the command's flags say they are needed, and the controller is itself still a candidate.
+- Outbound encoding follows the robot's firmware, or what it has been seen sending, so a robot on 3.9 or later never silently drops a plaintext command.
+- The connection loop never returns on a dropped broker; it backs off with jitter and reconnects.
+
+The same CLI can show what the library sees, stand up a fake robot from a fixture for development without hardware, and open the Studio, a local web UI for watching the protocol, documenting fields and saving fixtures (see `docs/studio.md`):
+
+```bash
+uv run yarbo-local status yarbo.localdomain --watch 30
+uv run yarbo-local sim protocol/fixtures/3.14.11/get_device_msg-asleep.jsonl --broker 127.0.0.1
+uv run yarbo-local studio yarbo.localdomain
+```
+
+## Can't see the base station in your router or controller?
+
+You won't. The base station bridges the rover's HaLow link onto your LAN behind a locally administered MAC that never associates with an access point or asks your DHCP server for an address. It picks a static address for itself, inside your DHCP pool, and it has no management page. Network controllers such as UniFi list clients by association or wired port, so the base station simply does not exist to them, even while it answers on ports 1883, 8883 and 22.
+
+Do not spend an afternoon on this. Scan the subnet instead:
+
+```bash
+uv run yarbo-local discover 192.168.1.0/24 --wait 8
+```
+
+Every host carrying Yarbo traffic is listed with the serial it carries and its DNS name, if it has one. A robot is identified by its own topics and nothing else; the tool reads no ARP table and runs no other program. The rover and the base station both answer, with the same data. Then protect yourself from the address collision Yarbo set up for you: either shrink your DHCP pool so it starts above the base station's address, or put the Yarbo Wi-Fi association on an isolated VLAN so the whole bridge moves out of your main network.
+
+## Safety and privacy
+
+The robot's broker has no authentication. Anyone on its network segment can drive it. Put the robot on its own VLAN, allow only the machine running this tooling (and later Home Assistant) to reach port 1883, and think deliberately about whether the robot should have internet access at all. Captures contain your serial number, coordinates and network details; use `--redact` and review the file before sharing it.
+
+## Have more than one robot?
+
+Nobody on the project does. One command tells us what we cannot find out ourselves, without sharing a serial, an address or a position: see [docs/multi-robot.md](docs/multi-robot.md).
+
+## Contributing protocol knowledge
+
+Read `protocol/README.md`. A command becomes `verified` only with a fixture showing the request and the reply on real hardware, with the firmware version recorded. Pull requests that add knowledge without evidence are asked for a capture.
+
+## Releasing
+
+Releases are published to PyPI by GitHub Actions through trusted publishing, with a manual approval and no token anywhere. See `docs/releasing.md`.
+
+## License and trademark
+
+MIT. Protocol facts were assembled from the vendor's MIT-licensed SDK, from `python-yarbo`, `home-assistant-yarbo`, the `jtubb` and `briangann` forks of the vendor integration, and the `steves2j` map editor; see `protocol/commands.yaml` for per-entry sources. Yarbo is a trademark of its owner. This project is not affiliated with, endorsed by, or supported by Yarbo.

yarbo_local-0.1.0.dev0/docs/multi-robot.md

@@ -0,0 +1,73 @@
+# More than one robot
+
+Nobody on this project owns two Yarbos. Everything below is either measured on one robot, reasoned from the protocol, or proven against the simulator, and each line says which. If you have two or more robots, five minutes of your time settles the open questions: see [Check your site](#check-your-site).
+
+## How it works
+
+Every robot runs its own MQTT broker and puts its serial number in every topic (`snowbot/<serial>/...`). Two rovers on Wi-Fi are two brokers at two addresses. A robot sends a heartbeat every 2 s awake and every 5 s asleep (measured), so listening to a broker for six seconds hears every robot it carries.
+
+The serial is the robot's identity everywhere: the Home Assistant entry, its entities, its device, its obstacle log and its aerial photo alignment are all keyed by it. A rover and its base station relay answer with the same data at two addresses (measured); because both carry one serial, they are one robot.
+
+## What is handled
+
+| Situation | What happens | Basis |
+|---|---|---|
+| Two rovers, two addresses | One Home Assistant entry each. A subnet scan finds both. | simulated |
+| One robot at two addresses (rover and relay) | One entry. The second address is refused as already configured. Two sessions at once work through both. | measured |
+| One broker carrying several robots | Setup lists the robots and asks which one. A session for one robot subscribes to its serial alone. | simulated |
+| A DHCP lease moves, and robot A's old address now answers as robot B | The old address is refused because A is not heard there, and the subnet is scanned for A. | simulated |
+| Robots on different firmware | The encoding (zlib from 3.9, plain JSON before) is decided per robot. A sleeping robot says nothing about its firmware, so the first request may be a guess; a guess that gets no reply is retried the other way. | simulated |
+| Finding one robot again on a site with several | The scan stops the moment that robot is heard. | simulated |
+
+## What is not known
+
+1. **Does a base station ever relay more than one rover?** If it does, one address carries several serials. The code handles that, but nobody has seen it.
+2. **Do brokers limit how many clients may connect?** Home Assistant holds one session per robot, the phone app another.
+3. **Does the heartbeat interval hold on other firmware?** Discovery waits six seconds.
+
+## Not supported, on purpose
+
+Two robots on one map card. Each robot keeps its own map with its own reference point, so a card shows one robot. The Studio and the command line tools work with one robot per run.
+
+## Check your site
+
+```bash
+git clone https://github.com/yarbo-local/yarbo-local
+cd yarbo-local
+uv sync
+uv run yarbo-local sitecheck 192.168.50.0/24
+```
+
+Use the subnet your robots are on; a single IP or a comma list works too. It takes about a minute.
+
+**What it does to your robots: nothing.** It listens, and it sends three read requests (`get_device_msg`, `read_all_plan`, `get_map`). It does not wake a robot, does not take control away from the phone app, and cannot send anything that moves a robot.
+
+**What it writes:** `sitecheck-report.md` and `sitecheck.log` in the current directory. Serial numbers become `robot-1`, `robot-2`; addresses become `host-1`, `host-2`; positions are never written, only whether two of them match. Both files are safe to attach to a [GitHub issue](https://github.com/yarbo-local/yarbo-local/issues), and that is the whole request: run it, attach both files, and say whether the Yarbo app was open.
+
+Each finding has the same shape, so a failure tells us what to change:
+
+```
+[FAIL] heartbeat-window: a robot heartbeats more slowly than discovery waits
+  expected: every robot heard at least every 6s (we measured 2 s awake, 5 s asleep)
+  seen: robot-2 on host-1: 2 heartbeats in 12s, longest gap 9.0s
+  meaning: Discovery and address recovery listen for one window and would miss this robot. ...
+  send us: the report file, sitecheck-report.md, and sitecheck.log; both are already scrubbed
+```
+
+| Check | Question it answers |
+|---|---|
+| `found` | Can this machine reach any robot at all? |
+| `shared-broker` | Does any address carry more than one robot? The main open question. |
+| `heartbeat-window` | Is every robot heard within the six seconds discovery waits? |
+| `isolation` | Does a subscription for one serial ever deliver another robot's messages? |
+| `reads` | Does every robot answer reads through every address that carries it? |
+| `coexistence` | Do several sessions stay connected together? |
+| `identity` | Do replies come from the robot they were addressed to? Compared by position, never written. |
+| `encoding` | Does each robot's encoding match the firmware rule? |
+| `unscoped` | Does a session given no serial notice the robots it did not pick? |
+| `resolve` | From a stale address, is each robot found again at an address that really carries it? |
+| `maps` | Do robots share one map frame, or keep one each? |
+
+The same checks run under pytest, if you prefer: `uv run pytest tests/live --hosts 192.168.50.0/24 -v`.
+
+The tool is tested before it reaches you: `tests/test_sitecheck.py` runs it against simulated sites and hands it records of sites that misbehave, one per failure above, so a failure on your site is about your site.