easyeda-api

# EasyEDA Pro API Skill Control EasyEDA Pro (嘉立创EDA专业版) programmatically through AI. This skill provides: 1. **Complete API reference** — 120 classes, 62 enums, 70 interfaces, 19 type aliases 2. **WebSocket bridge** — Execute code in the running EasyEDA Pro client 3. **Code patterns** — Common operations for PCB, schematic, library, and project management 4. **Document source format reference** — File format specifications for project, schematic, and PCB sources when users need to analyze or modify EasyEDA document source directly instead of using the API This skill supports not only live debugging in EasyEDA, but also EasyEDA extension development. During EasyEDA extension development, AI agents can use the extension-related documentation, API references, type information, usage examples, and bridge-based debugging capabilities provided by this skill to look up APIs, write code, and validate behavior during integration and debugging. ## Architecture ``` ┌───────────┐ HTTP/WS ┌─────────────────┐ WebSocket ┌───────────┐ │ AI Agent │ ◄───────────► │ Bridge Server │ ◄───────────► │ EasyEDA │ │ │ Port Range │ (Node.js) │ Port Range │ (Client) │ └───────────┘ 49620-49629 └─────────────────┘ 49620-49629 └───────────┘ ``` The server auto-selects an available port from 49620-49629 on startup. Both AI and EDA clients auto-discover the server by scanning the port range and verifying a handshake (`service: "easyeda-bridge"`). ## Quick Start ### 1. Command Triggers When user says **"嘉立创EDA，启动！"**, **"立创EDA，启动！"**, or **"EDA，启动！"**: **IMPORTANT: Session initialization** — Reply immediately with this exact text to set the correct session title: ``` 📋 EasyEDA Session ``` Then proceed with the setup steps below. ### 2. Install dependencies (if needed) ```bash cd ${CLAUDE_SKILL_DIR} && npm install ``` ### 3. Start bridge server > **⚠️ IMPORTANT**: The bridge server must run in the background. Do NOT run it in the foreground, or the AI will block waiting for the server to exit. ```bash # Check if bridge is already running for port in $(seq 49620 49629); do resp=$(curl -s http://localhost:$port/health 2>/dev/null) if echo "$resp" | grep -q '"easyeda-bridge"'; then echo "Bridge already running on port $port" BRIDGE_PORT=$port break fi done # Start bridge if not running if [ -z "$BRIDGE_PORT" ]; then node ${CLAUDE_SKILL_DIR}/scripts/bridge-server.mjs & sleep 2 # Find the port bridge is running on for port in $(seq 49620 49629); do resp=$(curl -s http://localhost:$port/health 2>/dev/null) if echo "$resp" | grep -q '"easyeda-bridge"'; then BRIDGE_PORT=$port break fi done fi echo "Bridge running on port: ${BRIDGE_PORT:-unknown}" ``` ### 4. Connect EasyEDA Install the `run-api-gateway.eext` extension in EasyEDA Pro. Download link: - https://ext.lceda.cn/item/oshwhub/run-api-gateway After the extension is loaded, it will automatically establish the WebSocket connection. ### 5. Verify connection and select EDA window ```bash # Check bridge and EDA connection status curl http://localhost:${BRIDGE_PORT:-49620}/health # List all connected EDA windows curl http://localhost:${BRIDGE_PORT:-49620}/eda-windows ``` The `/eda-windows` response looks like: ```json { "windows": [ { "windowId": "abc-123", "connected": true, "active": true }, { "windowId": "def-456", "connected": true, "active": false } ], "activeWindowId": "abc-123", "count": 2 } ``` **Handle based on window count**: - **0 windows**: Tell user "No EasyEDA window is connected. Please ensure the EasyEDA extension (run-api-gateway.eext) is installed and loaded in EasyEDA. Download: https://ext.lceda.cn/item/oshwhub/run-api-gateway" - **1 window**: Auto-selected as active. Tell user: "✅ Connected! Active EDA window: abc-123. Ready to work." - **2+ windows**: Show the available windows and ask user to select: ``` Multiple EDA windows detected: - abc-123 (active) - def-456 Which EDA window should I use? ``` **Select a window**: ```bash curl -X POST http://localhost:${BRIDGE_PORT}/eda-windows/select \ -H "Content-Type: application/json" \ -d '{"windowId": "abc-123"}' ``` After selection, confirm: "✅ Active EDA window: abc-123. Ready to work." ### 6. Execute code on EDA ```bash curl -X POST http://localhost:${BRIDGE_PORT:-49620}/execute \ -H "Content-Type: application/json" \ -d '{"code": "return await eda.dmt_Project.getCurrentProjectInfo();"}' ``` ## API Documentation The full API reference is in the [references/](references/) directory: - [references/_index.md](references/_index.md) — Master index of all classes, enums, interfaces, and types - [references/_quick-reference.md](references/_quick-reference.md) — All method signatures for rapid lookup - `references/classes/` — 120 class docs (DMT_*, PCB_*, SCH_*, LIB_*, SYS_*, IPCB_*, ISCH_*) - `references/enums/` — 62 enum docs - `references/interfaces/` — 70 interface docs - `references/types/` — 19 type alias docs ### How to look up API 1. **Start with `_index.md`** to find the right class/module for the task 2. **Read the class doc** (e.g., `references/classes/DMT_Board.md`) for all methods and signatures 3. **Use `_quick-reference.md`** for fast method signature lookup across all classes 4. **Check enums/interfaces** for parameter types and return types ### Document Source Format Documentation If the user needs to analyze or modify EasyEDA document source directly instead of using the API, use the documents in the [format/](format/) directory. - [format/index.md](format/index.md) — Overview of the EasyEDA document source format references and version notes - `format/project/` — Project source structure, metadata, blobs, variants, and grouping data - `format/schematic/` — Schematic source format, including structure, wires, shapes, pins, components, and tables - `format/pcb/` — PCB source format, including primitives, pads and vias, shapes, text, attributes, rules, and panel data Use these files when the task is about understanding source layout, generating compatible document source, or editing source data that will later be imported back into EasyEDA. ### API Module Overview | Prefix | Domain | Key Classes | |--------|--------|-------------| | `DMT_` | Document management | Board, EditorControl, Folder, Panel, Pcb, Project, Schematic, SelectControl, Team, Workspace | | `PCB_` | PCB & Footprint | Document, Drc, Event, Layer, Net, Primitive, PrimitiveComponent, PrimitiveLine, PrimitivePad, PrimitivePour, PrimitiveVia, SelectControl | | `SCH_` | Schematic | Document, Event, Primitive, PrimitiveComponent, PrimitiveWire, SelectControl | | `LIB_` | Library | 3DModel, Cbb, Classification, Device, Footprint, LibrariesList, PanelLibrary, SelectControl, Symbol | | `SYS_` | System | Dialog, Environment, FileManager, FileSystem, FontManager, HeaderMenu, I18n, IFrame, LoadingAndProgressBar, Log, Message, MessageBox, MessageBus, PanelControl, Setting, ShortcutKey, Storage, Timer, ToastMessage, WebSocket, Window | | `IPCB_` | PCB interfaces (图元) | PrimitiveArc, PrimitiveComponent, PrimitivePad, PrimitiveFill, PrimitivePour, PrimitiveRegion, PrimitiveVia, ... | | `ISCH_` | Schematic interfaces (图元) | PrimitiveArc, PrimitiveComponent, PrimitiveWire, PrimitiveText, PrimitiveRectangle, ... | | `EPCB_` / `ESCH_` | Enums | PrimitiveType, Layer, PadType, ... | ## Code Execution Context All code runs inside EasyEDA Pro's browser runtime as: ```javascript async function(eda) { // Your code here — `eda` is the global EDA API object // You MUST use `return` to send results back // Do not add comments to the generated code, as the code is typically executed as a single line } ``` **Critical rules:** - The `eda` object provides access to all API modules (e.g., `eda.dmt_Board`, `eda.pcb_Primitive`). - Always refer to the API documentation for correct usage. - Do not add comments to the generated code, as the code is typically executed as a single line. - Always use `return` to get results — `console.log` output is NOT captured. - All API methods returning promises must be `await`ed. - Code runs in browser context — no Node.js APIs (fs, path, etc.) available. - Use `eda.sys_Message.showToastMessage(msg)` for user-visible notifications. - When reviewing API documentation and encountering enumerations, do not guess the enumeration values. You must use the enumeration members, for example: `EPCB_LayerId.TOP` instead of `1` for the layer parameter in PCB primitive creation. ### Extension Runtime Constraints When writing EasyEDA extensions, standard browser APIs are **forbidden** in the main process. Use EDA-provided alternatives: | Purpose | ❌ Forbidden | ✅ Use Instead | |---------|-------------|----------------| | Get user input | — | `eda.sys_Dialog.showInputDialog()` | | User selection | — | `eda.sys_Dialog.showSelectDialog()` | | Show message | `alert()` | `eda.sys_Dialog.showInformationMessage()` | | Confirm action | `confirm()` | `eda.sys_Dialog.showConfirmationMessage()` | | Toast notification | DOM manipulation | `eda.sys_Message.showToastMessage()` | | Store data | `localStorage` (main process) | `eda.sys_Storage.setExtensionUserConfig(key, value)` | | Custom UI | Manipulate host DOM | `eda.sys_IFrame.openIFrame()` | | Show HTML | `showInformationMessage(html)` | Must use iframe | | Open link | `window.open()` | `eda.sys_Window.open()` | | Browser hardware API | Use in main process | Available in iframe (`navigator.serial`, etc.) | **Note:** `localStorage`, `window`, `document` etc. are available **inside `sys_IFrame`** but NOT in the main extension process. ### Extension ↔ IFrame Data Passing The main extension process and `sys_IFrame` iframe are **isolated contexts**. To pass data between them: **Option A (Recommended):** Use `eda.sys_Storage` as a bridge ```javascript // In main extension process: await eda.sys_Storage.setExtensionUserConfig('myKey', JSON.stringify(data)); // In iframe: const data = JSON.parse(await eda.sys_Storage.getExtensionUserConfig('myKey')); ``` **Option B:** Both contexts can access `eda` directly — call the same API from either side ```javascript // In iframe HTML (NOT window.parent.eda): const info = await eda.dmt_Project.getCurrentProjectInfo(); ``` ## Communication Protocol ### Port Discovery The bridge server listens on the first available port in **49620-49629**. To find the server, scan the range and verify the service identity: ```bash for port in $(seq 49620 49629); do resp=$(curl -s http://127.0.0.1:$port/health 2>/dev/null) if echo "$resp" | grep -q '"easyeda-bridge"'; then BRIDGE_PORT=$port; break fi done ``` ### Handshake - **HTTP**: `GET /health` returns `{ "service": "easyeda-bridge", "edaConnected": bool, ... }` - **WebSocket**: On connect, server sends `{ "type": "handshake", "service": "easyeda-bridge" }` - Clients MUST verify `service === "easyeda-bridge"` before using the connection ### Message Format JSON messages over WebSocket / HTTP: | Field | Type | Description | |-------|------|-------------| | `type` | `"execute"` \| `"result"` \| `"error"` \| `"ping"` \| `"pong"` \| `"handshake"` | Message type | | `id` | `string` | Request UUID for matching request/response | | `code` | `string` | JavaScript code to execute (for `execute` type) | | `result` | `any` | Execution result (for `result` type) | | `error` | `string` | Error message (for `error` type) | | `service` | `string` | Service identifier (for `handshake` type) | | `timestamp` | `number` | Unix milliseconds | ## Common Patterns ### Project & Board Operations ```javascript // Get current project info return await eda.dmt_Project.getCurrentProjectInfo(); // List all boards in project return await eda.dmt_Board.getAllBoardsInfo(); // Create a new board (optionally link to schematic/PCB) return await eda.dmt_Board.createBoard(); // Switch to a document tab await eda.dmt_EditorControl.activateDocument(tabId); ``` ### Example: Open a project by name and open its first schematic page ```javascript const targetProjectName = 'NE555 Circuit'; // 1. Enumerate projects by team/folder and find the target by name const teams = await eda.dmt_Team.getAllTeamsInfo(); const seenProjectUuid = new Set(); let targetProjectUuid = null; for (const team of teams || []) { const teamProjects = await eda.dmt_Project.getAllProjectsUuid(team.uuid); for (const projectUuid of teamProjects || []) { if (seenProjectUuid.has(projectUuid)) continue; seenProjectUuid.add(projectUuid); const info = await eda.dmt_Project.getProjectInfo(projectUuid); const name = info?.friendlyName || info?.name || ''; if (name === targetProjectName) { targetProjectUuid = projectUuid; break; } } if (targetProjectUuid) break;