{"id":37609436,"url":"https://github.com/antonvh/mpy-robot-tools","last_synced_at":"2026-01-16T10:17:23.603Z","repository":{"id":39327964,"uuid":"332050739","full_name":"antonvh/mpy-robot-tools","owner":"antonvh","description":"Install on a SPIKE Legacy or LEGO MINDSTORMS Robot Inventor hub for easy Bluetooth communication, animation, and motor synchronization.","archived":false,"fork":false,"pushed_at":"2025-10-11T21:31:40.000Z","size":2367,"stargazers_count":43,"open_issues_count":5,"forks_count":14,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-12-26T10:49:00.883Z","etag":null,"topics":["lego","lego-mindstorms","micropython","robotics"],"latest_commit_sha":null,"homepage":"https://antonsmindstorms.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/antonvh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-01-22T20:05:52.000Z","updated_at":"2025-11-27T14:53:07.000Z","dependencies_parsed_at":"2025-03-12T22:26:32.433Z","dependency_job_id":"34ebb3b4-4ea3-4d9b-b646-f66685a5a211","html_url":"https://github.com/antonvh/mpy-robot-tools","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/antonvh/mpy-robot-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antonvh%2Fmpy-robot-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antonvh%2Fmpy-robot-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antonvh%2Fmpy-robot-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antonvh%2Fmpy-robot-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antonvh","download_url":"https://codeload.github.com/antonvh/mpy-robot-tools/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antonvh%2Fmpy-robot-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478049,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lego","lego-mindstorms","micropython","robotics"],"created_at":"2026-01-16T10:17:22.776Z","updated_at":"2026-01-16T10:17:23.591Z","avatar_url":"https://github.com/antonvh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg alt=\"mpy-robot-tools logo\" src=\"https://raw.githubusercontent.com/antonvh/mpy-robot-tools/master/Images/mpy_robot_tools.png\" width=\"200\"\u003e\n\n# mpy-robot-tools\n\n[![License](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](LICENSE.md)\n[![MicroPython](https://img.shields.io/badge/MicroPython-compatible-orange.svg)](https://micropython.org/)\n[![LEGO](https://img.shields.io/badge/LEGO-SPIKE%20%7C%20MINDSTORMS-yellow.svg)](https://education.lego.com/)\n\nA comprehensive collection of MicroPython libraries and tools for building advanced LEGO robots. Designed for **LEGO SPIKE Prime**, **MINDSTORMS Robot Inventor**, and **ESP32-based** robotics projects.\n\n\u003c/div\u003e\n\nCreate synchronized motor movements, advanced animations, remote control systems, and more with this powerful robotics toolkit. For in-depth articles and tutorials, visit [antonsmindstorms.com](https://antonsmindstorms.com).\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Core Libraries](#core-libraries)\n- [Example Projects](#example-projects)\n- [Documentation](#documentation)\n- [Supported Platforms](#supported-platforms)\n- [Contributing](#contributing)\n- [License](#license)\n- [Author](#author)\n\n## Features\n\n- 🎮 **Remote Control**: BLE RC transmitter/receiver with gamepad-like controls via [btbricks](https://github.com/antonvh/btbricks)\n- ⚙️ **Motor Synchronization**: Advanced motor coordination with animation curves and timing functions\n- 🎨 **LED Animations**: Display utilities for hub LEDs and 5x5 matrix displays\n- 🔌 **SerialTalk**: Symmetrical UART/BLE/WebSocket communication for multi-hub projects\n- 🤖 **Pybricks-like API**: Familiar interface for SPIKE/MINDSTORMS hubs with SI units\n- 🛠️ **Helper Utilities**: Scaling, clamping, interpolation, and timing functions\n- 📡 **Multiple Communication Protocols**: BLE UART, LEGO Protocol, SerialTalk, and more\n\n## Installation\n\n### On SPIKE Prime / MINDSTORMS Robot Inventor\n\n1. Copy the code from the [install script](Installer/install_mpy_robot_tools.py) ([use the Copy raw contents button](https://github.blog/changelog/2021-09-20-quickly-copy-the-contents-of-a-file-to-the-clipboard/))\n2. Paste into an empty Python project in the LEGO SPIKE/MINDSTORMS app\n3. Run the script once (installation takes ~1 minute)\n4. **IMPORTANT**: Watch the console output and unplug the hub when prompted before restart completes\n\n\u003e **Note**: If the app requests a firmware update, you can safely ignore it. Accepting the update will require reinstallation. To exit the update prompt, long-press the center button and power cycle the hub.\n\n### Uninstall\n\nTo uninstall, remove the `/projects/mpy_robot_tools/` directory using a script or file manager (like Thonny IDE).\n\nFor a complete factory reset: In the LEGO app, click **Hub Connection Icon** → **More (···)** → **Reset Settings** → **OK**.\n\n⚠️ **Warning**: Factory reset deletes all programs permanently!\n\n## Quick Start\n\n### Synchronized Motor Animation\n\n```python\nfrom projects.mpy_robot_tools.motor_sync import Mechanism, linear_interpolation\nfrom projects.mpy_robot_tools.pybricks import Motor, Port\n\n# Define motors\nleft = Motor(Port.A)\nright = Motor(Port.B)\n\n# Create animation with keyframes: (time_ms, angle_degrees)\nmovement = linear_interpolation([\n    (0, 0),\n    (1000, 180),\n    (2000, 0)\n])\n\n# Run synchronized mechanism\nmech = Mechanism([left, right], [movement, movement])\nmech.start_loop(duration=2000)\n```\n\n### Remote Control Robot\n\n```python\nfrom projects.mpy_robot_tools.rc import RCReceiver, R_STICK_VER, L_STICK_HOR\nfrom projects.mpy_robot_tools.pybricks import Motor, Port\n\n# Setup motors and RC receiver\nleft_motor = Motor(Port.A)\nright_motor = Motor(Port.B)\nrcv = RCReceiver(name=\"myrobot\")\n\nprint(\"Waiting for RC connection...\")\nwhile True:\n    if rcv.is_connected():\n        # Get joystick values (-100 to 100)\n        throttle = rcv.controller_state(R_STICK_VER)\n        steering = rcv.controller_state(L_STICK_HOR)\n        \n        # Tank drive control\n        left_motor.dc(throttle + steering)\n        right_motor.dc(throttle - steering)\n```\n\n### Display Number on Hub LED Matrix\n\n```python\nfrom projects.mpy_robot_tools.light import image_99\nfrom hub import display\n\n# Display numbers up to 99 on the 5x5 matrix\ndisplay.show(image_99(42))\n```\n\n### Multi-Hub Communication with SerialTalk\n\n```python\nfrom projects.mpy_robot_tools.serialtalk import SerialTalk\nfrom hub import port\n\n# Initialize SerialTalk on a UART port\ntalk = SerialTalk(port.A)\n\n# Define a callable function\n@talk.call\ndef set_motor_speed(speed):\n    print(f\"Setting motor to {speed}\")\n    # Your motor control code here\n\n# Main loop - handle incoming commands\nwhile True:\n    talk.process()  # Non-blocking command processor\n```\n\n## Core Libraries\n\n### motor_sync.py\n\nAdvanced motor synchronization and animation system.\n\n- **`Mechanism(motors, time_functions)`** - Synchronizes multiple motors using time-based functions\n- **`linear_interpolation(keyframes)`** - Creates smooth motion between keyframes\n- **`sine_wave(amplitude, period)`** - Generates sinusoidal motion\n- **`AMHTimer()`** - High-precision millisecond timer\n\n### pybricks.py\n\nPybricks-compatible API for SPIKE Prime and MINDSTORMS Robot Inventor.\n\n- **`Motor(port)`** - Motor control with encoders, SI units, and async support\n- **`Port`** - Port definitions (A, B, C, D, E, F)\n- **`wait(ms)`** - Millisecond-precision wait function\n- **`UltrasonicSensor(port)`** - Distance sensing in mm/cm\n\n### btbricks (submodule)\n\nBluetooth Low Energy communication library. See [btbricks documentation](https://github.com/antonvh/btbricks) for full API.\n\n- **`UARTCentral()`** / **`UARTPeripheral()`** - Nordic UART Service for hub-to-hub communication\n- **`RCReceiver()`** / **`RCTransmitter()`** - Remote control with gamepad interface\n- **`MidiController()`** - Send MIDI over BLE\n- **`BtHub()`** - Control LEGO hubs via Bluetooth\n\n### serialtalk/\n\nSymmetrical communication protocol for UART, BLE, and WebSocket connections.\n\n- **`SerialTalk(port)`** - Remote procedure calls between devices\n- **`@talk.call`** - Decorator to expose functions for remote calling\n- Supports UART, Bluetooth, and WebSocket transports\n- Non-blocking command processing loop\n\n### light.py\n\nLED display utilities for SPIKE/MINDSTORMS hubs.\n\n- **`image_99(number)`** - Display 0-99 on 5x5 LED matrix\n- **`CONNECT_IMAGES`** - Animation frames for connection indicators\n- Custom image utilities and display helpers\n\n### helpers.py\n\nGeneral utility functions.\n\n- **`clamp_int(n, floor, ceiling)`** - Limit values to a range\n- **`scale(val, src_range, dst_range)`** - Map values between ranges\n- **`wait_until(func, condition)`** - Conditional waiting\n\n### HuskyLens Support\n\nFor HuskyLens AI vision sensor integration, see the dedicated [PyHuskyLens library](https://github.com/antonvh/PyHuskyLens) which includes a SPIKE Prime/Robot Inventor installer script.\n\n## Example Projects\n\nThe `Example projects/` directory contains fully working examples:\n\n- **`rc_hotrod_car_receiver.py`** - RC car with BLE remote control\n- **`rc_snake.py`** - Multi-segment robot snake with synchronized movement\n- **`ble_uart_simple_central.py`** / **`ble_uart_simple_peripheral.py`** - Hub-to-hub communication\n- **`bluepad_mecanum_wheels.py`** - Mecanum drive with gamepad control\n- **`inventor_ble_midi_guitar.py`** - MIDI instrument using hub sensors\n\nBrowse the `Example projects/` folder for more inspiration!\n\n## Documentation\n\n### Full API Reference\n\nComprehensive documentation is available at:\n\n**[docs.antonsmindstorms.com](https://docs.antonsmindstorms.com/)**\n\n### In-Code Documentation\n\nAll classes and functions include detailed docstrings. Use `help()` in the REPL:\n\n```python\nfrom projects.mpy_robot_tools.motor_sync import Mechanism\nhelp(Mechanism)\n```\n\n### Tutorials and Articles\n\nVisit [antonsmindstorms.com](https://antonsmindstorms.com) for:\n\n- Step-by-step tutorials\n- Advanced techniques\n- Building instructions\n- Video demonstrations\n\n## Supported Platforms\n\n- **LEGO SPIKE Prime** (all versions)\n- **LEGO MINDSTORMS Robot Inventor** (51515)\n- **LEGO SPIKE Essential** (limited support)\n- **ESP32** with MicroPython (via [LMS-ESP32 board](https://antonsmindstorms.com/product/wifi-python-esp32-board-for-mindstorms/))\n- Other MicroPython boards with compatible peripherals\n\n## Contributing\n\nContributions are welcome! Help improve this project by:\n\n- 📝 Adding documentation, docstrings, or tutorials\n- 🐛 Reporting bugs or issues\n- ✨ Submitting new features or examples\n- 🔧 Improving existing code\n\nPlease fork the repository and submit pull requests.\n\n## License\n\nThis project is licensed under the **GNU General Public License v3.0**.\n\nSee [LICENSE.md](LICENSE.md) for full details.\n\n## Author\n\n**Anton Vanhoucke**\n\n- Website: [antonsmindstorms.com](https://antonsmindstorms.com)\n- GitHub: [@antonvh](https://github.com/antonvh)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantonvh%2Fmpy-robot-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantonvh%2Fmpy-robot-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantonvh%2Fmpy-robot-tools/lists"}