Skip to content

README.md

Latest commit

 

History

History
154 lines (100 loc) · 7.65 KB

README.md

File metadata and controls

154 lines (100 loc) · 7.65 KB
Raw

Prime Robot Tools for VS Code

Write real Pybricks Python in Visual Studio Code, press F5, and run it on a LEGO Education SPIKE Prime robot over Bluetooth.

This project is designed for a family, coach, or teacher setting: one Windows laptop, one SPIKE Prime hub, and kids who should not need a terminal, Python setup, Bluetooth pairing, or knowledge of the upload protocol.

Current status: The extension and self-contained Windows packaging pipeline are implemented, with automated protocol and controller tests. Physical SPIKE Prime testing is still required before calling this competition-ready. Supervise children while testing moving robots.

What you need

  • A Windows 10 or Windows 11 computer with Bluetooth.
  • Visual Studio Code.
  • A LEGO Education SPIKE Prime hub.
  • The hub's USB data cable only if Pybricks firmware is not installed yet.
  • Internet access for the one-time extension and firmware installation.

You do not manually pair the hub in Windows Bluetooth Settings. The extension finds the Pybricks Bluetooth service itself.

Install Prime Robot Tools

Easiest installation

After a .vsix file has been published on this repository's Releases page, open PowerShell and paste:

irm https://raw.githubusercontent.com/bsambrone/robots4kids/main/setup.ps1 | iex

The script downloads the newest release and asks VS Code to install it. Restart VS Code if it was already open.

Install a downloaded VSIX manually

  1. Download prime-robot-tools-x.y.z.vsix from the Releases page.
  2. Open VS Code.
  3. Open Extensions with Ctrl+Shift+X.
  4. Select the ... menu at the top of Extensions.
  5. Select Install from VSIX... and choose the downloaded file.

If someone gave you a local copy of this repository with an artifacts folder, you can instead right-click setup.ps1, choose Run with PowerShell, and follow the message on screen.

Create the first robot project

  1. Open VS Code.
  2. Press Ctrl+Shift+P to open the Command Palette.
  3. Run Prime Robot: Create New Project.
  4. Choose a new, empty folder.
  5. Open the generated main.py file.

The example expects drive motors on ports A and B, moves forward 200 mm, and turns 90 degrees. Check the ports first, lift the wheels off the table for the first test, or remove the movement lines and keep only the print() line.

The generated prime-robot.json file tells VS Code that the folder is a robot project. F5 is only redirected to the robot while one of these projects is open.

Choose your firmware path

The hub already has Pybricks firmware

This includes the Prime 3 robot described for this project.

  1. No USB cable is needed.
  2. Turn on Bluetooth on the Windows computer.
  3. Close Pybricks Code browser tabs and other robot applications so they do not hold the connection.
  4. Turn on the SPIKE Prime hub.
  5. Return to VS Code and continue with Run the robot.

Do not pair the hub through Windows Settings.

The hub does not have Pybricks firmware

Firmware installation is a one-time adult setup. The extension currently guides you to the official Pybricks installer rather than flashing firmware itself.

  1. Connect the SPIKE Prime hub to the computer with its USB data cable.
  2. In VS Code, press Ctrl+Shift+P.
  3. Run Prime Robot: Set Up Robot. This opens the official Pybricks Code site.
  4. Follow the current official Pybricks firmware instructions for a Prime Hub.
  5. Do not unplug the USB cable or turn off the hub while firmware is being installed.
  6. When installation succeeds, close Pybricks Code so it releases the robot connection.
  7. Restart the hub, unplug USB, and return to VS Code. Normal programming now uses Bluetooth.

Pybricks provides a restore path back to official LEGO firmware from its tools menu if that is ever needed.

Run the robot

  1. Put the robot where it is safe to move.
  2. Turn on the hub.
  3. Open and save the Python program you want to run.
  4. Press F5 or select the Run Robot triangle in the editor title bar.
  5. Watch messages and print() output under View → Output → Prime Robot.

The extension finds the hub, connects, compiles the program, stops the previous program, uploads the new one, and starts it. A compile error is caught before the old robot program is disturbed.

Stop the robot

Press Shift+F5 or select the square Stop button. A normal Stop keeps Bluetooth connected so the next F5 is faster.

For an immediate physical safety stop—or whenever VS Code says the robot disconnected and its program state is unknown—use the hub's physical stop/power button. The extension never automatically restarts a program after an uncertain disconnect.

If something does not work

Robot not found

  1. Make sure the hub is on and is running Pybricks firmware.
  2. Make sure Windows Bluetooth is on.
  3. Close Pybricks Code, other VS Code windows, and terminal robot tools.
  4. Run Prime Robot: Reconnect from Ctrl+Shift+P.
  5. Run Prime Robot: Show Diagnostics and look in Output → Prime Robot.

F5 tries to run desktop Python

Open the folder that contains prime-robot.json, then reopen the Python file. The VS Code status bar should show Robot Offline, Robot Connected, or another Prime Robot state.

See Troubleshooting for disconnect, competing-connection, and diagnostics guidance.

What is included

  • A TypeScript VS Code extension with Run, Stop, Reconnect, Disconnect, Setup, project creation, diagnostics, status-bar state, editor buttons, F5/Shift+F5, output streaming, and Pybricks snippets.
  • A private Python robot service using pybricksdev 2.3.2 library APIs over newline-delimited JSON RPC.
  • A self-contained Windows runtime build using PyInstaller, so the final VSIX does not require Python on the family's computer.
  • Pinned runtime dependencies, tests, an example project, build/package scripts, and third-party notices.

Architecture and the exact upstream API seam are documented in Upstream integration notes. The original engineering specification remains in prime-robot-tools-codex-plan.md.

Developer build

These steps are only for contributors creating the VSIX, not for kids or families installing a release.

Prerequisites: Windows, Node.js/npm, and 64-bit Python 3.13.

# Compile the extension
.\scripts\build.ps1

# Create the Python environment and self-contained Windows robot service
.\runtime\build-runtime.ps1 -Python C:\Path\To\Python313\python.exe

# Run Python tests and TypeScript checks
.\scripts\test.ps1

# Build, test prerequisites, bundle the runtime/stubs, and create the VSIX
.\scripts\package.ps1

The installer is written to artifacts/prime-robot-tools-0.1.0.vsix.

Hardware acceptance tests still need to be performed with the target Windows Bluetooth adapter and physical SPIKE Prime hub. The checklist is in the implementation plan.

Scope and safety

  • Windows 10/11, one VS Code instance, and one SPIKE Prime hub are the V1 target.
  • Student code runs on the hub, never as desktop Python.
  • Pybricks firmware is required; first-time installation is currently browser-guided.
  • Bluetooth operations use timeouts, repeated Runs are serialized, and Stop cancels a pending start.
  • A disconnect does not prove a moving robot stopped. Use the hub controls when in doubt.

Prime Robot Tools is independent and is not endorsed by the LEGO Group. LEGO and SPIKE are trademarks of the LEGO Group. Pybricks components are maintained by the Pybricks project; see Third-party notices.