go2tool 0.1.0__tar.gz

go2tool-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+uv.lock

go2tool-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2025 Dimensional Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

go2tool-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: go2tool
+Version: 0.1.0
+Summary: Set up Unitree Go2 robots: Bluetooth Wi-Fi provisioning and LAN/BLE discovery
+Project-URL: Homepage, https://github.com/jeff-hykin/go2tool
+Project-URL: Repository, https://github.com/jeff-hykin/go2tool
+Author: Dimensional Inc.
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: bluetooth,go2,robot,unitree,wifi
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: bleak>=1.0.0
+Requires-Dist: cryptography>=42
+Requires-Dist: psutil>=7.0.0
+Requires-Dist: typer<1,>=0.19.2
+Description-Content-Type: text/markdown
+
+# go2tool
+
+Set up a Unitree Go2 (Pro or Air, stock firmware) from your laptop: put it on Wi-Fi over Bluetooth and find its IP. No Unitree app, no jailbreak.
+
+Originally the `dimos go2tool` command from [dimOS](https://github.com/dimensionalOS/dimos); this is the same tool as a standalone package.
+
+## Install
+
+```bash
+pip install go2tool
+# or run it without installing
+uvx go2tool discover
+```
+
+Needs Bluetooth on the machine running it (macOS or Linux/BlueZ) for the BLE parts.
+
+## Usage
+
+1. Power on the Go2. It advertises over BLE immediately.
+
+2. (Optional) make sure the robot is detected:
+
+```bash
+go2tool discover
+```
+
+3. Provision Wi-Fi (one-time per network):
+
+```bash
+go2tool connect-wifi --ssid <wifi> --password <password>
+```
+
+Scans BLE and connects to the only robot it finds, or prompts you to pick if there are several. Use `--name Go2_49060`, `--serial <serial>` or `--mac <ble-mac>` to pick one non-interactively, and `--ap` to make the robot host a hotspot with that SSID/password instead of joining one.
+
+4. Find the robot's IP:
+
+```bash
+go2tool discover
+```
+
+Prints `SOURCE NAME IP MAC SERIAL` for every robot it sees over BLE and LAN, e.g.
+
+```
+SOURCE NAME           IP              MAC                 SERIAL
+BLE    Go2_49060      -               AA:BB:CC:DD:EE:FF   B42D4000P6PC49060
+LAN    -              192.168.1.42    -                   B42D4000P6PC49060
+```
+
+Options: `--lan` / `--ble` to use only one source, `--timeout 0` to keep listening, `--lan-tick` for the LAN poll interval.
+
+LAN discovery pins the UDP multicast probe to each real network interface, so it still works with Tailscale or other VPNs up.
+
+## Credits
+
+BLE provisioning protocol from the [UniPwn](https://github.com/Bin4ry/UniPwn) project's reverse engineering (exploit payload removed; only the normal provisioning flow the official app uses).
+
+## License
+
+Apache-2.0, Copyright 2025-2026 Dimensional Inc.

go2tool-0.1.0/README.md

@@ -0,0 +1,59 @@
+# go2tool
+
+Set up a Unitree Go2 (Pro or Air, stock firmware) from your laptop: put it on Wi-Fi over Bluetooth and find its IP. No Unitree app, no jailbreak.
+
+Originally the `dimos go2tool` command from [dimOS](https://github.com/dimensionalOS/dimos); this is the same tool as a standalone package.
+
+## Install
+
+```bash
+pip install go2tool
+# or run it without installing
+uvx go2tool discover
+```
+
+Needs Bluetooth on the machine running it (macOS or Linux/BlueZ) for the BLE parts.
+
+## Usage
+
+1. Power on the Go2. It advertises over BLE immediately.
+
+2. (Optional) make sure the robot is detected:
+
+```bash
+go2tool discover
+```
+
+3. Provision Wi-Fi (one-time per network):
+
+```bash
+go2tool connect-wifi --ssid <wifi> --password <password>
+```
+
+Scans BLE and connects to the only robot it finds, or prompts you to pick if there are several. Use `--name Go2_49060`, `--serial <serial>` or `--mac <ble-mac>` to pick one non-interactively, and `--ap` to make the robot host a hotspot with that SSID/password instead of joining one.
+
+4. Find the robot's IP:
+
+```bash
+go2tool discover
+```
+
+Prints `SOURCE NAME IP MAC SERIAL` for every robot it sees over BLE and LAN, e.g.
+
+```
+SOURCE NAME           IP              MAC                 SERIAL
+BLE    Go2_49060      -               AA:BB:CC:DD:EE:FF   B42D4000P6PC49060
+LAN    -              192.168.1.42    -                   B42D4000P6PC49060
+```
+
+Options: `--lan` / `--ble` to use only one source, `--timeout 0` to keep listening, `--lan-tick` for the LAN poll interval.
+
+LAN discovery pins the UDP multicast probe to each real network interface, so it still works with Tailscale or other VPNs up.
+
+## Credits
+
+BLE provisioning protocol from the [UniPwn](https://github.com/Bin4ry/UniPwn) project's reverse engineering (exploit payload removed; only the normal provisioning flow the official app uses).
+
+## License
+
+Apache-2.0, Copyright 2025-2026 Dimensional Inc.

go2tool-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "go2tool"
+version = "0.1.0"
+description = "Set up Unitree Go2 robots: Bluetooth Wi-Fi provisioning and LAN/BLE discovery"
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Dimensional Inc." }]
+requires-python = ">=3.10"
+dependencies = [
+    "typer>=0.19.2,<1",
+    "psutil>=7.0.0",
+    "bleak>=1.0.0",
+    "cryptography>=42",
+]
+keywords = ["unitree", "go2", "robot", "bluetooth", "wifi"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+]
+
+[project.urls]
+Homepage = "https://github.com/jeff-hykin/go2tool"
+Repository = "https://github.com/jeff-hykin/go2tool"
+
+[project.scripts]
+go2tool = "go2tool.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"

go2tool-0.1.0/src/go2tool/__init__.py

@@ -0,0 +1,17 @@
+# Copyright 2025-2026 Dimensional Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Unitree Go2 setup utilities: BLE Wi-Fi provisioning and network discovery."""
+
+__version__ = "0.1.0"

go2tool-0.1.0/src/go2tool/ble.py

@@ -0,0 +1,355 @@
+# Copyright 2025-2026 Dimensional Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""BLE wifi-provisioning protocol for Unitree robots.
+
+Protocol reverse-engineered by the UniPwn project (https://github.com/Bin4ry/UniPwn);
+this module strips the exploit payload and keeps only the legitimate provisioning
+flow used by the official Unitree app.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+UNITREE_NAME_PREFIXES = ("Go2_", "G1_", "B2_", "H1_", "X1_")
+
+UNITREE_SERVICE_UUID = "0000ffe0-0000-1000-8000-00805f9b34fb"
+NOTIFY_CHAR_UUID = "0000ffe1-0000-1000-8000-00805f9b34fb"
+WRITE_CHAR_UUID = "0000ffe2-0000-1000-8000-00805f9b34fb"
+
+# Symmetric AES-CFB-128 key/iv burned into the firmware.
+_AES_KEY = bytes.fromhex("df98b715d5c6ed2b25817b6f2554124a")
+_AES_IV = bytes.fromhex("2841ae97419c2973296a0d4bdfe19a4f")
+
+CHUNK_SIZE = 14
+HANDSHAKE_CONTENT = b"unitree"
+
+# Instruction opcodes (TX / RX use the same numbers; opcode byte differs: 0x52 / 0x51).
+INST_HANDSHAKE = 1
+INST_SERIAL = 2
+INST_INIT_STA = 3
+INST_SSID = 4
+INST_PASSWORD = 5
+INST_COUNTRY = 6
+
+
+@dataclass
+class Go2Device:
+    name: str
+    address: str
+    serial: str | None = None
+
+
+def _serial_from_manuf(manuf_data: dict[int, bytes] | None) -> str | None:
+    """Recover the full 16-char serial from BLE manufacturer data.
+
+    The Go2 packs its serial across the company-ID + payload field: the
+    company-ID's little-endian bytes spell the first two ASCII chars, the
+    payload spells the rest.
+    """
+    if not manuf_data:
+        return None
+    cid, payload = next(iter(manuf_data.items()))
+    prefix = bytes([cid & 0xFF, (cid >> 8) & 0xFF])
+    try:
+        return (prefix + payload).decode("ascii")
+    except UnicodeDecodeError:
+        return None
+
+
+def _cipher() -> Any:
+    from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+    return Cipher(algorithms.AES(_AES_KEY), modes.CFB(_AES_IV))
+
+
+def encrypt(data: bytes) -> bytes:
+    enc = _cipher().encryptor()
+    out: bytes = enc.update(data) + enc.finalize()
+    return out
+
+
+def decrypt(data: bytes) -> bytes:
+    dec = _cipher().decryptor()
+    out: bytes = dec.update(data) + dec.finalize()
+    return out
+
+
+def build_packet(instruction: int, payload: bytes = b"") -> bytes:
+    """Build an encrypted TX packet: 0x52, length, instruction, *payload, checksum."""
+    body = bytes([0x52, len(payload) + 4, instruction]) + payload
+    checksum = (-sum(body)) & 0xFF
+    return encrypt(body + bytes([checksum]))
+
+
+def validate_response(response: bytes, expected_inst: int) -> bool:
+    if len(response) < 5:
+        return False
+    if response[0] != 0x51:
+        return False
+    if len(response) != response[1]:
+        return False
+    if response[2] != expected_inst:
+        return False
+    if (-sum(response[:-1])) & 0xFF != response[-1]:
+        return False
+    return response[3] == 0x01
+
+
+async def _stop_stale_bluez_scan() -> None:
+    """Tell BlueZ to drop any leftover scan from a prior process.
+
+    `BleakScanner.__aexit__` is what normally calls StopDiscovery. If a previous
+    invocation was killed before that ran (e.g. SIGTERM from `timeout`), BlueZ
+    keeps the session and the next StartDiscovery returns `InProgress`. Best-effort.
+    """
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            "bluetoothctl",
+            "scan",
+            "off",
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        try:
+            await asyncio.wait_for(proc.wait(), timeout=2.0)
+        except asyncio.TimeoutError:
+            proc.kill()
+    except (FileNotFoundError, OSError):
+        pass
+
+
+async def discover_ble(
+    prefixes: tuple[str, ...] = UNITREE_NAME_PREFIXES,
+) -> AsyncIterator[Go2Device]:
+    """Stream Unitree robots seen over BLE. Runs until the consumer stops iterating.
+
+    Yields a device on first sighting, and again whenever a later adv packet
+    upgrades a previously-unknown serial number.
+    """
+    from bleak import BleakScanner
+
+    await _stop_stale_bluez_scan()
+
+    found: dict[str, Go2Device] = {}
+    queue: asyncio.Queue[Go2Device] = asyncio.Queue()
+
+    def _on_detect(device: Any, adv: Any) -> None:
+        if not device.name or not device.name.startswith(prefixes):
+            return
+        serial = _serial_from_manuf(getattr(adv, "manufacturer_data", None))
+        existing = found.get(device.address)
+        if existing is None:
+            dev = Go2Device(name=device.name, address=device.address, serial=serial)
+            found[device.address] = dev
+            queue.put_nowait(dev)
+        elif existing.serial is None and serial is not None:
+            existing.serial = serial
+            queue.put_nowait(existing)
+
+    async with BleakScanner(detection_callback=_on_detect):
+        while True:
+            yield await queue.get()
+
+
+async def find_robots(
+    timeout: float = 15.0,
+    prefixes: tuple[str, ...] = UNITREE_NAME_PREFIXES,
+    on_device: Callable[[Go2Device], None] | None = None,
+) -> list[Go2Device]:
+    """One-shot BLE scan: collects devices for `timeout` seconds and returns them."""
+    out: dict[str, Go2Device] = {}
+
+    async def _collect() -> None:
+        async for dev in discover_ble(prefixes=prefixes):
+            out[dev.address] = dev
+            if on_device is not None:
+                on_device(dev)
+
+    try:
+        await asyncio.wait_for(_collect(), timeout=timeout)
+    except asyncio.TimeoutError:
+        pass
+    return list(out.values())
+
+
+class _Session:
+    """Internal helper that wraps a BleakClient with the unitree request/response state."""
+
+    def __init__(self, client: Any) -> None:
+        self.client = client
+        self.event = asyncio.Event()
+        self.last: bytes | None = None
+        self.serial_chunks: dict[int, bytes] = {}
+        self.serial: bytes | None = None
+
+    def on_notify(self, _sender: Any, data: bytearray) -> None:
+        packet = decrypt(bytes(data))
+        if len(packet) < 5 or packet[0] != 0x51:
+            return
+        if packet[2] == INST_SERIAL:
+            idx, total = packet[3], packet[4]
+            self.serial_chunks[idx] = packet[5:-1]
+            if len(self.serial_chunks) >= total:
+                self.serial = b"".join(self.serial_chunks[i] for i in sorted(self.serial_chunks))
+                self.event.set()
+        else:
+            self.last = packet
+            self.event.set()
+
+    async def write(self, packet: bytes) -> None:
+        await self.client.write_gatt_char(WRITE_CHAR_UUID, packet, response=True)
+
+    async def write_validated(
+        self, packet: bytes, expected_inst: int, timeout: float = 10.0
+    ) -> None:
+        await self.write(packet)
+        await asyncio.wait_for(self.event.wait(), timeout)
+        if self.last is None or not validate_response(self.last, expected_inst):
+            raise RuntimeError(f"BLE response invalid for instruction {expected_inst}")
+        self.event.clear()
+        self.last = None
+
+    async def send_chunked(
+        self, instruction: int, data: bytes, response_timeout: float = 10.0
+    ) -> None:
+        total = max(1, (len(data) + CHUNK_SIZE - 1) // CHUNK_SIZE)
+        for i in range(total):
+            chunk = data[i * CHUNK_SIZE : (i + 1) * CHUNK_SIZE]
+            packet = build_packet(instruction, bytes([i + 1, total]) + chunk)
+            await self.write(packet)
+            await asyncio.sleep(0.1)
+        await asyncio.wait_for(self.event.wait(), response_timeout)
+        if self.last is None or not validate_response(self.last, instruction):
+            raise RuntimeError(f"BLE response invalid for chunked instruction {instruction}")
+        self.event.clear()
+        self.last = None
+
+
+async def _connect_with_retry(
+    address: str,
+    timeout: float,
+    attempts: int,
+    on_progress: Callable[[str], None],
+) -> Any:
+    """Open a BleakClient, retrying only the connection step."""
+    from bleak import BleakClient
+
+    last_exc: BaseException | None = None
+    for i in range(attempts):
+        client = BleakClient(address, timeout=timeout)
+        try:
+            await client.connect()
+            return client
+        except Exception as e:
+            last_exc = e
+            on_progress(f"connect attempt {i + 1}/{attempts} failed: {e}")
+            if i + 1 < attempts:
+                await asyncio.sleep(1.0)
+    assert last_exc is not None
+    raise last_exc
+
+
+async def provision_wifi(
+    address: str,
+    ssid: str,
+    password: str,
+    country_code: str = "US",
+    *,
+    ap: bool = False,
+    timeout: float = 30.0,
+    connect_retries: int = 3,
+    on_progress: Callable[[str], None] | None = None,
+) -> str | None:
+    """Provision a Unitree robot's wifi over BLE. Returns the serial number on success.
+
+    With `ap=True` the robot hosts its own hotspot named `ssid` instead of joining one.
+
+    Retries the BLE connection step up to `connect_retries` times. Once connected,
+    handshake/SSID/password/country failures are not retried — those indicate a
+    protocol-level problem (or partial state on the robot) where blind retry is
+    counterproductive.
+    """
+    progress = on_progress or (lambda _msg: None)
+
+    client = await _connect_with_retry(address, timeout, connect_retries, progress)
+    try:
+        session = _Session(client)
+        try:
+            await client.start_notify(NOTIFY_CHAR_UUID, session.on_notify)
+        except Exception:
+            # Some firmware versions only expose the raw GATT handle.
+            await client.start_notify(13, session.on_notify)  # type: ignore[arg-type]
+
+        progress("handshake")
+        await session.write_validated(
+            build_packet(INST_HANDSHAKE, bytes([0, 0]) + HANDSHAKE_CONTENT),
+            INST_HANDSHAKE,
+        )
+
+        progress("read serial")
+        await session.write(build_packet(INST_SERIAL, bytes([0])))
+        try:
+            await asyncio.wait_for(session.event.wait(), 2.0)
+        except asyncio.TimeoutError:
+            pass
+        session.event.clear()
+
+        progress(f"init {'AP' if ap else 'STA'} mode")
+        await session.write_validated(
+            build_packet(INST_INIT_STA, bytes([1 if ap else 2])), INST_INIT_STA
+        )
+
+        progress(f"set SSID: {ssid}")
+        await session.send_chunked(INST_SSID, ssid.encode("utf-8"))
+
+        progress("set password")
+        await session.send_chunked(INST_PASSWORD, password.encode("utf-8"), response_timeout=5.0)
+
+        progress(f"set country: {country_code}")
+        await session.write_validated(
+            build_packet(INST_COUNTRY, bytes([1]) + country_code.encode("utf-8") + b"\x00"),
+            INST_COUNTRY,
+        )
+    finally:
+        await client.disconnect()
+
+    if session.serial:
+        return session.serial.decode("utf-8", errors="replace").rstrip("\x00")
+    return None
+
+
+async def retry(
+    fn: Callable[[], Awaitable[Any]],
+    attempts: int = 3,
+    delay: float = 1.0,
+    on_error: Callable[[int, BaseException], None] | None = None,
+) -> Any:
+    """Retry an awaitable a few times. Re-raises the final exception."""
+    last_exc: BaseException | None = None
+    for i in range(attempts):
+        try:
+            return await fn()
+        except Exception as e:
+            last_exc = e
+            if on_error:
+                on_error(i + 1, e)
+            if i + 1 < attempts:
+                await asyncio.sleep(delay)
+    assert last_exc is not None
+    raise last_exc

go2tool-0.1.0/src/go2tool/cli.py

@@ -0,0 +1,209 @@
+# Copyright 2025-2026 Dimensional Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""`go2tool` — Go2 setup utilities (BLE wifi provisioning, network discovery)."""
+
+from __future__ import annotations
+
+import asyncio
+
+import typer
+
+app = typer.Typer(
+    help="Go2 setup utilities (BLE wifi provisioning, network discovery)",
+    no_args_is_help=True,
+)
+
+
+_HEADER = f"{'SOURCE':<6} {'NAME':<14} {'IP':<15} {'MAC':<19} SERIAL"
+
+
+def _format_row(source: str, name: str, ip: str, mac: str, serial: str) -> str:
+    return f"{source:<6} {name:<14} {ip:<15} {mac:<19} {serial}"
+
+
+@app.command("discover")
+def discover(
+    ble: bool = typer.Option(False, "--ble", help="BLE only (default: BLE + LAN)"),
+    lan: bool = typer.Option(False, "--lan", help="LAN only (default: BLE + LAN)"),
+    lan_tick: float = typer.Option(2.0, "--lan-tick", help="LAN poll interval (s)"),
+    timeout: float = typer.Option(
+        7.0, "--timeout", "-t", help="Stop after this many seconds (0 = run forever)"
+    ),
+) -> None:
+    """Stream Go2 robot discoveries from BLE and/or LAN."""
+    do_ble = ble or not lan
+    do_lan = lan or not ble
+
+    typer.echo(_HEADER)
+
+    import signal
+
+    async def run() -> None:
+        from go2tool.ble import discover_ble
+        from go2tool.landiscovery import discover_lan
+
+        seen_ble: set[tuple[str, str | None]] = set()
+        seen_lan: set[str] = set()
+
+        async def _consume_ble() -> None:
+            async for d in discover_ble():
+                key = (d.address, d.serial)
+                if key in seen_ble:
+                    continue
+                seen_ble.add(key)
+                typer.echo(_format_row("BLE", d.name, "-", d.address, d.serial or "?"))
+
+        async def _consume_lan() -> None:
+            async for d in discover_lan(tick=lan_tick):
+                if d.serial in seen_lan:
+                    continue
+                seen_lan.add(d.serial)
+                typer.echo(_format_row("LAN", "-", d.ip, d.mac or "-", d.serial))
+
+        tasks: list[asyncio.Task[None]] = []
+        if do_ble:
+            tasks.append(asyncio.create_task(_consume_ble()))
+        if do_lan:
+            tasks.append(asyncio.create_task(_consume_lan()))
+
+        # Cancel on SIGINT or SIGTERM so the BleakScanner's __aexit__ runs and
+        # calls StopDiscovery; otherwise BlueZ retains the scan session.
+        loop = asyncio.get_running_loop()
+
+        def _stop() -> None:
+            for t in tasks:
+                t.cancel()
+
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            loop.add_signal_handler(sig, _stop)
+
+        if timeout > 0:
+            loop.call_later(timeout, _stop)
+
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+    asyncio.run(run())
+    typer.echo("\nStopped.")
+
+
+@app.command("connect-wifi")
+def connect_wifi(
+    ssid: str | None = typer.Option(None, "--ssid", help="Wi-Fi SSID"),
+    password: str | None = typer.Option(None, "--password", help="Wi-Fi password"),
+    country: str = typer.Option("US", "--country", help="Two-letter country code"),
+    ap: bool = typer.Option(False, "--ap", help="Host a hotspot with --ssid/--password instead"),
+    mac: str | None = typer.Option(None, "--mac", help="BLE MAC (skip scan)"),
+    serial: str | None = typer.Option(
+        None, "--serial", help="Robot serial — scan and auto-select match"
+    ),
+    name: str | None = typer.Option(
+        None, "--name", help="Robot BLE name (e.g. Go2_49060) — scan and auto-select match"
+    ),
+    timeout: float = typer.Option(5.0, "--timeout", help="Scan / connect timeout in seconds"),
+    retries: int = typer.Option(3, "--retries", help="Number of provisioning attempts"),
+) -> None:
+    """Provision a Go2 with Wi-Fi credentials over Bluetooth.
+
+    Fully non-interactive when (--mac | --serial | --name) and --ssid/--password
+    are all provided.
+    """
+    from go2tool.ble import (
+        Go2Device,
+        find_robots,
+        provision_wifi,
+        retry,
+    )
+
+    async def run() -> None:
+        if mac is not None:
+            target = mac
+        else:
+            typer.echo(f"Scanning BLE for {timeout:.0f}s ...")
+
+            def _on_device(d: Go2Device) -> None:
+                typer.echo(_format_row("BLE", d.name, "-", d.address, d.serial or "?"))
+
+            devices = await find_robots(timeout=timeout, on_device=_on_device)
+            if not devices:
+                typer.echo("No Unitree robots detected.", err=True)
+                raise typer.Exit(1)
+
+            if serial is not None or name is not None:
+                matches = [
+                    d
+                    for d in devices
+                    if (serial is None or d.serial == serial) and (name is None or d.name == name)
+                ]
+                if not matches:
+                    crit = ", ".join(
+                        f"{k}={v}" for k, v in (("serial", serial), ("name", name)) if v is not None
+                    )
+                    typer.echo(f"No BLE device matched {crit}.", err=True)
+                    raise typer.Exit(1)
+                if len(matches) > 1:
+                    typer.echo(f"{len(matches)} devices match — refine criteria:", err=True)
+                    for d in matches:
+                        typer.echo(f"  {d.name} {d.address} serial={d.serial}", err=True)
+                    raise typer.Exit(1)
+                target = matches[0].address
+            else:
+                typer.echo("")
+                typer.echo("Found:")
+                for i, d in enumerate(devices, 1):
+                    typer.echo(f"  {i}. {d.name} ({d.address})")
+                default = "1" if len(devices) == 1 else None
+                idx = typer.prompt("Select device", default=default, type=int)
+                if not 1 <= idx <= len(devices):
+                    typer.echo("Invalid selection.", err=True)
+                    raise typer.Exit(1)
+                target = devices[idx - 1].address
+
+        wifi_ssid = ssid if ssid is not None else typer.prompt("Wi-Fi SSID")
+        wifi_password = (
+            password
+            if password is not None
+            else typer.prompt("Wi-Fi password", hide_input=True, default="", show_default=False)
+        )
+
+        def _on_error(attempt: int, exc: BaseException) -> None:
+            typer.echo(f"  attempt {attempt} failed: {exc}", err=True)
+
+        device_serial = await retry(
+            lambda: provision_wifi(
+                target,  # type: ignore[arg-type]
+                wifi_ssid,
+                wifi_password,
+                country,
+                ap=ap,
+                on_progress=lambda m: typer.echo(f"  {m}"),
+            ),
+            attempts=retries,
+            on_error=_on_error,
+        )
+
+        if device_serial:
+            typer.echo(f"✓ Provisioned. Serial: {device_serial}")
+        else:
+            typer.echo("✓ Provisioned.")
+
+    asyncio.run(run())
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

go2tool-0.1.0/src/go2tool/landiscovery.py

@@ -0,0 +1,214 @@
+# Copyright 2025-2026 Dimensional Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""LAN discovery for Unitree Go2 robots.
+
+Go2s respond to a custom UDP-multicast probe (group 231.1.1.1, port 10131)
+with a JSON payload containing their serial number and IP. This module sends
+that probe and collects replies on port 10134.
+
+Implemented from scratch (rather than reusing legion1581/unitree_webrtc_connect's
+scanner) so we can pin the multicast send/recv to a specific interface — Tailscale
+and other VPN tun devices install a 224.0.0.0/4 route in a separate table that
+silently swallows the probe otherwise.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Iterator
+from dataclasses import dataclass
+import json
+import socket
+import struct
+import time
+
+import logging
+
+import psutil
+
+logger = logging.getLogger(__name__)
+
+MULTICAST_GROUP = "231.1.1.1"
+QUERY_PORT = 10131
+REPLY_PORT = 10134
+QUERY_PAYLOAD = json.dumps({"name": "unitree_dapengche"}).encode("utf-8")
+
+
+@dataclass(frozen=True)
+class Go2Device:
+    serial: str
+    ip: str
+    iface: str
+    mac: str | None = None
+
+
+def _read_arp(ip: str) -> str | None:
+    try:
+        with open("/proc/net/arp") as f:
+            for line in f.readlines()[1:]:
+                parts = line.split()
+                if len(parts) >= 4 and parts[0] == ip and parts[3] != "00:00:00:00:00:00":
+                    return parts[3].upper()
+    except OSError:
+        return None
+    return None
+
+
+def _resolve_mac(ip: str, retries: int = 3, retry_delay: float = 0.05) -> str | None:
+    """Resolve MAC for `ip` via /proc/net/arp; nudges the cache with a probe UDP send.
+
+    Linux-only. Returns None if the address can't be resolved (e.g. on macOS).
+    """
+    cached = _read_arp(ip)
+    if cached:
+        return cached
+    for _ in range(retries):
+        try:
+            s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            try:
+                s.sendto(b"", (ip, 9))  # discard port — kernel ARPs before send
+            except OSError:
+                pass
+            s.close()
+        except OSError:
+            pass
+        time.sleep(retry_delay)
+        mac = _read_arp(ip)
+        if mac:
+            return mac
+    return None
+
+
+def _candidate_ifaces() -> Iterator[tuple[str, str]]:
+    """Yield (iface_name, ipv4_addr) for non-loopback, non-tun IPv4 interfaces."""
+    skip_prefixes = ("lo", "tailscale", "wg", "tun", "docker", "br-", "veth", "Meta")
+    for name, addrs in psutil.net_if_addrs().items():
+        if name.startswith(skip_prefixes):
+            continue
+        for a in addrs:
+            if a.family == socket.AF_INET and not a.address.startswith("127."):
+                yield name, a.address
+                break
+
+
+def discover(timeout: float = 2.0, iface_ip: str | None = None) -> list[Go2Device]:
+    """Probe the LAN for Go2 robots.
+
+    Args:
+        timeout: seconds to wait for replies after sending the probe.
+        iface_ip: pin multicast to this local IPv4 address. If None, probe every
+            non-tunnel interfacel.
+    """
+    targets: list[tuple[str | None, str]] = (
+        [(None, iface_ip)] if iface_ip else list(_candidate_ifaces())
+    )
+    if not targets:
+        logger.warning("no usable interfaces found for Go2 discovery")
+        return []
+
+    found: dict[str, Go2Device] = {}
+    for name, ip in targets:
+        for dev in _probe_iface(ip, timeout):
+            dev = Go2Device(
+                serial=dev.serial, ip=dev.ip, iface=name or "?", mac=_resolve_mac(dev.ip)
+            )
+            found.setdefault(dev.serial, dev)
+    return list(found.values())
+
+
+def _probe_iface(iface_ip: str, timeout: float) -> Iterator[Go2Device]:
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    try:
+        sock.bind(("", REPLY_PORT))
+    except OSError as e:
+        logger.warning(f"could not bind UDP {REPLY_PORT} on {iface_ip}: {e}")
+        sock.close()
+        return
+
+    iface_addr = socket.inet_aton(iface_ip)
+    sock.setsockopt(socket.IPPROTO_IP, socket.IP_MULTICAST_IF, iface_addr)
+    sock.setsockopt(
+        socket.IPPROTO_IP,
+        socket.IP_ADD_MEMBERSHIP,
+        struct.pack("4s4s", socket.inet_aton(MULTICAST_GROUP), iface_addr),
+    )
+
+    try:
+        sock.sendto(QUERY_PAYLOAD, (MULTICAST_GROUP, QUERY_PORT))
+    except OSError as e:
+        logger.warning(f"multicast send failed on {iface_ip}: {e}")
+        sock.close()
+        return
+
+    sock.settimeout(timeout)
+    try:
+        while True:
+            try:
+                data, addr = sock.recvfrom(1024)
+            except TimeoutError:
+                return
+            try:
+                msg = json.loads(data.decode("utf-8"))
+            except (UnicodeDecodeError, json.JSONDecodeError):
+                continue
+            sn = msg.get("sn")
+            if not sn:
+                continue
+            yield Go2Device(serial=sn, ip=msg.get("ip", addr[0]), iface=iface_ip)
+    finally:
+        sock.close()
+
+
+async def discover_lan(
+    tick: float = 2.0,
+    timeout: float = 1.5,
+    iface_ip: str | None = None,
+) -> AsyncIterator[Go2Device]:
+    """Stream Go2 LAN discoveries. Polls multicast every `tick` seconds.
+
+    Yields each device on every poll cycle it shows up in (so consumers see the
+    device repeatedly while it remains alive on the network).
+    """
+    while True:
+        loop = asyncio.get_running_loop()
+        devs = await loop.run_in_executor(
+            None, lambda: discover(timeout=timeout, iface_ip=iface_ip)
+        )
+        for d in devs:
+            yield d
+        await asyncio.sleep(max(0.0, tick - timeout))
+
+
+def main() -> None:
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Discover Unitree Go2 robots on the LAN")
+    parser.add_argument("--timeout", type=float, default=2.0)
+    parser.add_argument(
+        "--iface-ip", help="pin probe to this local IPv4 (default: all non-tunnel ifaces)"
+    )
+    args = parser.parse_args()
+
+    devices = discover(timeout=args.timeout, iface_ip=args.iface_ip)
+    if not devices:
+        print("no Go2s found")
+        return
+    for d in devices:
+        print(f"{d.serial}\t{d.ip}\t(via {d.iface})")
+
+
+if __name__ == "__main__":
+    main()