Singular Blockly

Visual programming for Arduino, CyberBrick, and fischertechnik TXT Controller—inside VS Code.

Build with Blockly, preview generated code instantly, and upload through PlatformIO, USB, local-network OTA, or SSH.

Install from VS Code Marketplace · Install from Open VSX · Read the documentation

Feedback, Online Services, and Data Use

Use the clearly labeled Provide Feedback button inside the Blockly editor, run Singular Blockly: Provide Feedback from the Command Palette, or use VS Code's issue reporter. No GitHub account is required. Opening or filling the form makes no network request; before sending, the form shows the complete payload and asks for explicit confirmation.

Basic environment diagnostics are on by default and can be disabled. Recent structured events are off by default. The allowlist excludes source code, Blockly workspace content, generated code, file and folder names, paths, machine and device identifiers, serial ports, Wi-Fi and IP information, environment variables, credentials, raw errors, and raw logs. One optional screenshot is locally re-encoded, stripped of original metadata, limited to 1920 pixels and 3 MiB, previewed, and sent only after confirmation.

Feedback uses an anonymous secret stored in VS Code SecretStorage and a dedicated Cloudflare D1/R2 service; a private GitHub repository is used for maintainer workflow. This user-initiated support transfer is not telemetry or analytics. See the Privacy Notice, Support Policy, Feedback Service Terms, and Security Policy.

Why Singular Blockly?

• One visual editor, three programming workflows: Arduino C++, CyberBrick MicroPython, and TXT Controller Python.
• Hardware-ready uploads: PlatformIO for Arduino, USB or paired LAN OTA for CyberBrick, and SSH for TXT Controller.
• Classroom-friendly tools: localized samples, virtual TXT controls, I/O testing, backups, and clear hardware diagnostics.
• Modern Blockly experience: Blockly 13.2.1 with @blockly/theme-modern, light and dark themes, block search, touch support, keyboard navigation, and semantic control labels—all packaged for offline use.
• Safe project files: automatic persistence, backup recovery, orphan-block guards, and runtime validation of external workspace edits.
• AI-aware projects: project-local Agent Skills plus optional GitHub Copilot shadow-block suggestions.

Quick Start

1. Install Singular Blockly from the VS Code Marketplace or Open VSX.
2. Open a writable folder in VS Code.
3. Click the wand icon in the status bar or the Singular Blockly activity-bar icon.
4. Select a board and build your program from the toolbox.
5. Preview the generated code, then use the shared upload button.

After VS Code startup, Singular Blockly begins preparing its own verified Python, tested-range PlatformIO Core, and mpremote runtime in extension-owned storage. Opening the Blockly editor checks that runtime again without blocking editing. Arduino keeps the existing provider-first route: VS Code uses platformio.platformio-ide, while Open VSX environments such as VSCodium can use pioarduino.pioarduino-ide; the Singular Core is the fallback. A custom managed-runtime folder must be empty when first claimed, preventing repair or cleanup from adopting unrelated files.

code --install-extension singular-blockly-X.Y.Z.vsix

Supported Boards

Arduino projects keep platformio.ini; CyberBrick and TXT projects use Python workflows and remove it when it is not needed.

Key Workflows

Arduino and ESP32

• Generate Arduino C++ and synchronize platformio.ini automatically.
• Compile and upload through PlatformIO with board-aware port detection and actionable error messages.
• Monitor serial output in a VS Code terminal; ESP32 projects enable exception decoding automatically.
• Build with I/O, PWM, servo, encoder motor, Wi-Fi/MQTT, Pixetto, HUSKYLENS, and standard programming blocks.

CyberBrick

• Generate MicroPython for the ESP32-C3, including GPIO, onboard LED, timing, Wi-Fi, X11/X12, and ESP-NOW RC blocks.
• Use USB by default; configure a paired local-network OTA target from the CyberBrick gear menu.
• Complete first-time OTA setup over USB. Failed OTA uploads never fall back to USB automatically, preventing code from reaching the wrong classroom device.
• Keep compatible OTA agents current during network uploads; an agent-update warning does not discard the main program upload.
• Monitor MicroPython print() output through mpremote from a VS Code terminal.
• Browse localized CyberBrick samples with a packaged offline fallback.
• Keep Wi-Fi passwords, OTA tokens, and pairing secrets in VS Code SecretStorage. OTA setup does not modify firmware, /boot.py, WebREPL, or unrelated device files.

CyberBrick details · Expansion boards · RC pairing

TXT Controller

• Author one setup flow and multiple concurrent TXT process flows.
• Upload, run, and stop Python programs over SSH.
• Configure the connection and test it without leaving the Blockly editor.
• Create draggable virtual buttons with stable bindings.
• Test motors, outputs, and sensors from the integrated I/O Test Panel.

TXT passwords are stored in VS Code SecretStorage. The default target is 192.168.7.2 with username ftc; the generated program is uploaded to /tmp/singular_blockly/main.py.

TXT Controller details

AI-Assisted Workflows

Singular Blockly provides two separate AI experiences:

• Project-local Agent Skills give Codex and Claude Code the current board, workspace format, and runtime-derived block contract. No user-installed Node.js server is required.
• Optional GitHub Copilot suggestions can display temporary shadow blocks in the editor. They are disabled by default and remain unsaved until accepted. Use the AI status-bar item to inspect or configure the feature, or request a suggestion with Ctrl+Shift+Space (Cmd+Shift+Space on macOS).

External changes to blockly/main.json pass through disposable Blockly runtimes before reaching the live workspace. Invalid candidates are quarantined and the last valid workspace is restored.

Agent Skills and workspace safety

Project Files

Configuration

Settings are available through VS Code's Settings UI. Defaults below match the extension manifest.

Wi-Fi passwords, OTA tokens, pairing secrets, and TXT passwords are stored in VS Code SecretStorage, not in settings.json. Documentation and logs use placeholders or redacted values; never paste real credentials into project files or bug reports.

Requirements

• VS Code 1.126.0 or later, or VSCodium 1.126.04524 or later. Upgrade older editors before installing this extension version.
• A workspace folder with write access.
• Arduino / ESP32: PlatformIO provider and the C/C++ extension (ms-vscode.cpptools).
• CyberBrick: USB for normal upload and first-time OTA setup; a shared local network only for OTA. The extension prepares mpremote in its own managed Python runtime after activation and rechecks it when the Blockly editor opens.
• TXT Controller: network access to the controller, with Python 3 and ftrobopy available on the device.

Node.js is not required for extension users.

Documentation and Help

The interface ships in 15 languages with 99.36% average coverage. Auto mode follows the VS Code display language, while the editor's globe menu can switch languages immediately.

• Integrated specifications
• PlatformIO diagnostics and guided repair
• Serial Monitor
• Internationalization
• User-facing localization workflow
• Changelog
• Issue tracker
• Security policy

Example project: CyberBrick SoccerBot — an ESP-NOW remote-controlled robot with English and Traditional Chinese documentation.

Development

Contributor baseline: Node.js 24.20.0 (minimum supported: 22.16.0), TypeScript 6.0.3, Blockly 13.2.1, @blockly/theme-modern 13.2.0, and VS Code 1.126.0+.

npm install
npm run compile
npm run lint
npm test
npm run validate:i18n
npm run check:project-skills

When block definitions, toolbox entries, the workspace schema, or packaged Skill content changes, run npm run generate:project-skills before the freshness check. Add new user-facing block messages to all 15 locale files.

License

Licensed under the Apache License 2.0.