brickremote 0.3.0__py3-none-any.whl

brickremote/__init__.py

@@ -0,0 +1,8 @@
+"""Control JG_JMC-xxxx Bluetooth LE motor modules (Lego-compatible, "XP Block" app)."""
+
+from .car import Car
+from .module import JMCModule, discover, find
+from .protocol import GEARS, Status, motor_frame, parse_status, stop_frame
+
+__all__ = ["GEARS", "Car", "JMCModule", "Status", "discover", "find", "motor_frame", "parse_status", "stop_frame"]
+__version__ = "0.3.0"

brickremote/car.py

@@ -0,0 +1,40 @@
+"""Convenience wrapper for a car with one drive motor and one steering motor."""
+
+from __future__ import annotations
+
+from .module import JMCModule
+
+
+class Car:
+    """A car built on a JMCModule.
+
+    Defaults match the stock car: drive motor on port A (positive = forward),
+    steering on port D (positive = left, self-centring when stopped).
+    """
+
+    def __init__(self, module: JMCModule, *, drive_port: str = "a", steer_port: str = "d",
+                 invert_drive: bool = False, invert_steer: bool = False):
+        self.module = module
+        self.drive_port, self.steer_port = drive_port, steer_port
+        self._drive_sign = -1 if invert_drive else 1
+        self._steer_sign = -1 if invert_steer else 1
+
+    async def drive(self, speed: int, steer: int = 0) -> None:
+        """speed: -255..255 (positive = forward); steer: -255..255 (positive = left)."""
+        await self.module.drive(**{self.drive_port: self._drive_sign * speed,
+                                   self.steer_port: self._steer_sign * steer})
+
+    async def forward(self, speed: int = 255) -> None:
+        await self.drive(speed)
+
+    async def backward(self, speed: int = 255) -> None:
+        await self.drive(-speed)
+
+    async def left(self, speed: int = 255, steer: int = 255) -> None:
+        await self.drive(speed, steer)
+
+    async def right(self, speed: int = 255, steer: int = 255) -> None:
+        await self.drive(speed, -steer)
+
+    async def stop(self) -> None:
+        await self.module.stop()

brickremote/cli.py

@@ -0,0 +1,131 @@
+"""Control JG_JMC motor modules: `brickremote` (remote control), `scan`, `run`, `program`, `path`."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+
+from . import protocol, script
+from .car import Car
+from .module import JMCModule, discover
+
+
+async def _scan(args) -> None:
+    devices = await discover(args.timeout, settle=None if args.full else 2.0,
+                             on_found=lambda dev: print(f"{dev.address}  {(dev.name or '').strip()}", flush=True))
+    if not devices:
+        print("no modules found - is it switched on, and not connected to anything else?")
+
+
+async def _wait_battery(module: JMCModule) -> None:
+    for _ in range(20):  # the first status report takes a moment
+        if module.battery is not None:
+            print(f"battery: {module.battery}%")
+            return
+        await asyncio.sleep(0.1)
+
+
+def _connect(args) -> JMCModule:
+    return JMCModule(args.address, slot=args.slot, six_ports=args.six_ports, inverted=args.invert)
+
+
+async def _run(args) -> None:
+    speeds = {}
+    for item in args.speeds:
+        port, _, value = item.partition("=")
+        if port.lower() not in protocol.PORTS or not value:
+            raise SystemExit(f"bad argument {item!r}; expected e.g. a=255 or d=-120")
+        speeds[port.lower()] = int(value)
+    async with _connect(args) as module:
+        await _wait_battery(module)
+        await module.run(args.time, **speeds)
+
+
+async def _program(args) -> None:
+    try:
+        steps = script.parse_program(args.file.read())
+    except script.ScriptError as exc:
+        raise SystemExit(f"error: {exc}")
+    async with _connect(args) as module:
+        await _wait_battery(module)
+        await script.run_program(module, steps, gear=args.gear)
+
+
+async def _path(args) -> None:
+    try:
+        moves = script.parse_path(args.file.read())
+    except script.ScriptError as exc:
+        raise SystemExit(f"error: {exc}")
+    cal = script.Calibration(args.mps, args.dps)
+    async with _connect(args) as module:
+        await _wait_battery(module)
+        await script.run_path(Car(module, drive_port=args.drive, steer_port=args.steer), moves, cal)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="brickremote", description=__doc__)
+    parser.add_argument("--address", help="module address (default: first one found)")
+    parser.add_argument("--slot", type=int, default=1, help="module slot 1-3 (default 1)")
+    parser.add_argument("--six-ports", action="store_true", help="module has ports E and F")
+    parser.add_argument("--invert", default="", metavar="PORTS", help="ports to reverse, e.g. --invert ad")
+    parser.add_argument("--drive", default="a", help="car drive port (default a)")
+    parser.add_argument("--steer", default="d", help="car steering port (default d)")
+    parser.add_argument("--log", metavar="FILE", help="write a debug log (keys and commands sent) to FILE")
+    sub = parser.add_subparsers(dest="command")
+
+    scan = sub.add_parser("scan", help="list nearby modules")
+    scan.add_argument("--timeout", type=float, default=10.0, help="give up after this many seconds (default 10)")
+    scan.add_argument("--full", action="store_true", help="always scan the whole timeout, to find every module")
+    scan.set_defaults(func=_scan)
+
+    run = sub.add_parser("run", help="run ports for a while, e.g. `run a=255 d=-255 --time 2`")
+    run.add_argument("speeds", nargs="+", metavar="PORT=SPEED", help="speed -255..255 per port (a-f)")
+    run.add_argument("--time", type=float, default=2.0, help="seconds to run (default 2)")
+    run.set_defaults(func=_run)
+
+    prog = sub.add_parser("program", help="run a program script ('-' for stdin)",
+                          description=script.__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    prog.add_argument("file", type=argparse.FileType())
+    prog.add_argument("--gear", type=int, default=3, choices=(1, 2, 3), help="initial gear (default 3)")
+    prog.set_defaults(func=_program)
+
+    path = sub.add_parser("path", help="drive a path script ('-' for stdin)",
+                          description=script.__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    path.add_argument("file", type=argparse.FileType())
+    path.add_argument("--mps", type=float, default=0.5, help="metres per second at full speed (default 0.5)")
+    path.add_argument("--dps", type=float, default=90.0, help="degrees per second when turning (default 90)")
+    path.set_defaults(func=_path)
+
+    web = sub.add_parser("web", help="start the web remote control (open it in any browser on the network)")
+    web.add_argument("--port", type=int, default=8080, help="port to listen on (default 8080)")
+    web.add_argument("--host", default="0.0.0.0", help="address to listen on (default: all)")
+    web.set_defaults(func=None)
+
+    args = parser.parse_args()
+    if args.log:
+        logging.basicConfig(filename=args.log, level=logging.DEBUG,
+                            format="%(asctime)s %(name)s %(message)s")
+        logging.getLogger("bleak").setLevel(logging.INFO)
+    if args.command is None:
+        from . import tui
+        tui.run(args.address, args.drive, args.steer)
+        return
+    if args.command == "web":
+        try:
+            from . import web as webapp
+        except ImportError:
+            sys.exit("The web remote needs aiohttp: pip install 'brickremote[web]'")
+        webapp.run(args.address, args.drive, args.steer, args.host, args.port)
+        return
+    try:
+        asyncio.run(args.func(args))
+    except ConnectionError as exc:
+        sys.exit(f"error: {exc}")
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

brickremote/module.py

@@ -0,0 +1,208 @@
+"""Async client for a JG_JMC-xxxx motor module."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import shutil
+from collections.abc import Callable, Iterable
+
+from bleak import BleakClient, BleakScanner
+from bleak.backends.device import BLEDevice
+
+from . import protocol
+from .protocol import Status
+
+log = logging.getLogger(__name__)
+
+
+async def discover(timeout: float = 10.0, settle: float | None = 2.0,
+                   on_found: Callable[[BLEDevice], None] | None = None) -> list[BLEDevice]:
+    """Scan for modules.
+
+    Stops `settle` seconds after the last new module appeared (None = always scan the full
+    `timeout`), or after `timeout` seconds. `on_found` is called as each module is seen.
+    """
+    found: dict[str, BLEDevice] = {}
+    last_new = asyncio.Event()
+
+    def seen(dev: BLEDevice, adv) -> None:
+        if dev.address not in found and (adv.local_name or dev.name or "").startswith(protocol.NAME_PREFIX):
+            found[dev.address] = dev
+            last_new.set()
+            if on_found:
+                on_found(dev)
+
+    async with BleakScanner(seen):
+        deadline = asyncio.get_running_loop().time() + timeout
+        while (remaining := deadline - asyncio.get_running_loop().time()) > 0:
+            wait = remaining if settle is None or not found else min(settle, remaining)
+            last_new.clear()
+            try:
+                await asyncio.wait_for(last_new.wait(), wait)
+            except asyncio.TimeoutError:
+                if found and settle is not None:
+                    break
+    return list(found.values())
+
+
+async def find(address: str | None = None, timeout: float = 10.0) -> BLEDevice | None:
+    """Find one module, by address if given, otherwise the first one advertising."""
+    if address:
+        return await BleakScanner.find_device_by_address(address, timeout=timeout)
+    return await BleakScanner.find_device_by_filter(
+        lambda dev, adv: (adv.local_name or dev.name or "").startswith(protocol.NAME_PREFIX),
+        timeout=timeout)
+
+
+class JMCModule:
+    """A connected motor module.
+
+    The current motor state is resent every `resend_interval` seconds while
+    connected, which keeps the module awake and recovers from dropped writes.
+
+        async with JMCModule() as m:
+            await m.drive(a=255)
+            await asyncio.sleep(2)
+            await m.stop()
+
+    `inverted` flips the direction of the given ports (like the app's wrench
+    screen); `links` makes ports follow others, e.g. {"a": "c"} drives C
+    whenever A is driven (the app's A+C button).
+    """
+
+    def __init__(self, device: BLEDevice | str | None = None, *, slot: int = 1,
+                 six_ports: bool = False, resend_interval: float | None = 0.2,
+                 timeout: float = 20.0, inverted: Iterable[str] = (),
+                 links: dict[str, str] | None = None):
+        self._device = device
+        self.slot = slot
+        self.six_ports = six_ports
+        self.resend_interval = resend_interval
+        self.timeout = timeout
+        self.inverted = set(inverted)
+        self.links = dict(links or {})
+        self.status: Status | None = None
+        self.on_status: Callable[[Status], None] | None = None
+        self._client: BleakClient | None = None
+        self._speeds = dict.fromkeys(protocol.PORTS, 0)
+        self._resender: asyncio.Task | None = None
+        self._lock = asyncio.Lock()
+        self._last_frame = b""
+
+    @property
+    def is_connected(self) -> bool:
+        return self._client is not None and self._client.is_connected
+
+    @property
+    def address(self) -> str | None:
+        """Address of the connected module."""
+        return self._client.address if self._client else None
+
+    def detach(self) -> list[str] | None:
+        """Forget the connection without waiting for it to close, and return a command that closes it.
+
+        For apps that want to exit at once: run the returned command in the background. Only
+        available on Linux (BlueZ); returns None elsewhere, then use `disconnect()` instead.
+        """
+        path = getattr(getattr(self._client, "_backend", None), "_device_path", None)
+        if not path or not shutil.which("busctl"):
+            return None
+        if self._resender:
+            self._resender.cancel()
+            self._resender = None
+        self._client = None
+        return ["busctl", "call", "org.bluez", path, "org.bluez.Device1", "Disconnect"]
+
+    @property
+    def battery(self) -> int | None:
+        return self.status.battery if self.status else None
+
+    async def connect(self) -> None:
+        device = self._device
+        if device is None or isinstance(device, str):
+            device = await find(device, timeout=self.timeout)
+            if device is None:
+                raise ConnectionError("no JG_JMC module found; is it switched on and not connected elsewhere?")
+        self._client = BleakClient(device, timeout=self.timeout)
+        await self._client.connect()
+        await self._client.start_notify(protocol.NOTIFY_UUID, self._handle_notify)
+        if self.resend_interval:
+            self._resender = asyncio.create_task(self._resend_loop())
+        log.info("connected to %s", device)
+
+    async def disconnect(self) -> None:
+        if self._resender:
+            self._resender.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._resender
+            self._resender = None
+        if self._client:
+            if self._client.is_connected:
+                with contextlib.suppress(Exception):
+                    await self.stop()
+                await self._client.disconnect()
+            self._client = None
+
+    async def __aenter__(self) -> JMCModule:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.disconnect()
+
+    async def drive(self, **speeds: int) -> None:
+        """Set port speeds, e.g. drive(a=255, d=-120). Ports not given keep their speed."""
+        for port, speed in speeds.items():
+            if port not in self._speeds:
+                raise ValueError(f"unknown port {port!r}; use one of {', '.join(protocol.PORTS)}")
+            self._speeds[port] = speed
+            if port in self.links:
+                self._speeds[self.links[port]] = speed
+        await self._send()
+
+    async def run(self, seconds: float, **speeds: int) -> None:
+        """Drive the given ports for `seconds`, then stop them."""
+        await self.drive(**speeds)
+        try:
+            await asyncio.sleep(seconds)
+        finally:
+            await self.drive(**dict.fromkeys(speeds, 0))
+
+    @property
+    def speeds(self) -> dict[str, int]:
+        """Current speed per port, as last set."""
+        return dict(self._speeds)
+
+    async def stop(self) -> None:
+        """Stop every port."""
+        self._speeds = dict.fromkeys(protocol.PORTS, 0)
+        await self._send()
+
+    async def _send(self) -> None:
+        if not self.is_connected:
+            raise ConnectionError("not connected")
+        speeds = {p: -s if p in self.inverted else s for p, s in self._speeds.items()}
+        frame = protocol.motor_frame(**speeds, module=self.slot, six_ports=self.six_ports)
+        if frame != self._last_frame:
+            log.debug("send %s", frame.hex(" "))
+            self._last_frame = frame
+        async with self._lock:
+            # The module ignores write-without-response.
+            await self._client.write_gatt_char(protocol.WRITE_UUID, frame, response=True)
+
+    async def _resend_loop(self) -> None:
+        while True:
+            await asyncio.sleep(self.resend_interval)
+            try:
+                await self._send()
+            except Exception as exc:  # keep resending; disconnects surface on the next user call
+                log.debug("resend failed: %s", exc)
+
+    def _handle_notify(self, _sender, data: bytearray) -> None:
+        status = protocol.parse_status(bytes(data))
+        if status:
+            self.status = status
+            if self.on_status:
+                self.on_status(status)

brickremote/protocol.py

@@ -0,0 +1,90 @@
+"""Wire format of JG_JMC-xxxx motor modules.
+
+Commands are written (with response) to characteristic FFF2:
+
+    5A 6B 02 00 LEN  dirAB speedAB  dirCD speedCD  module  [dirEF speedE speedF]  SUM
+
+    LEN      payload length: 5 for 4-port modules, 8 for 6-port modules
+    dirAB    A: 1 = forward, 2 = reverse; B: +4 = forward, +8 = reverse
+    dirCD    same for C and D
+    speed    0..255, shared by both ports of a pair
+    module   1..3, the module slot (the official app can drive three at once)
+    SUM      sum of all previous bytes, modulo 256
+
+The module reports on FFF1:
+
+    5A 6B 01 00 01  battery%  SUM
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+SERVICE_UUID = "0000fff0-0000-1000-8000-00805f9b34fb"
+WRITE_UUID = "0000fff2-0000-1000-8000-00805f9b34fb"
+NOTIFY_UUID = "0000fff1-0000-1000-8000-00805f9b34fb"
+NAME_PREFIX = "JG_JMC-"
+
+HEADER = 0x5A
+FRAME_TYPE = 0x6B
+CMD_MOTORS = 0x02
+CMD_STATUS = 0x01
+
+MAX_SPEED = 255
+GEARS = (60, 120, 255)  # the official app's gears 1, 2 and 3
+PORTS = ("a", "b", "c", "d", "e", "f")
+
+
+def checksum(data: bytes | list[int]) -> int:
+    return sum(data) & 0xFF
+
+
+def _clamp(speed: int) -> int:
+    return max(-MAX_SPEED, min(MAX_SPEED, int(speed)))
+
+
+def _pair(first: int, second: int) -> tuple[int, int]:
+    """Direction bits and shared speed for two ports."""
+    first, second = _clamp(first), _clamp(second)
+    dirs = (1 if first > 0 else 2 if first < 0 else 0) | (4 if second > 0 else 8 if second < 0 else 0)
+    return dirs, max(abs(first), abs(second))
+
+
+def motor_frame(a: int = 0, b: int = 0, c: int = 0, d: int = 0, e: int = 0, f: int = 0,
+                *, module: int = 1, six_ports: bool = False) -> bytes:
+    """Build a motor command. Speeds are -255..255, negative means reverse.
+
+    Both ports of a pair (A/B, C/D, E/F) share one speed byte, so when both
+    run, the faster of the two is used.
+    """
+    if not 1 <= module <= 3:
+        raise ValueError("module must be 1, 2 or 3")
+    if not six_ports and (e or f):
+        raise ValueError("ports E and F need six_ports=True")
+    body = [HEADER, FRAME_TYPE, CMD_MOTORS, 0x00, 8 if six_ports else 5]
+    body += _pair(a, b)
+    body += _pair(c, d)
+    body.append(module)
+    if six_ports:
+        dirs, _ = _pair(e, f)
+        body += [dirs, abs(_clamp(e)), abs(_clamp(f))]
+    body.append(checksum(body))
+    return bytes(body)
+
+
+def stop_frame(*, module: int = 1, six_ports: bool = False) -> bytes:
+    return motor_frame(module=module, six_ports=six_ports)
+
+
+@dataclass(frozen=True)
+class Status:
+    battery: int  # percent
+
+
+def parse_status(data: bytes) -> Status | None:
+    """Parse a FFF1 notification; returns None for anything unrecognised."""
+    if len(data) < 7 or data[0] != HEADER or data[1] != FRAME_TYPE or data[2] != CMD_STATUS:
+        return None
+    if checksum(data[:-1]) != data[-1]:
+        return None
+    return Status(battery=data[5])

brickremote/script.py

@@ -0,0 +1,159 @@
+"""Text versions of the official app's "Program" (blocks) and "Path" modes.
+
+Program scripts, one command per line (`#` starts a comment):
+
+    gear 2              set speed for `+` / `-` (1 = 60, 2 = 120, 3 = 255)
+    a + 2               port A forward for 2 s at the current gear
+    ac - 1.5            ports A and C reverse for 1.5 s
+    d 200 1             port D at speed 200 for 1 s (-255..255)
+    b +                 port B forward, keep running
+    wait 1              pause 1 s (motors keep their state)
+    stop                stop every port
+    repeat 3            repeat the block up to `end` three times
+    forever             repeat the block up to `end` until stopped
+    end
+
+Path scripts drive a car (drive port + steering port), distances in metres,
+turns in degrees; `Calibration` turns them into times:
+
+    forward 1.5
+    left 90
+    back 0.5
+    right 45
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+from .car import Car
+from .module import JMCModule
+from .protocol import GEARS, PORTS
+
+
+class ScriptError(ValueError):
+    pass
+
+
+@dataclass
+class Step:
+    op: str               # "drive", "wait", "stop", "gear", "repeat"
+    ports: str = ""
+    speed: str | int = 0  # "+", "-" or an int
+    seconds: float | None = None
+    count: int | None = None  # repeat count, None = forever
+    body: list[Step] | None = None
+
+
+def parse_program(text: str) -> list[Step]:
+    stack: list[list[Step]] = [[]]
+    for lineno, raw in enumerate(text.splitlines(), 1):
+        words = raw.split("#", 1)[0].split()
+        if not words:
+            continue
+        cmd, args = words[0].lower(), words[1:]
+        try:
+            if cmd == "end":
+                if len(stack) == 1:
+                    raise ScriptError("`end` without `repeat`/`forever`")
+                stack.pop()
+            elif cmd in ("repeat", "forever"):
+                step = Step("repeat", count=int(args[0]) if cmd == "repeat" else None, body=[])
+                stack[-1].append(step)
+                stack.append(step.body)
+            elif cmd == "wait":
+                stack[-1].append(Step("wait", seconds=float(args[0])))
+            elif cmd == "stop":
+                stack[-1].append(Step("stop"))
+            elif cmd == "gear":
+                gear = int(args[0])
+                if not 1 <= gear <= len(GEARS):
+                    raise ScriptError("gear must be 1, 2 or 3")
+                stack[-1].append(Step("gear", count=gear))
+            elif cmd and all(c in PORTS for c in cmd):
+                speed = args[0] if args[0] in "+-" else int(args[0])
+                seconds = float(args[1]) if len(args) > 1 else None
+                stack[-1].append(Step("drive", ports=cmd, speed=speed, seconds=seconds))
+            else:
+                raise ScriptError(f"unknown command {cmd!r}")
+        except (IndexError, ValueError) as exc:
+            raise ScriptError(f"line {lineno}: {raw.strip()!r}: {exc or 'missing argument'}") from None
+    if len(stack) != 1:
+        raise ScriptError("missing `end`")
+    return stack[0]
+
+
+async def run_program(module: JMCModule, steps: list[Step], gear: int = 3, log=print) -> None:
+    """Run a parsed program. Cancel the task to abort; motors are stopped either way."""
+    state = {"gear": gear}
+
+    async def run(block: list[Step]) -> None:
+        for step in block:
+            if step.op == "gear":
+                state["gear"] = step.count
+            elif step.op == "wait":
+                await asyncio.sleep(step.seconds)
+            elif step.op == "stop":
+                await module.stop()
+            elif step.op == "repeat":
+                n = 0
+                while step.count is None or n < step.count:
+                    await run(step.body)
+                    n += 1
+            elif step.op == "drive":
+                speed = step.speed
+                if speed in ("+", "-"):
+                    speed = GEARS[state["gear"] - 1] * (1 if speed == "+" else -1)
+                speeds = dict.fromkeys(step.ports, speed)
+                log(f"{step.ports.upper()} {speed:+d}" + (f" for {step.seconds}s" if step.seconds else ""))
+                if step.seconds is None:
+                    await module.drive(**speeds)
+                else:
+                    await module.run(step.seconds, **speeds)
+
+    try:
+        await run(steps)
+    finally:
+        await module.stop()
+
+
+@dataclass
+class Calibration:
+    metres_per_second: float = 0.5   # at full speed, straight
+    degrees_per_second: float = 90.0  # at full speed, full steering lock
+
+
+def parse_path(text: str) -> list[tuple[str, float]]:
+    moves = []
+    for lineno, raw in enumerate(text.splitlines(), 1):
+        words = raw.split("#", 1)[0].split()
+        if not words:
+            continue
+        cmd = {"fwd": "forward", "backward": "back", "bwd": "back"}.get(words[0].lower(), words[0].lower())
+        if cmd not in ("forward", "back", "left", "right") or len(words) != 2:
+            raise ScriptError(f"line {lineno}: expected `forward|back|left|right <amount>`, got {raw.strip()!r}")
+        try:
+            moves.append((cmd, float(words[1])))
+        except ValueError:
+            raise ScriptError(f"line {lineno}: {words[1]!r} is not a number") from None
+    return moves
+
+
+async def run_path(car: Car, moves: list[tuple[str, float]], cal: Calibration, log=print) -> None:
+    """Drive a path at full speed. Turns are made driving forward with full steering."""
+    try:
+        for cmd, amount in moves:
+            if cmd in ("forward", "back"):
+                seconds = amount / cal.metres_per_second
+                log(f"{cmd} {amount} m ({seconds:.1f}s)")
+                await car.drive(255 if cmd == "forward" else -255)
+            else:
+                seconds = amount / cal.degrees_per_second
+                log(f"{cmd} {amount}° ({seconds:.1f}s)")
+                await car.drive(255, 255 if cmd == "left" else -255)
+            await asyncio.sleep(seconds)
+            await car.stop()
+            await asyncio.sleep(0.3)  # let the steering re-centre
+    finally:
+        await car.stop()