spikeble 0.1__tar.gz

spikeble-0.1/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+.venv*
+local/
+.vscode/
+dist/

spikeble-0.1/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2025 Michael Gross
+
+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.

spikeble-0.1/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: spikeble
+Version: 0.1
+Summary: BLE interface for running Micropython on LEGO SPIKE devices
+Project-URL: Homepage, https://github.com/MGross21/spikeble
+Project-URL: Repository, https://github.com/MGross21/spikeble
+Project-URL: Issues, https://github.com/MGross21/spikeble/issues
+Author-email: Michael Gross <MGross21@users.noreply.github.com>
+License: Copyright 2025 Michael Gross
+        
+        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.
+License-File: LICENSE
+Keywords: ble,bluetooth,lego,robotics,spike
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.11
+Requires-Dist: bleak>=1.0.0
+Description-Content-Type: text/markdown
+
+<h1 align="center">
+    <img src="https://raw.githubusercontent.com/MGross21/spikeble/main/assets/spikeble_logo.png" alt="spikeble logo" width="300" />
+</h1>
+<p align="center">
+    <sub>(pronounced "spike-able")</sub>
+    <br>
+    <img src="https://raw.githubusercontent.com/MGross21/spikeble/main/assets/lego_spike.png" alt="Lego Spike"/>
+</p>
+
+## Installation
+
+*From PyPI:*
+
+```console
+pip install spikeble
+```
+
+*From GitHub:*
+
+```console
+pip install git+https://github.com/MGross21/spikeble.git
+```
+
+> **⚠️ Warning:**  
+> It is **highly recommended** to install and use this library within a Python virtual environment. Installing `spikeble` will expose all MicroPython modules (such as `app`, `color`, `color_matrix`, `color_sensor`, `device`, `distance_sensor`, `force_sensor`, `hub`, `motor`, `motor_pair`, `orientation`, and `runloop`) as direct imports in your environment. Using a virtual environment prevents conflicts with other Python projects and keeps your global Python installation clean.
+>
+> <details>
+> <summary><strong>Making a Python Virtual Environment</strong></summary>
+>
+> ```bash
+> python -m venv .venv
+>
+> # Activate the virtual environment
+> # On Windows:
+> venv\Scripts\activate
+>
+> # On macOS/Linux:
+> source venv/bin/activate
+> ```
+>
+> Once activated, you can install `spikeble` and other dependencies.
+>
+> </details>
+
+## Running Code on SPIKE
+
+To enable auto-complete for MicroPython APIs, place all MicroPython imports inside your `main()` function.  
+Use the template below as a starting point for your SPIKE code:
+
+```python
+import spikeble
+import asyncio
+
+def main():
+    # from app import sound, bargraph, display, linegraph, music
+    import color
+    import color_matrix
+    import color_sensor
+    import device
+    import distance_sensor
+    import force_sensor
+    from hub import port, button, light, light_matrix, motion_sensor, sound
+    import motor
+    import motor_pair
+    import orientation
+    import runloop
+
+    ### Insert Your Code Here ###
+
+if __name__ == "__main__":
+    asyncio.run(spikeble.run(main))
+```
+
+> **Note:**  
+> As of `SPIKE™ Firmware v1.8.149` and `RPC v1.0.47`, using `import app` or `from app import ...` will result in an import error. The `app` module is currently disabled until further notice.
+
+### Other Send Methods
+
+You can also run code on the SPIKE using the following methods:
+
+```python
+spikeble.run_file("path/to/your_script.py")
+```
+
+```python
+spikeble.run_str("print('Hello from SPIKE!')")
+```
+
+## Documentation
+
+- [MicroPython Docs](https://spike.legoeducation.com/prime/modal/help/lls-help-python)
+- [Communication Protocol](https://github.com/LEGO/spike-prime-docs)
+<!-- - [Spike 3 Python Docs (Unofficial)](https://tuftsceeo.github.io/SPIKEPythonDocs/SPIKE3.html) -->

spikeble-0.1/README.md

@@ -0,0 +1,93 @@
+<h1 align="center">
+    <img src="https://raw.githubusercontent.com/MGross21/spikeble/main/assets/spikeble_logo.png" alt="spikeble logo" width="300" />
+</h1>
+<p align="center">
+    <sub>(pronounced "spike-able")</sub>
+    <br>
+    <img src="https://raw.githubusercontent.com/MGross21/spikeble/main/assets/lego_spike.png" alt="Lego Spike"/>
+</p>
+
+## Installation
+
+*From PyPI:*
+
+```console
+pip install spikeble
+```
+
+*From GitHub:*
+
+```console
+pip install git+https://github.com/MGross21/spikeble.git
+```
+
+> **⚠️ Warning:**  
+> It is **highly recommended** to install and use this library within a Python virtual environment. Installing `spikeble` will expose all MicroPython modules (such as `app`, `color`, `color_matrix`, `color_sensor`, `device`, `distance_sensor`, `force_sensor`, `hub`, `motor`, `motor_pair`, `orientation`, and `runloop`) as direct imports in your environment. Using a virtual environment prevents conflicts with other Python projects and keeps your global Python installation clean.
+>
+> <details>
+> <summary><strong>Making a Python Virtual Environment</strong></summary>
+>
+> ```bash
+> python -m venv .venv
+>
+> # Activate the virtual environment
+> # On Windows:
+> venv\Scripts\activate
+>
+> # On macOS/Linux:
+> source venv/bin/activate
+> ```
+>
+> Once activated, you can install `spikeble` and other dependencies.
+>
+> </details>
+
+## Running Code on SPIKE
+
+To enable auto-complete for MicroPython APIs, place all MicroPython imports inside your `main()` function.  
+Use the template below as a starting point for your SPIKE code:
+
+```python
+import spikeble
+import asyncio
+
+def main():
+    # from app import sound, bargraph, display, linegraph, music
+    import color
+    import color_matrix
+    import color_sensor
+    import device
+    import distance_sensor
+    import force_sensor
+    from hub import port, button, light, light_matrix, motion_sensor, sound
+    import motor
+    import motor_pair
+    import orientation
+    import runloop
+
+    ### Insert Your Code Here ###
+
+if __name__ == "__main__":
+    asyncio.run(spikeble.run(main))
+```
+
+> **Note:**  
+> As of `SPIKE™ Firmware v1.8.149` and `RPC v1.0.47`, using `import app` or `from app import ...` will result in an import error. The `app` module is currently disabled until further notice.
+
+### Other Send Methods
+
+You can also run code on the SPIKE using the following methods:
+
+```python
+spikeble.run_file("path/to/your_script.py")
+```
+
+```python
+spikeble.run_str("print('Hello from SPIKE!')")
+```
+
+## Documentation
+
+- [MicroPython Docs](https://spike.legoeducation.com/prime/modal/help/lls-help-python)
+- [Communication Protocol](https://github.com/LEGO/spike-prime-docs)
+<!-- - [Spike 3 Python Docs (Unofficial)](https://tuftsceeo.github.io/SPIKEPythonDocs/SPIKE3.html) -->

spikeble-0.1/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling>=1.27", "hatch-vcs>=0.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spikeble"
+description = "BLE interface for running Micropython on LEGO SPIKE devices"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [{ name = "Michael Gross", email = "MGross21@users.noreply.github.com" }]
+keywords = ["lego", "spike", "ble", "bluetooth", "robotics"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: System :: Hardware",
+]
+dependencies = ["bleak>=1.0.0"]
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://github.com/MGross21/spikeble"
+Repository = "https://github.com/MGross21/spikeble"
+Issues = "https://github.com/MGross21/spikeble/issues"
+
+[tool.hatch.version]
+source = "vcs"
+fallback-version = "0.0.0"
+raw-options = { local_scheme = "no-local-version" }
+
+[tool.hatch.build.targets.wheel]
+packages = ["spikeble"]
+include = ["spikeble/py.typed"]
+
+# Expose MicroPython folders as top-level install packages
+[tool.hatch.build.targets.wheel.force-include]
+"spikeble/micropython/app" = "app"
+"spikeble/micropython/color" = "color"
+"spikeble/micropython/color_matrix" = "color_matrix"
+"spikeble/micropython/color_sensor" = "color_sensor"
+"spikeble/micropython/device" = "device"
+"spikeble/micropython/distance_sensor" = "distance_sensor"
+"spikeble/micropython/force_sensor" = "force_sensor"
+"spikeble/micropython/hub" = "hub"
+"spikeble/micropython/motor" = "motor"
+"spikeble/micropython/motor_pair" = "motor_pair"
+"spikeble/micropython/orientation" = "orientation"
+"spikeble/micropython/runloop" = "runloop"
+
+[tool.hatch.build.targets.sdist]
+include = ["/spikeble", "/README.md", "/LICENSE*", "/pyproject.toml"]
+
+# ---- Tooling ---------------------------------------------------------------
+
+[tool.ruff]
+target-version = "py311"
+line-length = 80
+lint.select = ["E", "F", "I", "UP", "B", "C4", "SIM"]
+
+[tool.pytest.ini_options]
+addopts = "-ra -q"
+testpaths = ["tests"]

spikeble-0.1/spikeble/__init__.py

@@ -0,0 +1,71 @@
+from typing import Callable
+
+async def run_fn(
+    program: Callable[[], None],
+    *,
+    slot: int = 0,
+    stay_connected: bool = False,
+):
+    """Run a Python function on the SPIKE Prime hub."""
+    from .spike import logger
+    from ._utils import fn_to_string
+    try:
+        # call function and see if any front-side errors trigger
+        program()
+    except Exception as e:
+        logger.error(f"Error occurred while running program: {e}")
+    await run_str(
+        fn_to_string(program),
+        slot=slot,
+        name=program.__name__ + ".py",
+        stay_connected=stay_connected
+    )
+
+run = run_fn # shorthand alias default
+
+async def run_file(
+    program_path: str,
+    *,
+    slot: int = 0,
+    stay_connected: bool = False,
+):
+    """Run a Python file on the SPIKE Prime hub."""
+    from .spike import logger
+    from pathlib import Path
+    if not Path(program_path).exists():
+        logger.error(f"File not found: {program_path}")
+        return
+
+    program_str = Path(program_path).read_text()
+    try:
+        compile(program_str, program_path, "exec")
+    except Exception as e:
+        logger.error(f"Error compiling {program_path}: {e}")
+        return
+    await run_str(
+        program_str,
+        slot=slot,
+        name=Path(program_path).name,
+        stay_connected=stay_connected
+    )
+
+async def run_str(
+    program_str: str,
+    *,
+    slot: int = 0,
+    name: str = "program.py",
+    stay_connected: bool = False,
+):
+    """Run a Python string as code on the SPIKE Prime hub."""
+    from .spike import Spike
+    async with Spike(timeout=10, slot=slot) as hub:
+        await hub.get_info()
+        await hub.enable_notifications()
+        await hub.clear_slot()
+        await hub.upload_program(program_str.encode("utf-8"), name=name)
+        await hub.start_program()
+        if stay_connected:
+            try:
+                await hub.run_until_disconnect()
+            except KeyboardInterrupt:
+                await hub.disconnect()

spikeble-0.1/spikeble/_lib/cobs.py

@@ -0,0 +1,125 @@
+"""
+Example implementation of the Consistent Overhead Byte Stuffing (COBS) algorithm
+used by the SPIKE™ Prime BLE protocol.
+
+This implementation prioritizes readability and simplicity over performance and
+should be used for educational purposes only.
+"""
+
+DELIMITER = 0x02
+"""Delimiter used to mark end of frame"""
+
+NO_DELIMITER = 0xFF
+"""Code word indicating no delimiter in block"""
+
+COBS_CODE_OFFSET = DELIMITER
+"""Offset added to code word"""
+
+MAX_BLOCK_SIZE = 84
+"""Maximum block size (incl. code word)"""
+
+XOR = 3
+"""XOR mask for encoding"""
+
+
+# Source: https://lego.github.io/spike-prime-docs/encoding.html#cobs-encode
+def encode(data: bytes):
+    """
+    Encode data using COBS algorithm, such that no delimiters are present.
+    """
+    buffer = bytearray()
+    code_index = block = 0
+
+    def begin_block():
+        """Append code word to buffer and update code_index and block"""
+        nonlocal code_index, block
+        code_index = len(buffer)  # index of incomplete code word
+        buffer.append(NO_DELIMITER)  # updated later if delimiter is encountered
+        block = 1  # no. of bytes in block (incl. code word)
+
+    begin_block()
+    for byte in data:
+        if byte > DELIMITER:
+            # non-delimeter value, write as-is
+            buffer.append(byte)
+            block += 1
+
+        if byte <= DELIMITER or block > MAX_BLOCK_SIZE:
+            # block completed because size limit reached or delimiter found
+            if byte <= DELIMITER:
+                # reason for block completion is delimiter
+                # update code word to reflect block size
+                delimiter_base = byte * MAX_BLOCK_SIZE
+                block_offset = block + COBS_CODE_OFFSET
+                buffer[code_index] = delimiter_base + block_offset
+            # begin new block
+            begin_block()
+
+    # update final code word
+    buffer[code_index] = block + COBS_CODE_OFFSET
+
+    return buffer
+
+
+# Source: https://lego.github.io/spike-prime-docs/encoding.html#cobs-decode
+def decode(data: bytes):
+    """
+    Decode data using COBS algorithm.
+    """
+    buffer = bytearray()
+
+    def unescape(code: int):
+        """Decode code word, returning value and block size"""
+        if code == 0xFF:
+            # no delimiter in block
+            return None, MAX_BLOCK_SIZE + 1
+        value, block = divmod(code - COBS_CODE_OFFSET, MAX_BLOCK_SIZE)
+        if block == 0:
+            # maximum block size ending with delimiter
+            block = MAX_BLOCK_SIZE
+            value -= 1
+        return value, block
+
+    value, block = unescape(data[0])
+    for byte in data[1:]:  # first byte already processed
+        block -= 1
+        if block > 0:
+            buffer.append(byte)
+            continue
+
+        # block completed
+        if value is not None:
+            buffer.append(value)
+
+        value, block = unescape(byte)
+
+    return buffer
+
+
+# Source: https://lego.github.io/spike-prime-docs/encoding.html#cobs-pack
+def pack(data: bytes):
+    """
+    Encode and frame data for transmission.
+    """
+    buffer = encode(data)
+
+    # XOR buffer to remove problematic ctrl+C
+    for i in range(len(buffer)):
+        buffer[i] ^= XOR
+
+    # add delimiter
+    buffer.append(DELIMITER)
+    return bytes(buffer)
+
+
+# Source: https://lego.github.io/spike-prime-docs/encoding.html#cobs-unpack
+def unpack(frame: bytes):
+    """
+    Unframe and decode frame.
+    """
+    start = 0
+    if frame[0] == 0x01:  # unused priority byte
+        start += 1
+    # unframe and XOR
+    unframed = bytes(map(lambda x: x ^ XOR, frame[start:-1]))
+    return bytes(decode(unframed))

spikeble-0.1/spikeble/_lib/connection.py

@@ -0,0 +1,22 @@
+class UUID:
+    """
+    The LEGO SPIKE Prime Hub exposes a BLE GATT service with two characteristics:
+    - RX: for receiving data (from the hub's perspective)
+    - TX: for transmitting data (from the hub's perspective)
+    """
+
+    _BASE = "0000FD02"
+    _TAIL = "1000-8000-00805F9B34FB"
+    SERVICE = f"{_BASE}-0000-{_TAIL}"
+    RX = f"{_BASE}-0001-{_TAIL}"
+    TX = f"{_BASE}-0002-{_TAIL}"
+
+
+class Hardware:
+    MAC_ADDR = "3C:E4:B0:AB:D3:3A"
+
+
+class Name:
+    HINTS = ["SPIKE", "Spike", "Prime", "Hub", "Lego"] + [
+        str(i) for i in range(1, 100)
+    ]

spikeble-0.1/spikeble/_lib/crc.py

@@ -0,0 +1,11 @@
+from binascii import crc32 as _crc32
+
+
+def crc(data: bytes, seed=0, align=4):
+    """
+    Calculate the CRC32 of data with an optional seed and alignment.
+    """
+    remainder = len(data) % align
+    if remainder:
+        data += b"\x00" * (align - remainder)
+    return _crc32(data, seed)

spikeble-0.1/spikeble/_lib/enumeration.py

@@ -0,0 +1,79 @@
+from enum import IntEnum, unique
+
+
+@unique
+class Color(IntEnum):
+    BLACK = 0x00
+    MAGENTA = 0x01
+    PURPLE = 0x02
+    BLUE = 0x03
+    AZURE = 0x04
+    TURQUOISE = 0x05
+    GREEN = 0x06
+    YELLOW = 0x07
+    ORANGE = 0x08
+    RED = 0x09
+    WHITE = 0x0A
+    NONE = 0xFF
+
+
+@unique
+class HubPort(IntEnum):
+    A = 0x00
+    B = 0x01
+    C = 0x02
+    D = 0x03
+    E = 0x04
+    F = 0x05
+
+
+@unique
+class HubFace(IntEnum):
+    TOP = 0x00
+    FRONT = 0x01
+    RIGHT = 0x02
+    BOTTOM = 0x03
+    BACK = 0x04
+    LEFT = 0x05
+
+
+@unique
+class ProgramAction(IntEnum):
+    START = 0x00
+    STOP = 0x01
+
+
+@unique
+class ResponseStatus(IntEnum):
+    ACKNOWLEDGED = 0x00
+    NOT_ACKNOWLEDGED = 0x01
+
+
+@unique
+class MotorEndState(IntEnum):
+    """
+    Smart coast/brake: methods of stopping a motor that compensate for inaccuracies when following commands.
+    """
+
+    COAST = 0x00
+    BRAKE = 0x01
+    HOLD = 0x02
+    CONTINUE = 0x03
+    COAST_SMART = 0x04
+    BRAKE_SMART = 0x05
+    DEFAULT = 0xFF
+
+
+@unique
+class MotorMoveDirection(IntEnum):
+    CLOCKWISE = 0x00
+    COUNTERCLOCKWISE = 0x01
+    SHORTEST_PATH = 0x02
+    LONGEST_PATH = 0x03
+
+
+@unique
+class MotorDeviceType(IntEnum):
+    MEDIUM = 0x30
+    LARGE = 0x31
+    SMALL = 0x41