btbricks 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

btbricks/__init__.py

@@ -7,7 +7,7 @@ use it to create custom Bluetooth peripherals like RC controllers or MIDI
 devices compatible with LEGO hubs.
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.3"
 __author__ = "Anton Vanhoucke"
 __license__ = "MIT"
 

{btbricks-0.2.1.dist-info → btbricks-0.2.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: btbricks
-Version: 0.2.1
+Version: 0.2.3
 Summary: A MicroPython Bluetooth library for remote controlling LEGO hubs via BLE
 Home-page: https://github.com/antonvh/btbricks
 Author: Anton Vanhoucke
@@ -28,6 +28,9 @@ Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
 Requires-Dist: black>=23.0; extra == "dev"
 Requires-Dist: flake8>=5.0; extra == "dev"
 Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: mpy-cross>=1.20; extra == "dev"
+Requires-Dist: requests>=2.28.0; extra == "dev"
+Requires-Dist: markdown-link-validator>=0.1.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx>=4.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
@@ -37,17 +40,24 @@ Dynamic: home-page
 Dynamic: license-file
 Dynamic: requires-python
 
-# btbricks
-
+<div align="center">
 <img alt="btbricks logo" src="https://raw.githubusercontent.com/antonvh/btbricks/master/img/btbricks.png" width="200">
 
+# btbricks
+
 [![PyPI Version](https://img.shields.io/pypi/v/btbricks.svg)](https://pypi.org/project/btbricks/)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![MicroPython](https://img.shields.io/badge/MicroPython-compatible-orange.svg)](https://micropython.org/)
 
-A MicroPython Bluetooth library. It implements BLE (Bluetooth 5, Bluetooth Low Energy). Of the know BLE services, this library implements Nordic Uart Service (NUS), LEGO Service and MIDI service. The library contains both the BLE Central (client) and BLE Peripheral (server) classes.
+btbricks is MicroPython Bluetooth library. It implements **BLE** (Bluetooth 5, Bluetooth Low Energy). Of the know BLE services, this library implements **Nordic Uart Service** (NUS), **LEGO Service** and **MIDI service**. The library contains both the BLE Central (client) and BLE Peripheral (server) classes.
+
+</div>
 
-These BLE services allow for controlling LEGO hubs, running official firmware. The services also allow creating custom Bluetooth peripherals: RC controllers, MIDI devices, etc. To control the LEGO hubs, you can best use a [hub expansion board, like the LMS-ESP32](https://www.antonsmindstorms.com/product/wifi-python-esp32-board-for-mindstorms/).
+The BLE services allow controlling LEGO hubs running official firmware. You can
+also create custom Bluetooth peripherals: RC controllers, MIDI devices, and more.
+For LEGO hub control, a
+[hub expansion board like the LMS-ESP32](https://www.antonsmindstorms.com/product/wifi-python-esp32-board-for-mindstorms/)
+is recommended.
 
 ## Table of Contents
 
@@ -56,28 +66,45 @@ These BLE services allow for controlling LEGO hubs, running official firmware. T
 - [Quick Start](#quick-start)
 - [Documentation](#documentation-and-api-reference)
 - [Supported Platforms](#supported-platforms)
-- [Firmware Notes](#firmware-notes)
 - [License](#license)
 - [Author](#author)
 
 ## Features
 
-- 🔌 **BLE Communication**: Comprehensive Bluetooth Low Energy support via MicroPython's `ubluetooth`
-- 🎮 **Hub Control**: Control LEGO MINDSTORMS hubs, SPIKE sets, and smart hubs over Bluetooth
-- 📱 **Custom Peripherals**: Create RC controllers, MIDI controllers, and other BLE peripherals compatible with LEGO hubs
-- 🚀 **MicroPython Ready**: Optimized for MicroPython on ESP32, LEGO SPIKE, and other platforms
-- 📡 **LEGO Protocol**: Full support for LEGO Bluetooth protocols (LPF2, LPUP, CTRL+)
-- 🎛️ **Multiple Interfaces**: Nordic UART, MIDI, RC control, and native LEGO hub communication
-- ⚙️ **Advanced BLE**: Automatic MTU negotiation, descriptor handling, and efficient payload management
+- 🔌 **BLE Communication**: Comprehensive Bluetooth Low Energy support via
+  MicroPython's `ubluetooth`
+- 🎮 **Hub Control**: Control LEGO MINDSTORMS hubs, SPIKE sets, and smart hubs
+  over Bluetooth
+- 📱 **Custom Peripherals**: Create RC controllers, MIDI controllers, and other
+  BLE peripherals compatible with LEGO hubs
+- 🚀 **MicroPython Ready**: Optimized for MicroPython on ESP32, LEGO SPIKE, and
+  other platforms
+- 📡 **LEGO Protocol**: Full support for LEGO Bluetooth protocols (LPF2, LPUP,
+  CTRL+)
+- 🎛️ **Multiple Interfaces**: Nordic UART, MIDI, RC control, and native LEGO hub
+  communication
+- ⚙️ **Advanced BLE**: Automatic MTU negotiation, descriptor handling, and
+  efficient payload management
 
 ## Installation
 
+### Using ViperIDE Package Manager (Recommended)
+
+1. Open **ViperIDE** on your device
+2. Go to **Tools** → **Package Manager**
+3. Select **Install Package via Link**
+4. Enter the package link: `https://github.com/antonvh/btbricks.git`
+5. Follow the on-screen prompts to complete installation
+
 ### On LMS-ESP32
 
-The module should be included in the latest Micropython firmware from <https://wwww.antonsmindstorms.com>. If not, use ViperIDE or Thonny and create a new file called rcservo.py.
-Copy the contents from the same file in this repository inside.
+The module should be included in the latest Micropython firmware from <https:/firmware.antonsmindstorms.com>. If not, use ViperIDE as described above.
 
-### On MicroPython device using `micropip` from PyPI
+### On SPIKE Legacy or MINDSTORMS Robot Inventor
+
+Use the installer script in mpy-robot-tools: <https://github.com/antonvh/mpy-robot-tools/blob/master/Installer/install_mpy_robot_tools.py>
+
+### Deprecated: using `micropip` from PyPI
 
 ```python
 import micropip
@@ -86,10 +113,6 @@ await micropip.install("btbricks")
 
 Note: `micropip` must be available on the target board and may require an internet connection from the device.
 
-### On SPIKE Legacy or MINDSTORMS Robot Inventor
-
-Use the installer script in mpy-robot-tools: <https://github.com/antonvh/mpy-robot-tools/blob/master/Installer/install_mpy_robot_tools.py>
-
 ## Quick Start
 
 ### Connect to a LEGO Hub
@@ -119,7 +142,9 @@ if hub.is_connected():
 ```
 
 ### Create an RC Receiver (Hub-side)
-Use the examples in the `examples/` folder for full, runnable code. Minimal receiver/transmitter snippets:
+
+Use the examples in the `examples/` folder for full, runnable code. Minimal
+receiver/transmitter snippets:
 
 ```python
 from btbricks import RCReceiver, R_STICK_HOR, R_STICK_VER
@@ -195,7 +220,7 @@ except KeyboardInterrupt:
 
 See the full documentation and API reference at:
 
-https://docs.antonsmindstorms.com/en/latest/Software/btbricks/docs/index.html
+[docs.antonsmindstorms.com](https://docs.antonsmindstorms.com/en/latest/Software/btbricks/docs/index.html)
 
 ### Core Classes
 
@@ -222,7 +247,6 @@ https://docs.antonsmindstorms.com/en/latest/Software/btbricks/docs/index.html
 - **ESP32** with MicroPython
 - Other MicroPython boards with `ubluetooth` support
 
-
 ## License
 
 MIT License

{btbricks-0.2.1.dist-info → btbricks-0.2.3.dist-info}/RECORD

@@ -1,13 +1,14 @@
-btbricks/__init__.py,sha256=U1Yxw-A51X4eGmuACmqdfRpb9v_CNs6sgTy4RBKMQZU,1051
+btbricks/__init__.py,sha256=eUuqwGNWUQIA61IJp_p-b79RyEl2bvR_0mQmeQ_beeI,1051
 btbricks/bt.py,sha256=JLtXm3RsfpLTbWzGYhrEC1_AMlTpyXHaEoBR1Q5lC7A,44575
 btbricks/bthub.py,sha256=TVvpVo5E9nIzwmASMTAjjLs0lbY4Su4CYFlBU4KZ3dY,7967
 btbricks/ctrl_plus.py,sha256=CAnkG_SZ9Zysv4ZUDJ7UE0HTLMGeZYD0JxPEIIf-o6Y,177
-btbricks-0.2.1.dist-info/licenses/LICENSE,sha256=yVFkYtNY8Mlp5U_xedI4-O8Hxjg_vu-taxJlv8y-xVk,1078
+btbricks-0.2.3.dist-info/licenses/LICENSE,sha256=yVFkYtNY8Mlp5U_xedI4-O8Hxjg_vu-taxJlv8y-xVk,1078
 tests/__init__.py,sha256=CtJ2NCOCvkNNpVgAw3XHsKd_S-C36d7Yuq4QfTPmwgg,34
 tests/test_bthub.py,sha256=9yyBhsydjwN7_yXKzsKTEAxcjW_PqOzwZFcQ2dDv_f0,3298
 tests/test_constants.py,sha256=L0rIn8VsPIPc80qITblsPu9mQltL85pAFLQl2KQUpGY,2023
 tests/test_imports.py,sha256=kHrRnueFPnQxU807Bo9Ddr3x4hsryMroUoWC816N-Nc,2147
-btbricks-0.2.1.dist-info/METADATA,sha256=mdeew3CTC3HfEYMKbHW8AcN2jhrzep9Cf9rUMSE_WkY,7770
-btbricks-0.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-btbricks-0.2.1.dist-info/top_level.txt,sha256=nznVmPKoDx79OB6rEM180swD9X5G22V35afi5zon1d8,15
-btbricks-0.2.1.dist-info/RECORD,,
+tests/test_precommit_checks.py,sha256=mXDtYdLFDgBdOrMBGZyaGz5Z4QtzSfwFpP7axU_H-WE,7075
+btbricks-0.2.3.dist-info/METADATA,sha256=oZGjCxcMEkjr96h-xxk956TLDmdlhEjX4DwwXiRz48o,8160
+btbricks-0.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+btbricks-0.2.3.dist-info/top_level.txt,sha256=nznVmPKoDx79OB6rEM180swD9X5G22V35afi5zon1d8,15
+btbricks-0.2.3.dist-info/RECORD,,

tests/test_precommit_checks.py

@@ -0,0 +1,221 @@
+"""Pre-commit checks for dead links and mpy-cross compilation."""
+
+import os
+import re
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import List, Set
+
+import pytest
+import requests
+
+
+def find_markdown_files() -> List[Path]:
+    """Find all markdown files in the project."""
+    root = Path(__file__).parent.parent
+    md_files = []
+    for ext in ["*.md", "*.MD"]:
+        md_files.extend(root.glob(ext))
+        md_files.extend(root.glob(f"**/{ext}"))
+
+    # Exclude hidden directories and common ignore patterns
+    excluded = {".git", "node_modules", ".venv", "venv", "__pycache__"}
+    return [
+        f for f in md_files if not any(part.startswith(".") or part in excluded for part in f.parts)
+    ]
+
+
+def extract_urls_from_markdown(file_path: Path) -> Set[str]:
+    """Extract all HTTP(S) URLs from a markdown file."""
+    content = file_path.read_text(encoding="utf-8", errors="ignore")
+
+    # Match markdown links [text](url) and plain URLs
+    url_pattern = r"https?://[^\s\)<>\"\']+"
+    urls = set(re.findall(url_pattern, content))
+
+    # Clean up any trailing punctuation that might have been captured
+    cleaned_urls = set()
+    for url in urls:
+        # Remove trailing punctuation and backticks
+        url = re.sub(r'[.,;:!?\)`]+$', "", url)
+        cleaned_urls.add(url)
+
+    return cleaned_urls
+
+
+def is_url_valid(url: str, timeout: int = 10) -> tuple[bool, int]:
+    """Check if a URL is accessible.
+
+    Returns:
+        tuple of (is_valid, http_code)
+    """
+    # Skip localhost and example URLs
+    if "localhost" in url or "example.com" in url or "127.0.0.1" in url:
+        return True, 200
+
+    try:
+        # Use HEAD request first (faster)
+        response = requests.head(
+            url,
+            timeout=timeout,
+            allow_redirects=True,
+            headers={"User-Agent": "Mozilla/5.0 (compatible; LinkChecker/1.0)"},
+        )
+
+        # Some servers don't support HEAD, try GET if HEAD fails
+        if response.status_code >= 400:
+            response = requests.get(
+                url,
+                timeout=timeout,
+                allow_redirects=True,
+                headers={"User-Agent": "Mozilla/5.0 (compatible; LinkChecker/1.0)"},
+            )
+
+        # Consider 200-399 as valid
+        return response.status_code < 400, response.status_code
+
+    except requests.exceptions.Timeout:
+        return False, 408  # Request Timeout
+    except requests.exceptions.ConnectionError:
+        return False, 0  # Connection failed
+    except requests.exceptions.RequestException:
+        return False, 0  # Other request errors
+
+
+def find_python_files() -> List[Path]:
+    """Find all Python files in the btbricks package."""
+    root = Path(__file__).parent.parent
+    btbricks_dir = root / "btbricks"
+
+    if not btbricks_dir.exists():
+        return []
+
+    py_files = []
+    for py_file in btbricks_dir.rglob("*.py"):
+        # Skip __pycache__ and other temp directories
+        if "__pycache__" not in py_file.parts:
+            py_files.append(py_file)
+
+    return py_files
+
+
+def check_mpy_cross_available() -> bool:
+    """Check if mpy-cross is available."""
+    # Try to find mpy-cross in venv first
+    venv_mpy_cross = Path(__file__).parent.parent / ".venv" / "bin" / "mpy-cross"
+    if venv_mpy_cross.exists():
+        return True
+
+    # Fall back to checking PATH
+    try:
+        result = subprocess.run(
+            ["mpy-cross", "--version"], capture_output=True, text=True, timeout=5
+        )
+        return result.returncode == 0
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def compile_with_mpy_cross(py_file: Path) -> tuple[bool, str]:
+    """Try to compile a Python file with mpy-cross.
+
+    Returns:
+        tuple of (success, error_message)
+    """
+    # Find mpy-cross command
+    venv_mpy_cross = Path(__file__).parent.parent / ".venv" / "bin" / "mpy-cross"
+    mpy_cross_cmd = str(venv_mpy_cross) if venv_mpy_cross.exists() else "mpy-cross"
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        output_file = Path(tmpdir) / "temp.mpy"
+
+        try:
+            result = subprocess.run(
+                [mpy_cross_cmd, str(py_file), "-o", str(output_file)],
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+
+            if result.returncode == 0:
+                return True, ""
+            else:
+                return False, result.stderr or result.stdout
+
+        except subprocess.TimeoutExpired:
+            return False, "Compilation timeout"
+        except Exception as e:
+            return False, str(e)
+
+
+class TestDeadLinks:
+    """Test for dead links in markdown files."""
+
+    def test_no_dead_links(self):
+        """Check that all links in markdown files are valid."""
+        md_files = find_markdown_files()
+
+        if not md_files:
+            pytest.skip("No markdown files found")
+
+        all_urls = set()
+        url_sources = {}  # Track which file each URL came from
+
+        for md_file in md_files:
+            urls = extract_urls_from_markdown(md_file)
+            for url in urls:
+                all_urls.add(url)
+                if url not in url_sources:
+                    url_sources[url] = set()
+                url_sources[url].add(md_file.name)
+
+        if not all_urls:
+            pytest.skip("No URLs found in markdown files")
+
+        dead_links = []
+
+        for url in sorted(all_urls):
+            is_valid, http_code = is_url_valid(url)
+            if not is_valid:
+                sources = ", ".join(sorted(url_sources[url]))
+                dead_links.append(f"{url} (HTTP {http_code}) in {sources}")
+
+        if dead_links:
+            error_msg = f"Found {len(dead_links)} dead link(s):\n"
+            error_msg += "\n".join(f"  - {link}" for link in dead_links)
+            pytest.fail(error_msg)
+
+
+class TestMpyCrossCompilation:
+    """Test that all Python files compile with mpy-cross."""
+
+    def test_mpy_cross_installed(self):
+        """Check that mpy-cross is available."""
+        if not check_mpy_cross_available():
+            pytest.fail(
+                "mpy-cross is not installed or not available in PATH.\n"
+                "Install with: pip install mpy-cross"
+            )
+
+    def test_all_files_compile(self):
+        """Check that all Python files in btbricks/ compile with mpy-cross."""
+        if not check_mpy_cross_available():
+            pytest.skip("mpy-cross not available")
+
+        py_files = find_python_files()
+
+        if not py_files:
+            pytest.skip("No Python files found in btbricks/")
+
+        failed_compilations = []
+
+        for py_file in py_files:
+            success, error = compile_with_mpy_cross(py_file)
+            if not success:
+                failed_compilations.append(f"{py_file.name}: {error}")
+
+        if failed_compilations:
+            error_msg = f"Failed to compile {len(failed_compilations)} file(s) with mpy-cross:\n"
+            error_msg += "\n".join(f"  - {failure}" for failure in failed_compilations)
+            pytest.fail(error_msg)