Singular Blockly

A Visual Studio Code extension that provides a visual programming interface using Blockly for Arduino development, with multi-board support and internationalization.

📑 Table of Contents

• Core Dependencies
• Features
• Installation
• Requirements
• Quick Start
• 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)

🌐 Internationalization

• 15 Languages with 98.94% average coverage
• Automatic language detection
• Multi-language block search UI

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)
• 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:

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"
   • "Change the servo angle to 45 degrees"
   • "Show me the generated Arduino code"

💡 Tip: The AI maintains workspace backup (main.json.bak) for safe modifications.

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)

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

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.

🧮 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:

💡 The extension auto-generates platformio.ini with correct settings for hardware upload.

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