dotbot/cli/gateway: add host-side Mari gateway bridge subcommand

Thin re-mount of marilib's mari-edge: bridges UART <-> MQTT. With no
--mqtt-url, runs in local-stdout mode (prints received frames) so a
freshly-flashed gateway can be checked with zero broker infra.

AI-assisted: Claude Opus 4.7

Author: geonnave

dotbot/cli/gateway.py

@@ -0,0 +1,104 @@
+# SPDX-FileCopyrightText: 2026-present Inria
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""`dotbot gateway` — host-side Mari gateway bridge.
+
+Runs on whatever computer the gateway firmware is plugged into (a
+laptop for a starter setup, a Pi for a permanent install). Bridges UART
+HDLC frames to/from an MQTT broker, so a `dotbot controller --conn
+mqtts://…` can reach the swarm from anywhere.
+
+Thin re-mount of marilib's `mari-edge`: wraps a `MarilibEdge` with a
+serial adapter and (optionally) an MQTT adapter. With no `--mqtt-url`
+it runs in **local-stdout mode** — received frames print to stdout, so
+a freshly-flashed gateway can be sanity-checked with zero MQTT infra.
+
+Phase 1 is a raw bridge (mari frames + raw mari topics). DotBot-semantic
+MQTT topics are a later phase, tracked in the controller-CLI-redesign
+plan.
+"""
+
+import os
+import time
+
+import click
+
+
+def _run_gateway(port, mqtt_url):  # pragma: no cover - needs a real gateway
+    """Construct a MarilibEdge bridge and pump it until interrupted.
+
+    Imports marilib lazily so `dotbot gateway --help` is cheap and the
+    command is importable without a serial port present.
+    """
+    from marilib.communication_adapter import MQTTAdapter, SerialAdapter
+    from marilib.marilib_edge import MarilibEdge
+    from marilib.model import EdgeEvent
+    from marilib.serial_uart import get_default_port
+
+    port = port or get_default_port()
+    stdout_mode = mqtt_url is None
+
+    def on_event(event, event_data):
+        # In local-stdout mode, surface received data frames so a fresh
+        # gateway can be eyeballed without a broker.
+        if stdout_mode and event == EdgeEvent.NODE_DATA:
+            src = getattr(event_data.header, "source", 0)
+            payload = getattr(event_data, "payload", b"")
+            click.echo(f"<- {src:016x}: {bytes(payload).hex()}")
+
+    mqtt_interface = None
+    if mqtt_url is not None:
+        # Broker credentials come from the environment (see the controller
+        # surface). They take effect once the marilib companion adds
+        # username/password to MQTTAdapter; until then anonymous connect.
+        mqtt_interface = MQTTAdapter.from_url(mqtt_url, is_edge=True)
+        _ = (os.environ.get("DOTBOT_MQTT_USER"), os.environ.get("DOTBOT_MQTT_PASS"))
+
+    mari = MarilibEdge(
+        on_event,
+        serial_interface=SerialAdapter(port),
+        mqtt_interface=mqtt_interface,
+    )
+    where = mqtt_url if mqtt_url else "local-stdout"
+    click.echo(f"dotbot gateway: {port} <-> {where}", err=True)
+    try:
+        while True:
+            mari.update()
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        try:
+            mari.close()
+        except Exception:  # pylint: disable=broad-except
+            pass
+
+
+@click.command(
+    name="gateway",
+    help=(
+        "Host-side Mari gateway bridge (UART <-> MQTT). Runs wherever the "
+        "gateway firmware is plugged in. Without --mqtt-url, prints received "
+        "frames to stdout (local debug mode)."
+    ),
+)
+@click.option(
+    "-p",
+    "--port",
+    type=str,
+    default=None,
+    help="Serial port of the attached gateway firmware. Default: autodetect.",
+)
+@click.option(
+    "-m",
+    "--mqtt-url",
+    type=str,
+    default=None,
+    help=(
+        "MQTT broker to bridge to (`mqtts://host:port`). Absent → "
+        "local-stdout debug mode."
+    ),
+)
+def cmd(port, mqtt_url):
+    """Run the gateway bridge."""
+    _run_gateway(port, mqtt_url)

dotbot/cli/main.py

@@ -38,7 +38,12 @@
     (
         "sim",
         "dotbot.cli.sim",
-        "Standalone simulator (equivalent to controller --adapter dotbot-simulator).",
+        "Standalone simulator (equivalent to controller --conn simulator).",
+    ),
+    (
+        "gateway",
+        "dotbot.cli.gateway",
+        "Host-side Mari gateway bridge (UART <-> MQTT).",
     ),
     (
         "swarm",

dotbot/tests/test_cli_dispatcher.py

@@ -44,6 +44,7 @@
 EXPECTED_SUBCOMMANDS = {
     "controller",
     "sim",
+    "gateway",
     "swarm",
     "calibrate-lh2",
     "demo",

dotbot/tests/test_gateway.py

@@ -0,0 +1,42 @@
+# SPDX-FileCopyrightText: 2026-present Inria
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Tests for `dotbot gateway` — the CLI surface, not the live bridge.
+
+The bridge itself (`_run_gateway`) needs a real serial gateway, so it's
+mocked here; we check flag parsing and that the command forwards
+`--port` / `--mqtt-url` correctly.
+"""
+
+from unittest.mock import patch
+
+from click.testing import CliRunner
+
+from dotbot.cli.gateway import cmd as gateway_cmd
+
+
+def test_gateway_help_mentions_stdout_mode():
+    result = CliRunner().invoke(gateway_cmd, ["--help"])
+    assert result.exit_code == 0
+    assert "--port" in result.output
+    assert "--mqtt-url" in result.output
+    # The no-broker default behaviour is documented.
+    assert "stdout" in result.output.lower()
+
+
+@patch("dotbot.cli.gateway._run_gateway")
+def test_gateway_forwards_port_and_mqtt_url(run):
+    result = CliRunner().invoke(
+        gateway_cmd,
+        ["--port", "/dev/ttyACM0", "--mqtt-url", "mqtts://argus:8883"],
+    )
+    assert result.exit_code == 0, result.output
+    run.assert_called_once_with("/dev/ttyACM0", "mqtts://argus:8883")
+
+
+@patch("dotbot.cli.gateway._run_gateway")
+def test_gateway_defaults_to_stdout_mode_no_mqtt(run):
+    result = CliRunner().invoke(gateway_cmd, ["--port", "/dev/ttyACM0"])
+    assert result.exit_code == 0, result.output
+    # mqtt_url is None → local-stdout mode.
+    run.assert_called_once_with("/dev/ttyACM0", None)