Library Migration Guide

Blockly Library Conversion Guide

A systematic guide for converting Arduino libraries into Aily Blockly libraries, based on real conversion cases (ArduinoJson, OneButton, MQTT/PubSubClient, DHT, INA219, VL53L0X, etc.).

Conversion Workflow

Prerequisites

1. Use the existing environment/project context first to determine whether a project is already open.
2. If no project exists, use project with action="create" to create one, then continue with the new project path.

⚠️ CRITICAL: Library Working Directory

All library files MUST be created in <projectPath>/<library-name>/, NOT in node_modules/.

• ✅ Correct: <projectPath>/lib-grove_motor/block.json
• ❌ Wrong: <projectPath>/node_modules/@aily-project/lib-grove_motor/block.json

The node_modules/ directory is managed by npm and is write-protected. After creating the library locally, install it with: npm install ./<library-name>

If a file write operation returns a path/permission error, check your target path — you are likely writing to node_modules/ instead of <projectPath>/<library-name>/. Fix the path and retry. Do NOT attempt to bypass by using terminal commands (mkdir, echo, Out-File, etc.) to write into protected directories.

Step-by-step Process

1. Source Analysis: Analyze the Arduino library header files to identify public APIs. Classify by operation type: initialization, connection, communication, status, maintenance, quick operations.

2. Block Design: Design user-friendly blocks following block type mapping rules (see Section "Block Design Rules" below).

3. Create Library Files in <projectPath>/<library-name>/:

   • block.json — Block definitions
   • generator.js — Code generator
   • toolbox.json — Toolbox configuration
   • package.json — Library metadata

4. Copy Source Files: Use run_terminal to copy the Arduino source:

   • If src/ folder exists → copy to <projectPath>/<library-name>/src/<library-name>/
   • If no src/ folder → copy .c, .cpp, .h, .hpp files to <projectPath>/<library-name>/src/<library-name>/

5. Write README.md: First read Blockly_Library_README_Conventions.md (fetch from https://blockly.diandeng.tech/files/Blockly_Library_README_Conventions.md), then follow its format.

6. Post-conversion: Ask the user if they need help with:

   • Installing: npm i <library-path> (must specify the local library path)
   • Testing the converted library
   • Opening the library folder location

Library Directory Structure

library-name/
├─ block.json        // Block definitions
├─ generator.js      // Code generator
├─ toolbox.json      // Toolbox configuration
├─ package.json      // Library metadata
├─ README.md         // Human-readable documentation
├─ README_AI.md      // LLM-readable documentation
└─ src/
   └─ library-name/  // Copied Arduino source files

Detailed Code Specification

IMPORTANT: For complete code specification with detailed examples, read the companion file Blockly_Library_CODE_Conventions.md located in this skill's folder. It covers:

• Full block.json design rules with templates for every block type
• Complete generator.js implementation patterns with real-world examples
• toolbox.json shadow blocks and organization
• package.json configuration with board compatibility
• Board adaptation patterns and WiFi library selection

The sections below summarize the critical rules that MUST be followed.

Block Design Rules

Block Type Mapping

field_input vs field_variable

• field_input: For initialization blocks — user enters a NEW variable name
• field_variable: For method call blocks — user selects an EXISTING variable (set variableTypes and defaultType)
• Global objects (Serial, WiFi, Wire, SPI, httpUpdate, SPIFFS, ESP, EEPROM): No variable field needed

Reading Variable Names in generator.js

// field_input
const varName = block.getFieldValue('VAR') || 'defaultVar';

// field_variable
const varField = block.getField('VAR');
const varName = varField ? varField.getText() : 'defaultVar';

// Global object — use directly
const serialPort = block.getFieldValue('SERIAL') || 'Serial';

Board Config Template Variables (block.json)

Use these in field_dropdown options — auto-populated at runtime: