lumalou 0.1.0__tar.gz

lumalou-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: lumalou
+Version: 0.1.0
+Summary: Local BLE control for the Fisher-Price Lumalou — reverse-engineered MPID protocol, pure Python
+Author: Emanuele Strazzullo
+License: MIT
+Project-URL: Homepage, https://github.com/stramanu/lumalou
+Project-URL: Issues, https://github.com/stramanu/lumalou/issues
+Keywords: fisher-price,lumalou,ble,bluetooth,bleak,reverse-engineering,gld09
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Home Automation
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: bleak>=0.22
+Requires-Dist: cryptography>=41
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+# lumalou (Python)
+
+Local BLE control for the Fisher-Price Lumalou. Pure Python (async, [bleak](https://github.com/hbldh/bleak)).
+
+```bash
+pip install lumalou
+```
+
+## Library
+
+```python
+import asyncio
+from lumalou import LumalouClient, Color
+
+async def main():
+    devices = await LumalouClient.scan()
+    async with LumalouClient(devices[0]["address"]) as luma:
+        await luma.light_color(Color.RAINBOW)
+        await luma.play(0)            # guided sleep playlist
+        await luma.volume(5)
+        print(await luma.request_state())
+
+asyncio.run(main())
+```
+
+## CLI
+
+```bash
+lumalou scan
+lumalou light --color blue --brightness 7
+lumalou sound --source ocean --volume 5
+lumalou soother                 # --off to stop
+lumalou time                    # sync clock
+lumalou state                   # read full state
+lumalou send 3c05               # raw app_data (opcode + args)
+```
+
+Add `-a <address>` to target a device; otherwise it auto-scans.
+
+Requires Python 3.10+, a Bluetooth LE adapter, and radio range of the device.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest        # runs the shared golden vectors (spec/vectors.json)
+```
+
+MIT.

lumalou-0.1.0/README.md

@@ -0,0 +1,49 @@
+# lumalou (Python)
+
+Local BLE control for the Fisher-Price Lumalou. Pure Python (async, [bleak](https://github.com/hbldh/bleak)).
+
+```bash
+pip install lumalou
+```
+
+## Library
+
+```python
+import asyncio
+from lumalou import LumalouClient, Color
+
+async def main():
+    devices = await LumalouClient.scan()
+    async with LumalouClient(devices[0]["address"]) as luma:
+        await luma.light_color(Color.RAINBOW)
+        await luma.play(0)            # guided sleep playlist
+        await luma.volume(5)
+        print(await luma.request_state())
+
+asyncio.run(main())
+```
+
+## CLI
+
+```bash
+lumalou scan
+lumalou light --color blue --brightness 7
+lumalou sound --source ocean --volume 5
+lumalou soother                 # --off to stop
+lumalou time                    # sync clock
+lumalou state                   # read full state
+lumalou send 3c05               # raw app_data (opcode + args)
+```
+
+Add `-a <address>` to target a device; otherwise it auto-scans.
+
+Requires Python 3.10+, a Bluetooth LE adapter, and radio range of the device.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest        # runs the shared golden vectors (spec/vectors.json)
+```
+
+MIT.

lumalou-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lumalou"
+version = "0.1.0"
+description = "Local BLE control for the Fisher-Price Lumalou — reverse-engineered MPID protocol, pure Python"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Emanuele Strazzullo" }]
+keywords = ["fisher-price", "lumalou", "ble", "bluetooth", "bleak", "reverse-engineering", "gld09"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Home Automation",
+  "Framework :: AsyncIO",
+]
+dependencies = ["bleak>=0.22", "cryptography>=41"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://github.com/stramanu/lumalou"
+Issues = "https://github.com/stramanu/lumalou/issues"
+
+[project.scripts]
+lumalou = "lumalou.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["lumalou*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

lumalou-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lumalou-0.1.0/src/lumalou/__init__.py

@@ -0,0 +1,30 @@
+"""
+lumalou — local BLE control for the Fisher-Price Lumalou (gld09).
+
+Reverse-engineered MPID protocol: ECDH P-256 handshake + AES-128-CTR, pure Python.
+
+    import asyncio
+    from lumalou import LumalouClient, Color
+
+    async def main():
+        devices = await LumalouClient.scan()
+        async with LumalouClient(devices[0]["address"]) as luma:
+            await luma.light_color(Color.RAINBOW)
+            print(await luma.request_state())
+
+    asyncio.run(main())
+"""
+from .client import LumalouClient
+from ._generated import (Color, Audio, Song, LightDuration, PlaylistDuration,
+                         NapDuration, Alarm, RoutineControl, ClockFormat,
+                         OperationMode, Stage)
+from .protocol import build_tx_frame, decrypt_rx_frame, encode_command, crc8
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "LumalouClient",
+    "Color", "Audio", "Song", "LightDuration", "PlaylistDuration", "NapDuration",
+    "Alarm", "RoutineControl", "ClockFormat", "OperationMode", "Stage",
+    "build_tx_frame", "decrypt_rx_frame", "encode_command", "crc8",
+]

lumalou-0.1.0/src/lumalou/_generated.py

@@ -0,0 +1,208 @@
+"""AUTO-GENERATED from spec/protocol.json by tools/codegen.py. Do not edit."""
+from enum import IntEnum
+
+GATT = {
+    "service": "4cea0001-c678-4202-b5d3-712dbb5e5b14",
+    "characteristics": {
+        "tx": "4cea0002-c678-4202-b5d3-712dbb5e5b14",
+        "rx": "4cea0003-c678-4202-b5d3-712dbb5e5b14",
+        "factory": "4cea0004-c678-4202-b5d3-712dbb5e5b14",
+        "session": "4cea0005-c678-4202-b5d3-712dbb5e5b14"
+    },
+    "blacklist": {
+        "dfuService": "00001530-1212-efde-1523-785feabcd123",
+        "note": "Nordic DFU / firmware update service. Never write to it."
+    }
+}
+
+COMMANDS = {
+    "SET_GLOBAL_STATE": 1,
+    "SET_GLOBAL_ON": 3,
+    "SET_CURRENT_DATE": 48,
+    "REQUEST_CURRENT_DATE": 49,
+    "SEND_PAIRING_COMPLETE": 52,
+    "REQUEST_TOYIC_FW_VERSION": 53,
+    "SET_VOLUME": 55,
+    "TURN_OFF_AUDIO": 56,
+    "REQUEST_VOLUME": 57,
+    "SET_LED_BRIGHTNESS": 58,
+    "REQUEST_LED_BRIGHTNESS": 59,
+    "SET_LIGHT_COLOR": 60,
+    "REQUEST_LIGHT_COLOR": 61,
+    "TURN_OFF_CLOUD_BACKLIGHT": 62,
+    "PLAY_AUDIO": 63,
+    "SET_MUSIC_PLAYLIST": 64,
+    "REQUEST_MUSIC_PLAYLIST": 65,
+    "SET_PLAYLIST_DURATION": 66,
+    "REQUEST_PLAYLIST_DURATION": 67,
+    "SET_R2R_STATUS": 68,
+    "REQUEST_R2R_STATUS": 69,
+    "SET_R2R_TIMES": 70,
+    "REQUEST_R2R_TIMES": 71,
+    "SET_SLEEPY_TIMES": 72,
+    "REQUEST_SLEEPY_TIMES": 73,
+    "SET_R2R_ALARMS": 74,
+    "REQUEST_R2R_ALARM_STATUS": 75,
+    "REQUEST_R2R_ALARMS": 76,
+    "START_NAP_TIME": 77,
+    "REQUEST_CURRENT_NAP_TIME_STATUS": 78,
+    "SET_NAP_TIME_ALARM": 79,
+    "REQUEST_NAP_TIME_ALARM_STATUS": 80,
+    "REQUEST_NAP_TIME_ALARM": 81,
+    "SET_TIME_PRESCALER": 82,
+    "REQUEST_GLOBAL_STATE": 83,
+    "REQUEST_SONG_PLAYING": 85,
+    "SET_ROUTINE_MODE_STATUS": 88,
+    "REQUEST_ROUTINE_MODE_STATUS": 89,
+    "SET_ROUTINE_TASK_STATUS": 104,
+    "SET_ROUTINE_MUSIC_STATUS": 105,
+    "REQUEST_ROUTINE_MUSIC_STATUS": 106,
+    "ROUTINE_CONTROL_COMMAND": 107,
+    "SET_SOOTHER_MODE_LIGHT_DURATION": 108,
+    "REQUEST_SOOTHER_MODE_LIGHT_DURATION": 109,
+    "REQUEST_OPERATION_MODE": 114,
+    "REQUEST_TIME_PRESCALER": 115,
+    "REQUEST_ACTIVITY_STATE": 116,
+    "REQUEST_CURRENT_STAGE": 117,
+    "REQUEST_TRANSMISSION_MODE": 118,
+    "SET_ROUTINE_MODE_VOLUME": 119,
+    "REQUEST_ROUTINE_MODE_VOLUME": 120,
+    "SET_CLOCK_SETTINGS": 121,
+    "REQUEST_CLOCK_SETTINGS": 122,
+    "START_ROUTINE_MODE": 123
+}
+DAY_ROUTINE = {
+    "SET": {
+        "sunday": 90,
+        "monday": 92,
+        "tuesday": 94,
+        "wednesday": 96,
+        "thursday": 98,
+        "friday": 100,
+        "saturday": 102
+    },
+    "REQUEST": {
+        "sunday": 91,
+        "monday": 93,
+        "tuesday": 95,
+        "wednesday": 97,
+        "thursday": 99,
+        "friday": 101,
+        "saturday": 103
+    }
+}
+RESPONSES = {2: "GLOBAL_STATE", 17: "OTA_COMPLETE", 18: "TOYIC_FW_VERSION", 19: "CURRENT_DATE", 20: "CURRENT_SONG", 21: "CURRENT_VOLUME", 22: "LIGHT_STATUS", 23: "LIGHT_BRIGHTNESS", 24: "LIGHT_COLOR", 25: "CURRENT_PLAYLIST", 26: "AUDIO_TIMER_DURATION", 27: "TIMER_ABOUT_TO_EXPIRE", 28: "NAP_TIME_STATUS", 29: "TRANSMISSION_MODE", 30: "OPERATION_MODE", 31: "ACTIVITY_STATE", 32: "CURRENT_STAGE", 33: "READY_TO_RISE_STATUS", 34: "READY_TO_RISE_TIMES", 35: "SLEEPY_TIME_TIMES", 36: "NAP_TIME_ALARM_STATUS", 37: "NAP_TIME_ALARM_TIME", 38: "READY_TO_RISE_ALARM_STATUS", 39: "READY_TO_RISE_ALARM_TIMES", 40: "TIME_PRESCALER", 43: "SUNDAY_ROUTINE", 44: "MONDAY_ROUTINE", 45: "TUESDAY_ROUTINE", 46: "WEDNESDAY_ROUTINE", 47: "THURSDAY_ROUTINE", 144: "FRIDAY_ROUTINE", 145: "SATURDAY_ROUTINE", 146: "ROUTINE_MODE_STATUS", 147: "ROUTINE_MUSIC_STATUS", 148: "ROUTINE_TASK_STATUS", 149: "LIGHT_DURATION", 152: "ROUTINE_VOLUME_LEVEL", 153: "CLOCK_SETTINGS"}
+
+class Color(IntEnum):
+    WARM = 0
+    RED = 1
+    YELLOW = 2
+    ORANGE = 3
+    GREEN = 4
+    BLUE = 5
+    PURPLE = 6
+    NIGHT_LIGHT = 7
+    COOL = 8
+    RAINBOW = 9
+
+class Audio(IntEnum):
+    SLEEP_PLAYLIST = 0
+    CUSTOM_PLAYLIST = 1
+    PINK_NOISE = 2
+    OCEAN = 3
+    RAIN = 4
+    BROWN_NOISE = 5
+    NATURE = 6
+    HIGHWAY = 7
+
+class Song(IntEnum):
+    NO_SONG = 0
+    SLEEP_BABY_SLEEP = 1
+    HOUR_GLASS = 2
+    FRERE_JACQUES = 3
+    HOW_LOVELY_THE_EVENING = 4
+    TARREGA_LAGRIMA = 5
+    WHATS_THE_MATTER_DEAR = 6
+    SUO_GAN = 7
+    WATER_COLOR_DREAMS = 8
+    DANCE_OF_THE_JELLYFISH = 9
+    INSIDE_THE_BUBBLE = 10
+    PAPER_KITES = 11
+    CRICKETS_IN_SPACE = 12
+    PINK_NOISE = 13
+    OCEAN = 14
+    RAIN = 15
+    BROWN_NOISE = 16
+    NATURE = 17
+    HIGHWAY = 18
+
+class LightDuration(IntEnum):
+    MIN_15 = 0
+    MIN_30 = 1
+    MIN_60 = 2
+    MIN_90 = 3
+    CONTINUOUS = 4
+    MIN_1 = 5
+
+class PlaylistDuration(IntEnum):
+    MIN_15 = 0
+    MIN_30 = 1
+    MIN_60 = 2
+    MIN_90 = 3
+    MIN_120 = 4
+    CONTINUOUS = 5
+    MIN_1 = 6
+
+class NapDuration(IntEnum):
+    INACTIVE = 0
+    MIN_15 = 1
+    MIN_30 = 2
+    MIN_45 = 3
+    MIN_60 = 4
+    MIN_75 = 5
+    MIN_90 = 6
+    MIN_105 = 7
+    MIN_120 = 8
+    MIN_150 = 9
+    MIN_180 = 10
+    MIN_1 = 11
+
+class Alarm(IntEnum):
+    ACTIVE = 0
+    AFTER_15 = 1
+    AFTER_30 = 2
+    AFTER_45 = 3
+    AFTER_60 = 4
+    AFTER_75 = 5
+    AFTER_90 = 6
+    AFTER_105 = 7
+    AFTER_120 = 8
+    INACTIVE = 9
+    AFTER_1 = 10
+
+class RoutineControl(IntEnum):
+    COMPLETE_TASK = 0
+    PREV_TASK = 1
+    RESTART_SEQUENCE = 2
+    COMPLETE_SEQUENCE = 3
+    CANCEL = 4
+
+class OperationMode(IntEnum):
+    SOOTHER = 0
+    DAYTIME_AWAKE = 2
+    SLEEPY_TIME = 3
+    PAIRING = 4
+    FIRMWARE_UPDATE = 5
+    NAPTIME = 6
+    ROUTINE = 7
+
+class Stage(IntEnum):
+    NONE = 0
+    READY = 1
+    SETTLE = 2
+    SLEEP = 3
+
+class ClockFormat(IntEnum):
+    H12 = 0
+    H24 = 1
+

lumalou-0.1.0/src/lumalou/cli.py

@@ -0,0 +1,111 @@
+"""Command-line interface.  `lumalou --help`"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+
+from . import commands as C
+from ._generated import Color, Audio
+from .client import LumalouClient
+
+_COLORS = {c.name.lower(): int(c) for c in Color}
+_AUDIO = {"playlist": 0, "custom": 1, "pink": 2, "ocean": 3, "rain": 4,
+          "brown": 5, "nature": 6, "highway": 7}
+
+
+def _color_id(v):
+    return _COLORS[v.lower()] if v.lower() in _COLORS else int(v)
+
+
+def _audio_id(v):
+    return _AUDIO[v.lower()] if v.lower() in _AUDIO else int(v)
+
+
+async def _resolve_address(addr):
+    if addr:
+        return addr
+    devices = await LumalouClient.scan(timeout=8.0)
+    if not devices:
+        raise SystemExit("No device found. Turn the Lumalou on and try again.")
+    print(f"[auto] using {devices[0]['name']} ({devices[0]['address']}, {devices[0]['rssi']} dBm)")
+    return devices[0]["address"]
+
+
+async def _run(args):
+    if args.cmd == "scan":
+        for d in await LumalouClient.scan(timeout=args.timeout):
+            print(f"  {d['rssi']:>4} dBm  {d['name'] or '(no name)':<20} {d['address']}  mfg={d['manufacturer']}")
+        return
+
+    address = await _resolve_address(args.address)
+    async with LumalouClient(address) as luma:
+        if args.cmd == "state":
+            print(json.dumps(await luma.request_state(), indent=2))
+        elif args.cmd == "light":
+            if args.color is not None:
+                await luma.light_color(_color_id(args.color))
+            if args.brightness is not None:
+                await luma.brightness(args.brightness)
+            if args.off:
+                await luma.light_off()
+        elif args.cmd == "sound":
+            if args.source is not None:
+                await luma.play(_audio_id(args.source))
+            if args.volume is not None:
+                await luma.volume(args.volume)
+            if args.off:
+                await luma.audio_off()
+        elif args.cmd == "soother":
+            await luma.soother(not args.off)
+        elif args.cmd == "nap":
+            await luma.nap(args.minutes)
+        elif args.cmd == "time":
+            await luma.sync_time()
+            print("clock synced")
+        elif args.cmd == "send":
+            await luma.send(bytes.fromhex(args.hex))
+
+
+def build_parser():
+    p = argparse.ArgumentParser(prog="lumalou", description="BLE control for the Fisher-Price Lumalou.")
+    p.add_argument("-a", "--address", help="device address/UUID (default: auto-scan)")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("scan", help="find Lumalou devices")
+    s.add_argument("--timeout", type=float, default=8.0)
+
+    sub.add_parser("state", help="read the full state")
+
+    li = sub.add_parser("light", help="control the light")
+    li.add_argument("-c", "--color", help="warm|red|yellow|orange|green|blue|purple|night_light|cool|rainbow or 0-9")
+    li.add_argument("-b", "--brightness", type=int, help="0-9")
+    li.add_argument("--off", action="store_true", help="turn the light off")
+
+    au = sub.add_parser("sound", help="control audio")
+    au.add_argument("-s", "--source", help="playlist|custom|pink|ocean|rain|brown|nature|highway or 0-7")
+    au.add_argument("-v", "--volume", type=int, help="0-9")
+    au.add_argument("--off", action="store_true", help="stop audio")
+
+    so = sub.add_parser("soother", help="start/stop the soother")
+    so.add_argument("--off", action="store_true")
+
+    n = sub.add_parser("nap", help="start a nap")
+    n.add_argument("minutes", type=int, help="duration id (1=15, 2=30, ... 10=180)")
+
+    sub.add_parser("time", help="sync the device clock")
+
+    se = sub.add_parser("send", help="send raw app_data in hex")
+    se.add_argument("hex", help="e.g. 3c05 = blue light")
+    return p
+
+
+def main(argv=None):
+    try:
+        asyncio.run(_run(build_parser().parse_args(argv)))
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

lumalou-0.1.0/src/lumalou/client.py

@@ -0,0 +1,157 @@
+"""Async BLE client (bleak): scan, handshake, send commands, read state."""
+from __future__ import annotations
+
+import asyncio
+import datetime
+from typing import Callable, Optional
+
+from bleak import BleakClient, BleakScanner
+
+from . import commands as C
+from . import crypto
+from . import protocol as P
+from . import responses as R
+from ._generated import GATT
+
+SERVICE = GATT["service"]
+TX = GATT["characteristics"]["tx"]
+RX = GATT["characteristics"]["rx"]
+FACTORY = GATT["characteristics"]["factory"]
+SESSION = GATT["characteristics"]["session"]
+
+WRITE_SPACING = 0.15  # seconds between writes (the device is sensitive to bursts)
+
+
+class LumalouClient:
+    """Async client. Use as an async context manager or via connect()/disconnect()."""
+
+    def __init__(self, address: str, *, on_state: Optional[Callable[[dict], None]] = None):
+        self.address = address
+        self.connected = False
+        self._on_state = on_state
+        self._client: Optional[BleakClient] = None
+        self._key = self._nonce = self._salt = None
+        self._seq = 1
+        self._lock = asyncio.Lock()
+        self._state: Optional[dict] = None
+        self._state_waiters: list[asyncio.Future] = []
+
+    @staticmethod
+    async def scan(timeout: float = 8.0) -> list[dict]:
+        """Scan for BLE devices. The Lumalou advertises its AP number as its name."""
+        found = await BleakScanner.discover(timeout=timeout, return_adv=True)
+        out = [{
+            "address": addr,
+            "name": adv.local_name or dev.name,
+            "rssi": adv.rssi,
+            "manufacturer": {str(k): v.hex() for k, v in adv.manufacturer_data.items()},
+        } for addr, (dev, adv) in found.items()]
+        out.sort(key=lambda r: -(r["rssi"] or -999))
+        return out
+
+    async def connect(self):
+        self._client = BleakClient(self.address)
+        await self._client.connect()
+        await self._client.start_notify(RX, self._on_rx)
+        token = bytes(await self._client.read_gatt_char(FACTORY))
+        device_pub = crypto.token_device_pubkey(token)
+        self._salt = crypto.token_device_salt(token)
+        priv, pub = crypto.generate_keypair()
+        self._nonce = crypto.new_nonce()
+        self._key = crypto.derive_session_key(priv, device_pub)[:16]
+        await self._client.write_gatt_char(SESSION, pub + self._nonce, response=True)  # 37B
+        await asyncio.sleep(0.4)
+        await self._write(C.ENABLE_RX)  # let the toy-IC stream responses
+        await asyncio.sleep(0.3)
+        self.connected = True
+        return self
+
+    async def disconnect(self):
+        self.connected = False
+        if self._client:
+            try:
+                await self._client.disconnect()
+            except Exception:
+                pass
+
+    async def __aenter__(self):
+        return await self.connect()
+
+    async def __aexit__(self, *exc):
+        await self.disconnect()
+
+    async def _write(self, plaintext: bytes):
+        async with self._lock:
+            frame = P.build_tx_frame(plaintext, self._seq, self._key, self._nonce, self._salt)
+            self._seq += 1
+            await self._client.write_gatt_char(TX, frame, response=False)
+            await asyncio.sleep(WRITE_SPACING)
+
+    async def send(self, app_data: bytes):
+        """Send a raw application command ([opcode] + args)."""
+        await self._write(P.encode_command(app_data))
+
+    def _on_rx(self, _sender, data: bytearray):
+        res = P.decrypt_rx_frame(bytes(data), self._key, self._nonce, self._salt)
+        if not res or not res["crc_ok"]:
+            return
+        r = P.parse_response_frame(res["plaintext"])
+        if r.get("ok") and r.get("opcode") == 0x02:
+            st = R.parse_global_state(r["args"])
+            self._state = st
+            for fut in self._state_waiters:
+                if not fut.done():
+                    fut.set_result(st)
+            self._state_waiters.clear()
+            if self._on_state:
+                self._on_state(st)
+
+    async def request_state(self, timeout: float = 3.0) -> Optional[dict]:
+        """Query the full GLOBAL_STATE and return it decoded."""
+        fut = asyncio.get_event_loop().create_future()
+        self._state_waiters.append(fut)
+        await self.send(C.request("global_state"))
+        try:
+            return await asyncio.wait_for(fut, timeout)
+        except asyncio.TimeoutError:
+            return self._state
+
+    @property
+    def state(self) -> Optional[dict]:
+        return self._state
+
+    # ---- high-level API ----
+    async def light_color(self, color: int):
+        await self.send(C.set_light_color(int(color)))
+
+    async def brightness(self, level: int):
+        await self.send(C.set_led_brightness(level))
+
+    async def light_off(self):
+        await self.send(C.turn_off_backlight())
+
+    async def light_duration(self, duration: int):
+        await self.send(C.set_light_duration(int(duration)))
+
+    async def volume(self, level: int):
+        await self.send(C.set_volume(level))
+
+    async def play(self, source: int):
+        await self.send(C.play_audio(int(source)))
+
+    async def audio_off(self):
+        await self.send(C.turn_off_audio())
+
+    async def playlist(self, song_ids):
+        await self.send(C.set_music_playlist(song_ids))
+
+    async def nap(self, duration: int):
+        await self.send(C.start_nap(int(duration)))
+
+    async def soother(self, on: bool = True):
+        await self.send(C.set_global_on(on))
+
+    async def sync_time(self, when: Optional[datetime.datetime] = None):
+        d = when or datetime.datetime.now()
+        weekday = (d.weekday() + 1) % 7  # Python Mon=0..Sun=6 -> device Sun=0..Sat=6
+        await self.send(C.set_current_date(d.hour, d.minute, d.second, weekday))

lumalou-0.1.0/src/lumalou/commands.py

@@ -0,0 +1,134 @@
+"""Command builders. Each returns the app-level payload: [opcode] + args."""
+from __future__ import annotations
+
+from ._generated import COMMANDS, DAY_ROUTINE, Color, Audio, Song, LightDuration, \
+    PlaylistDuration, NapDuration, Alarm, RoutineControl, ClockFormat
+
+NO_MODIFY = 0x0F  # "leave unchanged" sentinel for SET_GLOBAL_STATE fields
+
+_u8 = lambda *a: bytes(a)
+
+
+def bcd(n) -> int:
+    return 0xFF if n is None else (((n // 10) << 4) | (n % 10)) & 0xFF
+
+
+def reduce_low_nibbles(values) -> bytes:
+    v = list(values)
+    if len(v) % 2:
+        v = [0] + v
+    return bytes(((v[i] << 4) | (v[i + 1] & 0x0F)) & 0xFF for i in range(0, len(v), 2))
+
+
+# ---- light ----
+def set_light_color(color) -> bytes:
+    return _u8(COMMANDS["SET_LIGHT_COLOR"], int(color))
+
+
+def set_led_brightness(level: int) -> bytes:
+    return _u8(COMMANDS["SET_LED_BRIGHTNESS"], level & 0xFF)
+
+
+def set_light_duration(duration) -> bytes:
+    return _u8(COMMANDS["SET_SOOTHER_MODE_LIGHT_DURATION"], int(duration))
+
+
+def turn_off_backlight() -> bytes:
+    return _u8(COMMANDS["TURN_OFF_CLOUD_BACKLIGHT"])
+
+
+# ---- audio ----
+def play_audio(source) -> bytes:
+    return _u8(COMMANDS["PLAY_AUDIO"], int(source))
+
+
+def turn_off_audio() -> bytes:
+    return _u8(COMMANDS["TURN_OFF_AUDIO"])
+
+
+def set_playlist_duration(duration) -> bytes:
+    return _u8(COMMANDS["SET_PLAYLIST_DURATION"], int(duration))
+
+
+def set_music_playlist(song_ids) -> bytes:
+    ids = [int(s) for s in song_ids if int(s) != 0][:12]
+    ids += [0] * (12 - len(ids))
+    return bytes([COMMANDS["SET_MUSIC_PLAYLIST"], *ids])
+
+
+# ---- volume ----
+def set_volume(level: int) -> bytes:
+    return _u8(COMMANDS["SET_VOLUME"], level & 0xFF)
+
+
+def set_routine_volume(level: int) -> bytes:
+    return _u8(COMMANDS["SET_ROUTINE_MODE_VOLUME"], level & 0xFF)
+
+
+# ---- system ----
+def set_global_on(on: bool) -> bytes:
+    return _u8(COMMANDS["SET_GLOBAL_ON"], 1 if on else 0)
+
+
+def set_global_state(*, lights_on=None, brightness=None, music_on=None, volume=None,
+                     r2r=None, r2r_alarm=None, nap_alarm=None, routine=None) -> bytes:
+    f = lambda x: NO_MODIFY if x is None else (int(x) & 0x0F)
+    return bytes([COMMANDS["SET_GLOBAL_STATE"], *reduce_low_nibbles(
+        [f(lights_on), f(brightness), f(music_on), f(volume),
+         f(r2r), f(r2r_alarm), f(nap_alarm), f(routine)])])
+
+
+def set_current_date(hour, minute, second, weekday) -> bytes:
+    return _u8(COMMANDS["SET_CURRENT_DATE"], bcd(hour), bcd(minute), bcd(second), bcd(weekday))
+
+
+def set_clock_settings(display_on, brightness, fmt) -> bytes:
+    return bytes([COMMANDS["SET_CLOCK_SETTINGS"],
+                  *reduce_low_nibbles([0, int(bool(display_on)), brightness & 0x0F, int(fmt)])])
+
+
+# ---- timers ----
+def set_r2r_status(on: bool) -> bytes:
+    return _u8(COMMANDS["SET_R2R_STATUS"], 1 if on else 0)
+
+
+def start_nap(duration) -> bytes:
+    return _u8(COMMANDS["START_NAP_TIME"], int(duration))
+
+
+def set_nap_alarm(alarm) -> bytes:
+    return _u8(COMMANDS["SET_NAP_TIME_ALARM"], int(alarm))
+
+
+# ---- routine ----
+def set_routine_status(on: bool) -> bytes:
+    return _u8(COMMANDS["SET_ROUTINE_MODE_STATUS"], 1 if on else 0)
+
+
+def start_routine_mode() -> bytes:
+    return _u8(COMMANDS["START_ROUTINE_MODE"])
+
+
+def routine_control(ctrl) -> bytes:
+    return _u8(COMMANDS["ROUTINE_CONTROL_COMMAND"], int(ctrl))
+
+
+# ---- read-only queries ----
+_REQUESTS = {
+    "global_state": "REQUEST_GLOBAL_STATE", "current_date": "REQUEST_CURRENT_DATE",
+    "toyic_fw_version": "REQUEST_TOYIC_FW_VERSION", "led_brightness": "REQUEST_LED_BRIGHTNESS",
+    "light_color": "REQUEST_LIGHT_COLOR", "light_duration": "REQUEST_SOOTHER_MODE_LIGHT_DURATION",
+    "volume": "REQUEST_VOLUME", "routine_volume": "REQUEST_ROUTINE_MODE_VOLUME",
+    "song_playing": "REQUEST_SONG_PLAYING", "music_playlist": "REQUEST_MUSIC_PLAYLIST",
+    "playlist_duration": "REQUEST_PLAYLIST_DURATION", "operation_mode": "REQUEST_OPERATION_MODE",
+    "activity_state": "REQUEST_ACTIVITY_STATE", "current_stage": "REQUEST_CURRENT_STAGE",
+    "clock_settings": "REQUEST_CLOCK_SETTINGS", "transmission_mode": "REQUEST_TRANSMISSION_MODE",
+}
+
+
+def request(name: str) -> bytes:
+    return _u8(COMMANDS[_REQUESTS[name]])
+
+
+# transport-level: enable the toy-IC to stream responses (raw SSI0 ENABLE_RX)
+ENABLE_RX = bytes([0x01, 0x50, 0x01])

lumalou-0.1.0/src/lumalou/crypto.py

@@ -0,0 +1,63 @@
+"""
+Session-key handshake — pure Python.
+
+Reimplements the device's native MPID handshake (ECDH P-256 + a 100-round
+AES-128-CTR "mattel" stretch), validated bit-exact against golden vectors.
+Depends only on `cryptography`.
+"""
+from __future__ import annotations
+
+import os
+
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+
+_CURVE = ec.SECP256R1()
+_MATTEL = bytes([0x6D, 0x61, 0x74, 0x74, 0x65, 0x6C])  # "mattel"
+
+
+def _aes_ctr(key16: bytes, iv16: bytes, data: bytes) -> bytes:
+    return Cipher(algorithms.AES(key16), modes.CTR(iv16)).encryptor().update(bytes(data))
+
+
+def generate_keypair():
+    """Ephemeral P-256 keypair. Returns (private_key, compressed_pubkey_33B)."""
+    priv = ec.generate_private_key(_CURVE)
+    pub = priv.public_key().public_bytes(Encoding.X962, PublicFormat.CompressedPoint)
+    return priv, pub
+
+
+def ecdh_shared_secret(private_key, peer_pub_compressed: bytes) -> bytes:
+    """ECDH shared secret (X coordinate, 32B). Accepts the peer's compressed public key."""
+    peer = ec.EllipticCurvePublicKey.from_encoded_point(_CURVE, bytes(peer_pub_compressed))
+    return private_key.exchange(ec.ECDH(), peer)
+
+
+def stretch(shared32: bytes) -> bytes:
+    """100 rounds of AES-128-CTR: key = shared[:16], IV = counter + 'mattel'."""
+    s = bytearray(shared32)
+    for counter in range(100):
+        iv = bytes([0, 0, 0, 0, 0, 0, 0, counter, 0]) + _MATTEL + bytes([0])
+        s = bytearray(_aes_ctr(bytes(s[:16]), iv, bytes(s)))
+    return bytes(s)
+
+
+def derive_session_key(private_key, device_pub_compressed: bytes) -> bytes:
+    """32-byte session key (first 16 bytes are the AES-128 data-channel key)."""
+    return stretch(ecdh_shared_secret(private_key, device_pub_compressed))
+
+
+def new_nonce() -> bytes:
+    """4 random bytes (the app 'salt' sent in the SESSION payload)."""
+    return os.urandom(4)
+
+
+def token_device_pubkey(token: bytes) -> bytes:
+    """Device compressed public key: bytes [25:58] of the MFG token."""
+    return bytes(token[25:58])
+
+
+def token_device_salt(token: bytes) -> bytes:
+    """Device salt: last 4 bytes of the MFG token."""
+    return bytes(token[-4:])

lumalou-0.1.0/src/lumalou/protocol.py

@@ -0,0 +1,87 @@
+"""MPID framing and AES-128-CTR data channel. See docs/protocol.md."""
+from __future__ import annotations
+
+import struct
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+SSI0_ID = 0x01
+SPI_WRITE = 0x01
+
+# CRC-8, polynomial 0x07
+_CRC8 = []
+for _i in range(256):
+    _c = _i
+    for _ in range(8):
+        _c = ((_c << 1) ^ 0x07) & 0xFF if (_c & 0x80) else (_c << 1) & 0xFF
+    _CRC8.append(_c)
+
+
+def crc8(data: bytes, init: int = 0xFF) -> int:
+    c = init
+    for b in data:
+        c = _CRC8[(b ^ c) & 0xFF]
+    return c
+
+
+def aes128_ctr(key16: bytes, iv16: bytes, data: bytes) -> bytes:
+    return Cipher(algorithms.AES(key16), modes.CTR(iv16)).encryptor().update(bytes(data))
+
+
+# ---- application framing ----
+def compose_request(app_data: bytes) -> bytes:
+    """FE-frame: 0xFE | len | app_data | XOR(len ^ app_data...)."""
+    xor = len(app_data) & 0xFF
+    for b in app_data:
+        xor ^= b
+    return bytes([0xFE, len(app_data) & 0xFF]) + bytes(app_data) + bytes([xor & 0xFF])
+
+
+def ssi0_wrap(fe_frame: bytes, address: int = 0) -> bytes:
+    return bytes([SSI0_ID, ((SPI_WRITE << 4) & 0xF0) | (address & 0x0F)]) + fe_frame
+
+
+def encode_command(app_data: bytes) -> bytes:
+    """[opcode] + args  ->  MPID plaintext (01 10 | FE-frame)."""
+    return ssi0_wrap(compose_request(app_data))
+
+
+def parse_response_frame(plaintext: bytes) -> dict:
+    """Decode an MPID plaintext response: strip SSI header, then the FE-frame."""
+    d = plaintext
+    ssi = None
+    if len(d) >= 2 and d[0] in (0x01, 0x02):
+        ssi = d[:2].hex()
+        d = d[2:]
+    fe = d.find(b"\xFE")
+    if fe >= 0 and len(d) >= fe + 3:
+        d = d[fe:]
+        length = d[1]
+        body = d[2:2 + length]
+        return {"ssi": ssi, "ok": True,
+                "opcode": body[0] if body else None,
+                "args": bytes(body[1:]) if len(body) > 1 else b""}
+    return {"ssi": ssi, "ok": False}
+
+
+# ---- MPID frame + AES-128-CTR ----
+def _iv(seq: int, a4: bytes, b4: bytes) -> bytes:
+    return struct.pack(">I", seq & 0xFFFFFFFF) + a4 + b4 + b"\x00\x00\x00\x00"
+
+
+def build_tx_frame(plaintext: bytes, seq: int, key16: bytes, nonce4: bytes, dev_salt4: bytes) -> bytes:
+    """App -> device frame. IV = seq || appNonce || deviceSalt || 0."""
+    h0 = bytes([0x7E]) + struct.pack(">I", seq & 0xFFFFFFFF) + struct.pack(">H", (len(plaintext) + 1) & 0xFFFF)
+    header = h0 + bytes([crc8(h0)])
+    body = bytes(plaintext) + bytes([crc8(plaintext)])
+    return header + aes128_ctr(key16, _iv(seq, nonce4, dev_salt4), body)
+
+
+def decrypt_rx_frame(frame: bytes, key16: bytes, nonce4: bytes, dev_salt4: bytes) -> dict | None:
+    """Device -> app frame. IV = seq || deviceSalt || appNonce || 0."""
+    if len(frame) < 9 or frame[0] != 0x7E:
+        return None
+    seq = struct.unpack(">I", frame[1:5])[0]
+    dec = aes128_ctr(key16, _iv(seq, dev_salt4, nonce4), frame[8:])
+    plaintext, crc = dec[:-1], (dec[-1] if dec else 0)
+    return {"seq": seq, "plaintext": plaintext, "crc_ok": crc8(plaintext) == crc}

lumalou-0.1.0/src/lumalou/responses.py

@@ -0,0 +1,52 @@
+"""Decode device responses. Values are raw integers (canonical); use label() for names."""
+from __future__ import annotations
+
+from ._generated import RESPONSES, OperationMode, Stage, Color
+
+
+def _nibbles(data: bytes):
+    out = []
+    for b in data:
+        out.append(b >> 4)
+        out.append(b & 0x0F)
+    return out
+
+
+def parse_global_state(args: bytes) -> dict:
+    """Decode the GLOBAL_STATE snapshot (response 0x02) into raw integer fields."""
+    n = _nibbles(args)
+    while len(n) < 26:
+        n.append(0)
+    return {
+        "operationMode": n[0], "activityState": n[1], "musicStatus": n[2],
+        "currentSong": (n[3] << 4) | n[4], "currentVolume": n[5], "playlistDuration": n[6],
+        "lightStatus": n[7], "lightBrightness": n[8], "lightColor": n[9],
+        "napTimeStatus": n[10], "napDuration": n[11], "ready2RiseStatus": n[12],
+        "ready2RiseAlarmStatus": n[13], "timePrescaler": n[14], "currentStage": n[15],
+        "clockDisplay": n[16], "clockBrightness": n[17], "clockFormat": n[18],
+        "routineMusicStatus": n[19], "taskRewardSfx": n[20], "routineRewardSfx": n[21],
+        "lightDuration": n[22], "routineVolume": n[23], "routineModeStatus": n[24],
+        "alarmExecuting": n[25],
+    }
+
+
+def response_name(opcode: int) -> str:
+    return RESPONSES.get(opcode, f"0x{opcode:02x}")
+
+
+def label(state: dict) -> dict:
+    """Add human-readable labels to a decoded GLOBAL_STATE (non-destructive)."""
+    out = dict(state)
+    try:
+        out["operationModeLabel"] = OperationMode(state["operationMode"]).name
+    except ValueError:
+        pass
+    try:
+        out["currentStageLabel"] = Stage(state["currentStage"]).name
+    except ValueError:
+        pass
+    try:
+        out["lightColorLabel"] = Color(state["lightColor"]).name
+    except ValueError:
+        pass
+    return out

lumalou-0.1.0/src/lumalou.egg-info/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: lumalou
+Version: 0.1.0
+Summary: Local BLE control for the Fisher-Price Lumalou — reverse-engineered MPID protocol, pure Python
+Author: Emanuele Strazzullo
+License: MIT
+Project-URL: Homepage, https://github.com/stramanu/lumalou
+Project-URL: Issues, https://github.com/stramanu/lumalou/issues
+Keywords: fisher-price,lumalou,ble,bluetooth,bleak,reverse-engineering,gld09
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Home Automation
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: bleak>=0.22
+Requires-Dist: cryptography>=41
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+# lumalou (Python)
+
+Local BLE control for the Fisher-Price Lumalou. Pure Python (async, [bleak](https://github.com/hbldh/bleak)).
+
+```bash
+pip install lumalou
+```
+
+## Library
+
+```python
+import asyncio
+from lumalou import LumalouClient, Color
+
+async def main():
+    devices = await LumalouClient.scan()
+    async with LumalouClient(devices[0]["address"]) as luma:
+        await luma.light_color(Color.RAINBOW)
+        await luma.play(0)            # guided sleep playlist
+        await luma.volume(5)
+        print(await luma.request_state())
+
+asyncio.run(main())
+```
+
+## CLI
+
+```bash
+lumalou scan
+lumalou light --color blue --brightness 7
+lumalou sound --source ocean --volume 5
+lumalou soother                 # --off to stop
+lumalou time                    # sync clock
+lumalou state                   # read full state
+lumalou send 3c05               # raw app_data (opcode + args)
+```
+
+Add `-a <address>` to target a device; otherwise it auto-scans.
+
+Requires Python 3.10+, a Bluetooth LE adapter, and radio range of the device.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest        # runs the shared golden vectors (spec/vectors.json)
+```
+
+MIT.

lumalou-0.1.0/src/lumalou.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+src/lumalou/__init__.py
+src/lumalou/_generated.py
+src/lumalou/cli.py
+src/lumalou/client.py
+src/lumalou/commands.py
+src/lumalou/crypto.py
+src/lumalou/protocol.py
+src/lumalou/responses.py
+src/lumalou.egg-info/PKG-INFO
+src/lumalou.egg-info/SOURCES.txt
+src/lumalou.egg-info/dependency_links.txt
+src/lumalou.egg-info/entry_points.txt
+src/lumalou.egg-info/requires.txt
+src/lumalou.egg-info/top_level.txt
+tests/test_vectors.py

lumalou-0.1.0/src/lumalou.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lumalou-0.1.0/src/lumalou.egg-info/entry_points.txt

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

lumalou-0.1.0/src/lumalou.egg-info/requires.txt

@@ -0,0 +1,5 @@
+bleak>=0.22
+cryptography>=41
+
+[dev]
+pytest>=8

lumalou-0.1.0/src/lumalou.egg-info/top_level.txt

@@ -0,0 +1 @@
+lumalou

lumalou-0.1.0/tests/test_vectors.py

@@ -0,0 +1,58 @@
+"""Golden-vector conformance: the Python binding must match spec/vectors.json.
+
+This is the cross-language contract: every binding runs the same vectors.
+"""
+import json
+from pathlib import Path
+
+import pytest
+from cryptography.hazmat.primitives.asymmetric import ec
+
+from lumalou import crypto, protocol as P, responses as R
+
+VECTORS = json.loads((Path(__file__).resolve().parents[3] / "spec" / "vectors.json").read_text())
+
+
+@pytest.mark.parametrize("v", VECTORS["crc8"])
+def test_crc8(v):
+    assert P.crc8(bytes.fromhex(v["data"]), v["init"]) == v["expected"]
+
+
+@pytest.mark.parametrize("v", VECTORS["sessionKey"])
+def test_session_key(v):
+    priv = ec.derive_private_key(int(v["privateScalar"], 16), ec.SECP256R1())
+    key = crypto.derive_session_key(priv, bytes.fromhex(v["devicePubCompressed"]))
+    assert key.hex() == v["expected"]
+
+
+@pytest.mark.parametrize("v", VECTORS["encodeCommand"])
+def test_encode_command(v):
+    assert P.encode_command(bytes.fromhex(v["appData"])).hex() == v["expected"]
+
+
+@pytest.mark.parametrize("v", VECTORS["txFrame"])
+def test_tx_frame(v):
+    frame = P.build_tx_frame(bytes.fromhex(v["plaintext"]), v["seq"],
+                             bytes.fromhex(v["key"]), bytes.fromhex(v["nonce"]), bytes.fromhex(v["salt"]))
+    assert frame.hex() == v["expected"]
+
+
+@pytest.mark.parametrize("v", VECTORS["rxDecrypt"])
+def test_rx_decrypt(v):
+    res = P.decrypt_rx_frame(bytes.fromhex(v["frame"]), bytes.fromhex(v["key"]),
+                             bytes.fromhex(v["nonce"]), bytes.fromhex(v["salt"]))
+    assert res is not None
+    assert res["plaintext"].hex() == v["expectedPlaintext"]
+    assert res["crc_ok"] == v["expectedCrcOk"]
+
+
+@pytest.mark.parametrize("v", VECTORS["globalState"])
+def test_global_state(v):
+    assert R.parse_global_state(bytes.fromhex(v["args"])) == v["expected"]
+
+
+@pytest.mark.parametrize("v", VECTORS["responseFrame"])
+def test_response_frame(v):
+    r = P.parse_response_frame(bytes.fromhex(v["plaintext"]))
+    assert r["ok"] and r["opcode"] == v["expectedOpcode"]
+    assert r["args"].hex() == v["expectedArgs"]