brickremote 0.3.0__py3-none-any.whl

brickremote/web.py

@@ -0,0 +1,243 @@
+"""Web remote control: `brickremote web` serves a touch-friendly page to any browser on the network.
+
+The browser talks to the server over a WebSocket. While a control is held, the page repeats
+its state several times a second; if those messages stop (closed tab, lost Wi-Fi), the motors
+are stopped after a moment.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import socket
+import time
+from importlib import resources
+
+from aiohttp import WSMsgType, web
+
+from .car import Car
+from .module import JMCModule
+from .protocol import PORTS
+from .script import Calibration, ScriptError, parse_path, parse_program, run_path, run_program
+from .tui import EXAMPLE_PATH, EXAMPLE_PROGRAM, load_config, save_config
+
+log = logging.getLogger(__name__)
+
+DEADMAN = 0.7  # seconds without a drive message before moving motors are stopped
+
+
+class Remote:
+    """Shared state between all connected browsers."""
+
+    def __init__(self, module: JMCModule, car: Car):
+        self.module, self.car = module, car
+        cfg = load_config()
+        self.cfg = cfg
+        self.module.inverted = set(cfg.get("inverted", []))
+        self.settings = {
+            "gear": cfg.get("gear", 3),
+            "program": cfg.get("program", EXAMPLE_PROGRAM),
+            "path": cfg.get("path", EXAMPLE_PATH),
+            "calibration": cfg.get("calibration", vars(Calibration())),
+            "inverted": sorted(self.module.inverted),
+            "links": {},
+            "drive_port": car.drive_port,
+            "steer_port": car.steer_port,
+        }
+        self.clients: set[web.WebSocketResponse] = set()
+        self.task: asyncio.Task | None = None
+        self.log: list[str] = []
+        self.last_drive = 0.0
+
+    @property
+    def running(self) -> bool:
+        return self.task is not None and not self.task.done()
+
+    def say(self, msg: str) -> None:
+        log.debug("say %s", msg)
+        self.log = (self.log + [msg])[-5:]
+
+    def persist(self) -> None:
+        self.cfg.update(gear=self.settings["gear"], inverted=self.settings["inverted"],
+                        calibration=self.settings["calibration"], program=self.settings["program"],
+                        path=self.settings["path"])
+        save_config(self.cfg)
+
+    def state(self) -> dict:
+        return {"type": "state", "connected": self.module.is_connected, "battery": self.module.battery,
+                "speeds": self.module.speeds, "running": self.running, "log": self.log,
+                "settings": self.settings}
+
+    async def broadcast(self) -> None:
+        msg = json.dumps(self.state())
+        for ws in list(self.clients):
+            with contextlib.suppress(Exception):
+                await ws.send_str(msg)
+
+    def start(self, coro) -> None:
+        self.cancel()
+        self.task = asyncio.create_task(coro)
+        self.task.add_done_callback(self._finished)
+
+    def _finished(self, task: asyncio.Task) -> None:
+        if task.cancelled():
+            self.say("Stopped.")
+        elif task.exception():
+            self.say(f"Oops: {task.exception()}")
+        else:
+            self.say("All done!")
+
+    def cancel(self) -> None:
+        if self.running:
+            self.task.cancel()
+
+    async def handle(self, msg: dict) -> None:
+        kind = msg.get("type")
+        if kind == "drive":
+            if self.running or not self.module.is_connected:
+                return
+            speeds = {p: max(-255, min(255, int(v))) for p, v in msg.get("speeds", {}).items() if p in PORTS}
+            self.last_drive = time.monotonic()
+            if any(self.module.speeds[p] != v for p, v in speeds.items()):
+                await self.module.drive(**speeds)
+        elif kind == "stop":
+            self.cancel()
+            if self.module.is_connected:
+                await self.module.stop()
+            self.say("STOP!")
+        elif kind == "settings":
+            new = msg.get("settings", {})
+            for key in ("gear", "program", "path", "calibration"):
+                if key in new:
+                    self.settings[key] = new[key]
+            if "inverted" in new:
+                self.settings["inverted"] = sorted(p for p in new["inverted"] if p in PORTS)
+                self.module.inverted = set(self.settings["inverted"])
+            if "links" in new:
+                self.settings["links"] = {a: b for a, b in new["links"].items() if a in PORTS and b in PORTS}
+                self.module.links = dict(self.settings["links"])
+            self.persist()
+        elif kind == "run_program":
+            try:
+                steps = parse_program(self.settings["program"])
+            except ScriptError as exc:
+                self.say(f"Oops: {exc}")
+            else:
+                self.say("Running your program!")
+                self.start(run_program(self.module, steps, int(self.settings["gear"]), log=self.say))
+        elif kind == "run_path":
+            try:
+                moves = parse_path(self.settings["path"])
+            except ScriptError as exc:
+                self.say(f"Oops: {exc}")
+            else:
+                self.say("Off we go!")
+                cal = Calibration(**self.settings["calibration"])
+                self.start(run_path(self.car, moves, cal, log=self.say))
+
+    async def deadman(self) -> None:
+        """Stop motors when browsers stop sending while something is moving."""
+        while True:
+            await asyncio.sleep(0.1)
+            moving = any(self.module.speeds.values())
+            if moving and not self.running and time.monotonic() - self.last_drive > DEADMAN:
+                with contextlib.suppress(Exception):
+                    await self.module.stop()
+
+    async def keep_connected(self) -> None:
+        while True:
+            if not self.module.is_connected:
+                self.cancel()
+                try:
+                    await self.module.disconnect()
+                    await self.module.connect()
+                    self.say("Connected! Let's go!")
+                except Exception as exc:
+                    log.debug("connect failed: %s", exc)
+                    await asyncio.sleep(1)
+                    continue
+            await asyncio.sleep(0.5)
+
+    async def ticker(self) -> None:
+        while True:
+            await self.broadcast()
+            await asyncio.sleep(0.2)
+
+
+async def index(request: web.Request) -> web.Response:
+    html = resources.files("brickremote").joinpath("web/index.html").read_text(encoding="utf-8")
+    return web.Response(text=html, content_type="text/html")
+
+
+async def websocket(request: web.Request) -> web.WebSocketResponse:
+    remote: Remote = request.app["remote"]
+    ws = web.WebSocketResponse(heartbeat=5)
+    await ws.prepare(request)
+    remote.clients.add(ws)
+    await ws.send_str(json.dumps(remote.state()))
+    try:
+        async for msg in ws:
+            if msg.type == WSMsgType.TEXT:
+                try:
+                    await remote.handle(json.loads(msg.data))
+                except Exception as exc:
+                    remote.say(f"Oops: {exc}")
+                await remote.broadcast()
+    finally:
+        remote.clients.discard(ws)
+    return ws
+
+
+def local_addresses() -> list[str]:
+    addresses = set()
+    with contextlib.suppress(OSError):
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.connect(("192.0.2.1", 1))  # no packet is sent; this just picks the outgoing interface
+        addresses.add(s.getsockname()[0])
+        s.close()
+    with contextlib.suppress(OSError):
+        addresses.add(socket.gethostname() + ".local")
+    return sorted(addresses)
+
+
+async def serve(module: JMCModule, car: Car, host: str, port: int) -> None:
+    remote = Remote(module, car)
+    app = web.Application()
+    app["remote"] = remote
+    app.router.add_get("/", index)
+    app.router.add_get("/ws", websocket)
+    runner = web.AppRunner(app, access_log=None)
+    await runner.setup()
+    await web.TCPSite(runner, host, port).start()
+    print("Brick Remote is running! Open one of these in a browser:", flush=True)
+    print(f"  http://localhost:{port}")
+    if host in ("0.0.0.0", "::", ""):
+        for addr in local_addresses():
+            print(f"  http://{addr}:{port}  (from a tablet or another computer)")
+    print("Press Ctrl-C to stop.", flush=True)
+    tasks = [asyncio.create_task(t) for t in (remote.keep_connected(), remote.deadman(), remote.ticker())]
+    try:
+        await asyncio.Event().wait()
+    finally:
+        for t in tasks:
+            t.cancel()
+        remote.cancel()
+        if module.is_connected:
+            with contextlib.suppress(Exception):
+                await asyncio.wait_for(module.stop(), 0.5)
+            command = module.detach()
+            if command:
+                import subprocess
+                subprocess.Popen(command, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+                                 stderr=subprocess.DEVNULL, start_new_session=True)
+        await runner.cleanup()
+
+
+def run(address: str | None = None, drive_port: str = "a", steer_port: str = "d",
+        host: str = "0.0.0.0", port: int = 8080) -> None:
+    module = JMCModule(address, timeout=5.0)
+    car = Car(module, drive_port=drive_port, steer_port=steer_port)
+    with contextlib.suppress(KeyboardInterrupt):
+        asyncio.run(serve(module, car, host, port))

brickremote-0.3.0.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.5
+Name: brickremote
+Version: 0.3.0
+Summary: Drive Lego-compatible Bluetooth motor bricks (JG_JMC / XP Block "Smart creative module") from a computer
+Project-URL: Homepage, https://surak.github.io/brickremote/
+Project-URL: Source, https://github.com/surak/brickremote
+Project-URL: Changelog, https://github.com/surak/brickremote/blob/main/CHANGELOG.md
+Author-email: Alexandre Strube <surak@surak.eti.br>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ble,bluetooth,building blocks,jg_jmc,kids,motor,remote control,smart creative module,xp block
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Classifier: Topic :: Home Automation
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Requires-Dist: bleak>=0.22
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Provides-Extra: web
+Requires-Dist: aiohttp>=3.9; extra == 'web'
+Description-Content-Type: text/markdown
+
+# brickremote
+
+**Website for kids and parents: https://surak.github.io/brickremote/**
+
+Python library for the cheap Lego-compatible Bluetooth LE motor bricks that advertise as
+`JG_JMC-xxxx` and are normally driven by the **XP Block** phone app ("Smart creative module",
+four motor ports A–D). Works anywhere [bleak](https://github.com/hbldh/bleak) does: Linux
+(incl. Raspberry Pi), macOS and Windows.
+
+```
+pip install brickremote          # library and terminal app
+pip install "brickremote[web]"     # plus the web remote control
+```
+
+Or from a checkout, without installing anything yourself:
+
+```
+./run.sh          # creates .venv on first run, then starts the remote control app
+./run.sh scan     # any other command works the same way
+```
+
+## Remote control app
+
+Run `brickremote` with no arguments for a terminal version of the phone app (everything except the
+phone-only gyroscope and voice modes):
+
+| Tab | Keys |
+|-----|------|
+| Car | arrows: forward/back, steer left/right (drive port A, steering port D; change with `--drive`/`--steer`) |
+| Ports | like two game sticks: `W`/`S` port A, `A`/`D` port B, `I`/`K` port C, `J`/`L` port D |
+| Program | `e` edit in `$EDITOR`, Enter run (see below) |
+| Path | `e` edit, Enter run, `[` `]` / `{` `}` calibrate speed and turn rate |
+
+Everywhere: `Tab` switch screen, `1`-`3` speed (60/120/255), `space` STOP, `q` quit, and
+
+- `h` **hold**: motors keep running after you let go of the key (steering still springs back)
+- `p` **pair**: one port copies another (off → A+B → A+C), for builds with two motors that
+  should always move together, like a tank
+- `r` + port letter **reverse**: that port turns the other way round, for a motor that was
+  mounted backwards
+
+Settings, programs and paths are saved in `~/.config/brickremote.json`.
+
+Terminals report key presses but not releases, so a motor runs while its key auto-repeats and
+stops a moment after you let go. Steering always springs back to centre, even with hold on.
+
+## Web remote control
+
+```
+./run.sh web          # or: brickremote web   (needs `pip install 'brickremote[web]'`)
+```
+
+This starts a small web server and prints its address. Open it in any browser: on the same
+computer, or on a tablet or laptop on the same Wi-Fi, which then becomes the remote control.
+It has the same four screens as the terminal app, plus things a browser is good at:
+
+- buttons you hold down, a steering wheel you can drag, and two joysticks for the ports
+- program blocks you tap to build a program
+- a grid where you draw the route for path mode
+
+If the browser stops talking to the server (tab closed, Wi-Fi gone), the motors stop by themselves.
+
+## Command line
+
+```
+brickremote scan                         # list modules nearby
+brickremote run a=255 --time 2           # port A forward, full speed, 2 s
+brickremote run a=-120 d=255 --time 1.5  # A reverse at medium speed, D forward
+brickremote program dance.txt            # run a program script
+brickremote path route.txt --mps 0.6     # drive a path script
+brickremote --invert d run d=255         # global options: --address, --slot, --invert, --drive, --steer
+```
+
+### Program scripts (the app's block programming)
+
+```
+gear 2              # speed for + and -: 1 = 60, 2 = 120, 3 = 255
+repeat 3
+  a + 1.5           # port A forward for 1.5 s
+  ac - 1            # ports A and C reverse for 1 s
+  wait 0.5
+end
+d 200               # port D at speed 200, keep running
+forever             # until Ctrl-C / space
+  b + 1
+  b - 1
+end
+```
+
+### Path scripts (the app's path mode)
+
+```
+forward 1.5   # metres
+left 90       # degrees, driving forward with full steering
+back 0.5
+right 45
+```
+
+Distances and angles become times through a calibration (`--mps`, `--dps`, or `[ ] { }` in the
+app): measure how far the car goes in one second at full speed, and how many degrees it turns.
+
+## Library
+
+```python
+import asyncio
+from brickremote import JMCModule
+
+async def main():
+    async with JMCModule() as m:          # connects to the first module found
+        await m.drive(a=255, d=-120)      # speeds -255..255, negative = reverse
+        await asyncio.sleep(2)
+        await m.stop()
+        print("battery:", m.battery, "%")
+
+asyncio.run(main())
+```
+
+`JMCModule(address)` targets a specific module, `discover()` lists all of them. While connected,
+the current state is resent every 0.2 s, which keeps the module from going to sleep.
+
+```python
+JMCModule(inverted="d", links={"a": "c"})   # reverse port D; C follows A
+await m.run(2, a=255)                       # A forward for 2 s, then stop
+```
+
+`brickremote.script` has the program and path engines (`parse_program`, `run_program`,
+`parse_path`, `run_path`) if you want them from your own code.
+
+For the stock car (drive motor on A, steering on D) there is a small wrapper:
+
+```python
+from brickremote import Car, JMCModule
+
+async with JMCModule() as m:
+    car = Car(m)
+    await car.left(speed=200)   # forward while steering left
+```
+
+## Protocol
+
+Reverse-engineered from the XP Block Android app. The module exposes service `FFF0`;
+commands go to `FFF2` and **must be written with response** (write-without-response is
+silently ignored):
+
+```
+5A 6B 02 00 05  dirAB speedAB  dirCD speedCD  slot  SUM
+```
+
+| Field   | Meaning |
+|---------|---------|
+| dirAB   | A: `1` forward, `2` reverse; B: `+4` forward, `+8` reverse |
+| speedAB | 0–255, shared by A and B (the app's gears are 60 / 120 / 255) |
+| dirCD, speedCD | same for C and D |
+| slot    | 1–3, module slot (the app can drive three modules at once) |
+| SUM     | sum of all previous bytes, modulo 256 |
+
+Six-port modules use length `08` and append `dirEF speedE speedF`.
+
+The module reports on `FFF1` with `5A 6B 01 00 01 <battery %> SUM`. It switches itself off
+after about ten minutes without commands.
+
+## Limitations
+
+- The two ports of a pair share one speed byte, so A and B (or C and D) cannot run at different
+  speeds at the same time; the faster one wins.
+- Only tested with a four-port module. Six-port support follows the app's code but is unverified.
+
+## License
+
+MIT

brickremote-0.3.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+brickremote/__init__.py,sha256=fDh9aKEKqP1sThGbBEIrrqHEiidBPtVg9kZjJY1QBHQ,369
+brickremote/car.py,sha256=G1aE8KDvopRTuO_a1snA542Isx58ZQ5OFq2mP5Eox6g,1498
+brickremote/cli.py,sha256=MZulXrOcDo8bf7lDb6ILPaQwunUu6kQJwd53cAq2Ajo,5702
+brickremote/module.py,sha256=5KrV0WBXCv_6geeocrkopbzL5jGgbirEjGPuSyytgq0,8109
+brickremote/protocol.py,sha256=Z3CiSGF-vOBuCV_nSC53sx8ctN94nT6Y1schrqvlB5w,2915
+brickremote/script.py,sha256=ewuZoZRhLwPI1uv66tuRS-tf99V5v9YG_h8TqHyy8Cw,6123
+brickremote/tui.py,sha256=VoGllR2PYjsfyiz4BeaRkAr437XGuR6bs-bD-31hjbE,29707
+brickremote/web.py,sha256=0GojwZsMGRMsUo6MyPWc7-ZdGvDbCh-dcaCdqFsg9Qk,9347
+brickremote/web/index.html,sha256=bjzb5fv7nIi0GI5KDAjxhy3Nx9p484rJcuD7stepwFg,33416
+brickremote-0.3.0.dist-info/METADATA,sha256=_ZPZyuHpRO_lEz8iWfUU0inVwbN4Jj1sqteSfb46uLw,7123
+brickremote-0.3.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+brickremote-0.3.0.dist-info/entry_points.txt,sha256=P2ufB2nHe5T-jvZ70AHV0JdNwelzgnNjRD8IqOpD0a4,53
+brickremote-0.3.0.dist-info/licenses/LICENSE,sha256=b-oeTQceLUsSNGJQezIG2xGZHZUY_CysQ09bjWPsGyQ,1073
+brickremote-0.3.0.dist-info/RECORD,,

brickremote-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

brickremote-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+brickremote = brickremote.cli:main

brickremote-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandre Strube
+
+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.