The ultimate Visual Studio Code extension for professional Pybricks development. Streamline your LEGO robotics workflow with one-click program execution, real-time hub output, a comprehensive GUI for settings, and customizable sound feedback.
🔥 Key Features
🚀 One-Click Execution: Run your Python scripts on any Pybricks hub directly from VS Code with a single click or keyboard shortcut (F10).
📡 Real-Time Output: See print() statements and program output from your hub instantly in the VS Code output channel. No more waiting for the program to finish!
⚙️ Graphical Settings UI: A clean, user-friendly settings panel to configure everything. No more manual JSON editing.
🔊 Customizable Sound Effects: Get audible feedback for key events!
Hub Connected
Download Started
Program Started
Program Finished Successfully
Program Failed or Errored
🎵 Custom Sound Support: Easily set your own sound files for each event. On Windows, .wav files are used for seamless background playback.
🔍 Hub Discovery: Scan for available Pybricks hubs directly from the settings panel.
🛠️ Connection Testing: A simple "Test Connection" button to verify that pybricksdev is correctly installed and accessible.
📜 Main Program Support: Set a primary script to run even when no file is open in the editor.
✅ Clean and Modern UI: A polished user experience from top to bottom.
📦 Installation
Install the Extension:
Open the Extensions view in VS Code (Ctrl+Shift+X).
Search for Pybricks Runner Pro.
Click Install.
Install pybricksdev: This extension requires the official pybricksdev command-line tool to communicate with the hub.
Open a terminal (Ctrl+\).
The recommended way to install is via pip:
pip install pybricksdev
Verify the installation by running:
pybricksdev --version
If you see a version number, you're all set!
🚀 How to Use
Running a Program
From an open file: With a Python file open, click the "Play" icon in the editor's title bar, or press F10.
From the Command Palette: Open the Command Palette (Ctrl+Shift+P), type Pybricks, and select Run on Pybricks Hub.
From the File Explorer: Right-click any .py file and select Run on Pybricks Hub.
Accessing Settings
Open the Command Palette (Ctrl+Shift+P).
Type Pybricks and select Open Pybricks Settings.
The graphical settings panel will open, allowing you to configure everything.
⚙️ Configuration
All settings can be configured through the Pybricks Settings panel.
Connection
Hub Name: The exact name your hub broadcasts over Bluetooth. Use the Scan for Hubs button if you're unsure.
Connection Timeout: How long (in milliseconds) the extension should wait for a connection before giving up.
Auto-Connect on Run: If checked, the extension will immediately try to connect when you run a program.
Program
Main Program File: Set a default .py file. This allows you to run a specific program using the command palette even if you have a different file open. Use the Browse... and Clear buttons to manage this.
Sound Effects
Enable Sounds: A master switch to turn all sound effects on or off.
Event Sounds: For each event (Connect, Download, etc.), you can provide a full path to a sound file.
On Windows, only .wav files are supported for seamless background playback.
On macOS/Linux, .wav, .mp3, and .ogg are supported.
Leave the path empty to use the default (if available) or no sound.
Behavior
Show Output on Run: Automatically open the "Pybricks Runner" output channel when you start a program.
Verbose Logging: Show extra, detailed logs in the output channel. This is very useful for troubleshooting connection problems.
troubleshooting
"pybricksdev is not installed or not found in PATH"
This means the extension cannot find the pybricksdev tool.
Ensure you have installed it using pip install pybricksdev.
Make sure your Python Scripts directory is in your system's PATH environment variable.
You can test this by opening a new terminal and typing pybricksdev --version. If it works there, it should work in VS Code after a restart.
I can't hear any sound effects on Windows
Make sure the sound files you have selected in the settings are in the .wav format. Other formats like .mp3 will fail silently.
Ensure the path to the .wav file is correct and the file exists.
Check the "Pybricks Runner" output channel for any [SOUND ERROR] messages.
My program's print() messages appear only at the end
This was a known issue with output buffering in older versions. The latest version of the extension has fixed this by forcing unbuffered output, so you should see messages in real-time. If you still experience this, please open an issue on GitHub.
Developed by ThomasChong. For feature requests or to report bugs, please visit the GitHub repository.
