Singular Blockly

VS Code extension for visual Arduino & MicroPython programming with Blockly. Multi-board support (Uno, Nano, Mega, ESP32, CyberBrick), WiFi/MQTT IoT blocks, AI camera integration (Pixetto, HuskyLens), MCP server for GitHub Copilot, PlatformIO integration, and 15 languages with 99% coverage.

📑 Table of Contents

• Core Dependencies
• Features
• Installation
• Requirements
• Quick Start
• Examples & Projects
• Usage
• Block Categories
• Supported Boards and Platforms
• Extension Settings
• Known Issues
• License
• Contributing

Core Dependencies

• Blockly: 12.3.1 - Visual programming library
• @blockly/theme-modern: 7.0.1 - Modern theme with darker borders
• Node.js: 22.16.0+ required
• VS Code: 1.105.0+ required

Features

🎯 Multi-Board Support

• Arduino Uno, Nano, Mega
• ESP32 Dev Module
• Super Mini (Lolin C3 Mini)
• 🆕 CyberBrick (ESP32-C3, MicroPython)

🌐 Internationalization

• 15 Languages with 98.94% average coverage
• In-editor language picker (globe icon) with instant UI updates
• Auto mode follows VS Code's display language
• Multi-language block search UI

Change Language (in editor):

1. Click the globe icon in the Blockly toolbar
2. Choose Auto (follow VS Code) or a specific language
3. The Blockly UI updates immediately

Change VS Code Display Language (affects Auto):

1. Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
2. Type "Configure Display Language"
3. Select your preferred language
4. VS Code will restart and Blockly Auto mode will follow

| Language | Code | Coverage | | ------------------- | ------- | -------- | | English | en | 99.3% | | Traditional Chinese | zh-hant | 99.3% | | Spanish | es | 98.9% | | Portuguese (Brazil) | pt-br | 98.9% | | French | fr | 98.9% | | German | de | 98.9% | | Italian | it | 98.9% | | Russian | ru | 98.9% | | Japanese | ja | 98.9% | | Korean | ko | 98.9% | | Polish | pl | 98.9% | | Turkish | tr | 98.9% | | Hungarian | hu | 98.6% | | Bulgarian | bg | 98.6% | | Czech | cs | 98.6% |

Quality Assurance:

• ✅ Automated validation (placeholders, encoding, consistency)
• ✅ Direct translation pattern detection
• ✅ Monthly CI/CD quality audits
• 📚 Localization Quickstart Guide

💾 Workspace Management

• Automatic state saving and project persistence
• Board configuration management
• Arduino code generation (.cpp files)
• 🆕 MicroPython code generation (CyberBrick)
• Automatic PlatformIO configuration
• Project Safety Guard 🛡️
  • Smart project type detection (Node.js, Python, Java, etc.)
  • Warning dialog to prevent accidental modifications
  • Workspace-level preference memory
• Comprehensive Backup System
  • Timestamped backups with preview
  • Safe restoration with temporary backups
  • Auto-backup with configurable intervals
  • Modern responsive UI

🛠 Development Features

• Real-time code generation with manual refresh
• Visual drag-and-drop block interface
• Integrated board configuration
• Block Search 🔍
  • Search by name or parameter (Ctrl+F)
  • Highlight and navigate results
  • Multi-language UI support
• Experimental Blocks Tracking
  • Yellow dashed border indicators
  • Notification system
• Theme support (light/dark with toggle)
• Touch device support (pinch-to-zoom)
• PlatformIO integration for hardware upload
• Pin Mode Tracking
  • Auto-track modes (INPUT, OUTPUT, INPUT_PULLUP)
  • Conflict detection and warnings
  • Auto-add pinMode configurations

🤖 AI Integration with MCP Server

Seamless integration with GitHub Copilot and AI assistants through the Model Context Protocol (MCP).

AI-Assisted Block Programming:

• Block Query: Ask AI "How do I use the servo motor block?" and get detailed usage info
• Smart Suggestions: AI understands your hardware setup and suggests compatible blocks
• Natural Language: Add blocks using commands like "Add an ultrasonic sensor block"
• Project Awareness: AI knows your board type, pins, and current workspace state

Available MCP Tools:

| Tool | Description | | ------------------------- | --------------------------------------------------------------- | | get_block_usage | Get detailed block documentation with fields and JSON templates | | search_blocks | Search blocks by keyword (Chinese/English), sorted by relevance | | list_blocks_by_category | Browse blocks by category (15 categories available) | | get_workspace_state | Read current workspace, block arrangement, and board config | | update_workspace | Add, modify, delete, or replace blocks in workspace | | refresh_editor | Sync changes to the visual editor after workspace updates | | get_platform_config | Get board configuration and PlatformIO settings | | get_board_pins | Query pin capabilities (digital, analog, PWM, I2C, SPI) | | get_generated_code | Read the generated Arduino/MicroPython code |

Getting Started with AI:

1. Open VS Code with Copilot Agent Mode enabled
2. The MCP Server auto-registers when extension activates
3. Use natural language in Copilot chat:
   • "What servo blocks are available?"
   • "Add a servo setup block on pin 9"
   • "Show me blocks in the motors category"
   • "Show me the generated Arduino code"

💡 Tip: The AI maintains workspace backup (main.json.bak) for safe modifications. Use get_block_usage with context parameter to get ready-to-use JSON templates.

Installation

From VS Code Marketplace (Recommended)

1. Open VS Code
2. Go to Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Singular Blockly"
4. Click Install

Offline Installation (GitHub Release)

For restricted network environments (企業內網 / 教育環境):

1. Download the latest .vsix file from GitHub Releases
2. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
3. Select "Extensions: Install from VSIX..."
4. Choose the downloaded .vsix file

Command Line Alternative:

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

Requirements

• Visual Studio Code 1.105.0 or higher
• Node.js 22.16.0 or higher
• Basic understanding of Arduino programming concepts
• Required Extensions:
  • PlatformIO IDE Extension
  • C/C++ Extension (ms-vscode.cpptools)
• For CyberBrick (MicroPython):
  • Python 3.x installed
  • mpremote tool (pip install mpremote)

Quick Start

Get started in 3 minutes:

1. Install the extension from VS Code Marketplace
2. Open a folder (File → Open Folder)
3. Click the wand icon 🪄 in the status bar
4. Select your Arduino board from the dropdown
5. Drag blocks from the toolbox and start coding!

💡 First time? The extension will auto-generate platformio.ini and src/main.cpp for you.

Usage

1. Open or create a folder in VS Code:

   • This extension requires a workspace folder to store its files
   • Use File > Open Folder... or File > New Folder
   • Make sure you have write permissions in the folder
   • Note: The extension will warn you if opened in a non-Blockly project to prevent accidental file modifications

2. Open the extension using:

   • Click the wand icon (🪄) in the status bar
   • Click the Singular Blockly icon in the activity bar

3. Select your target board from the dropdown menu:

   • The extension will automatically create and configure platformio.ini
   • First-time board selection requires a workspace reload

4. Create your program using the visual blocks:

   • Drag blocks from the toolbox categories
   • Configure block parameters
   • Connect blocks to build your logic
   • Changes are auto-saved and persist between sessions

5. The extension will automatically:

   • Generate Arduino code in src/main.cpp
   • Save workspace state in blockly/main.json
   • Update PlatformIO configuration
   • Provide real-time code(.cpp) generation

📚 Examples & Projects

Explore real-world projects built with Singular Blockly:

| Project | Description | Board | | -------------------------------------------------------------------------------------- | --------------------------------------------------- | ---------- | | CyberBrick SoccerBot 🌐 EN/繁中 | Remote-controlled soccer robot with ESP-NOW pairing | CyberBrick |

💡 Tip: Have a project to share? Submit a PR to add it here!

Block Categories

🔌 Arduino I/O Operations

• Smart pin options with automatic PWM pin detection
• Optimized analog write functionality for PWM pins

⚙️ ESP32 PWM Configuration (v0.43.0+)

• Custom PWM frequency (1-80000 Hz) and resolution (8-16 bit)
• High-frequency PWM for motor driver chips (20-75KHz)
• Automatic validation: frequency × 2^resolution ≤ 80,000,000
• Backward compatible (default: 75000Hz / 8bit)
• Independent from ESP32Servo blocks

🎮 Servo Motor Control

• Configurable setup and angle control
• Smart dropdown with auto-detection
• Board-specific library support (ESP32/Arduino)

🔧 Encoder Motor Support

• Setup, read, reset, and PID control
• Automatic pin management

📡 Sensor Blocks

Ultrasonic Sensor

• Hardware interrupt support
• Smart block linking (trigger + read)
• Auto-detection between blocks

Seven-Segment Display

• Common cathode/anode modes

Threshold Functions

• Analog input monitoring

📷 Pixetto Smart Camera

• Complete visual recognition system
• Color Detection: 8 colors (red, blue, green, yellow, orange, purple, black, white)
• Shape Detection: triangle, rectangle, pentagon, hexagon, circle
• Face Detection and AprilTag Recognition
• Neural Network and Handwritten Digit Recognition
• Road Detection with center/boundary info
• Position data (X, Y, width, height)
• UART configuration (RX/TX pins)

🤖 HUSKYLENS Smart Camera (Experimental)

• Advanced AI vision system
• Dual Modes: I2C and UART
• Recognition Algorithms:
  • Face recognition
  • Object tracking/recognition
  • Line tracking
  • Color recognition
  • Tag recognition
  • Object classification
• Real-time block/arrow detection results
• Interactive learning functions
• Position and ID information

📡 ESP32 WiFi/MQTT Communication (v0.47.0+)

WiFi Connectivity (ESP32/Super Mini only)

• Connect/Disconnect with 10-second timeout protection
• Network scanning with SSID and signal strength
• Connection status monitoring
• IP address retrieval

MQTT IoT Communication

• Broker setup (server, port, client ID)
• Publish/Subscribe messaging
• Message callback handling
• Auto-include PubSubClient library dependency

Utility Blocks

• to_string - Convert numbers/booleans to strings
• text_to_number - Convert strings to integers/floats

💡 WiFi/MQTT blocks appear only when ESP32 boards are selected. Non-ESP32 boards show a warning.

🐍 CyberBrick MicroPython Blocks (v0.49.0+)

ESP32-C3 MicroPython visual programming for CyberBrick board:

Main & GPIO

• Main program structure (setup/loop equivalent)
• Digital GPIO read/write
• GPIO mode configuration (INPUT/OUTPUT/PULLUP/PULLDOWN)

LED Control

• RGB LED with customizable colors
• Brightness control

Time Functions

• Delay in milliseconds
• Delay in seconds

WiFi Connectivity

• Connect/Disconnect
• Connection status
• IP address retrieval

X11 Extension Board (v0.51.0+)

• 180° Servo angle control (S1-S4 ports)
• 360° Servo speed control (S1-S4 ports)
• DC Motor speed control (M1-M2 ports)
• WS2812 LED strip color control (D1-D2 ports)

🆕 X12 Transmitter Extension Board (v0.52.0+)

• Local joystick reading (L1-L3, R1-R3 axes, ADC 0-4095)
• Joystick value mapping to custom range
• Local button state detection (K1-K4)

🆕 Serial Monitor (v0.60.0+)

• Real-time serial output viewing in VS Code terminal
• Arduino boards: Uses pio device monitor with auto baud rate detection from platformio.ini
• CyberBrick: Uses mpremote for MicroPython print() output
• Auto-close before upload to release COM port, auto-restart after success
• ESP32 boards auto-enable exception decoder for crash analysis
• Monitor button shows for all board types

Built-in MicroPython Generators

• Complete logic, loops, math, text, list, variable, and function block support
• Clean Python code generation with proper indentation
• One-click upload via mpremote tool

💡 When switching to CyberBrick, platformio.ini is auto-removed to avoid conflicts. Workspace is auto-backed up before board switch.

⚠️ Compatibility Note: This tool uses the officially supported mpremote method to upload code—it does not modify or damage the official firmware. You can switch back to the official CyberBrick editor anytime by simply uploading from it, which will overwrite the program directly (tested and verified).

🧮 Programming Constructs

Functions

• Parameter support
• Custom threshold functions
• Multiple output types (numeric, boolean, string)
• Chinese function name conversion

Variables

• Rename/delete capabilities

Data Structures

• Lists and Arrays

Control Flow

• Logic Operations
• Loops (repeat, while, for)
• Time-based duration loops
• Flow control (break, continue) with validation

Operations

• Math Operations
• Text Operations
• Value Mapping (Arduino map() function)

Supported Boards and Platforms

Each board is configured with optimized PlatformIO settings:

| Board | Platform | Board ID | Architecture | | ------------------------------ | ----------- | -------------- | ------------ | | Arduino Uno | atmelavr | uno | AVR | | Arduino Nano | atmelavr | nanoatmega328 | AVR | | Arduino Mega | atmelavr | megaatmega2560 | AVR | | ESP32 Dev Module | espressif32 | esp32dev | ESP32 | | Super Mini (Lolin C3 Mini) | espressif32 | lolin_c3_mini | ESP32-C3 | | 🆕 CyberBrick | MicroPython | esp32c3 | ESP32-C3 |

💡 The extension auto-generates platformio.ini with correct settings for hardware upload (Arduino boards), or uses mpremote for MicroPython upload (CyberBrick).

Extension Settings

• singularBlockly.safetyGuard.suppressWarning
  • Type: boolean
  • Default: false
  • Scope: Workspace-level
  • Description: Suppress safety warnings when opening non-Blockly projects

Project Safety Guard 🛡️

The extension detects non-Blockly projects (Node.js, Python, Java, etc.) and shows a warning dialog:

• Continue → Proceed with opening
• Cancel → Abort operation
• Don't remind again → Suppress warnings for this workspace

Re-enable warnings by changing workspace settings:

{
	"singularBlockly.safetyGuard.suppressWarning": false
}

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Third-Party Licenses

This project incorporates the following third-party components:

• Blockly - Apache License 2.0
• PlatformIO - Apache License 2.0
• Arduino Core Libraries - LGPL

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Resources:

• GitHub Repository
• Issue Tracker
• Localization Guide