# KiCad Service

A shared KiCad CLI HTTP service running on a dedicated Adom container. Provides headless KiCad operations without needing KiCad installed locally.

**This is NOT the same as adom-desktop KiCad control.** Two different things:

| | KiCad Service (this skill) | adom-desktop KiCad |
|---|---|---|
| **Where KiCad runs** | Dedicated server container | User's Windows/Mac desktop |
| **GUI** | None — headless CLI only | Full KiCad GUI (schematic editor, PCB layout, 3D viewer) |
| **What it does** | DRC, Gerber export, SVG rendering, STEP/GLB export, symbol/footprint search | Open/close editors, install symbols/footprints, screenshot windows, handle dialogs |
| **Install needed** | None — already running | Yes — user installs Adom Desktop app |
| **Best for** | Automated validation, rendering, batch export | Interactive editing, visual inspection, demo recordings |

## When to use which

- "Run DRC on my board" → **KiCad Service** (this skill)
- "Open my schematic in KiCad" → **adom-desktop** (needs desktop install)
- "Export gerbers from a .kicad_pcb file" → **KiCad Service**
- "Show me the KiCad Symbol Editor" → **adom-desktop**
- "Render my footprint as SVG" → **KiCad Service**
- "Install this symbol into KiCad's library" → **adom-desktop**

## Service URL

```
https://coder.john-service-kicad-cli-5948815f6104358b.containers.adom.inc/proxy/8780
```

This is a shared service available to all Adom containers. Use `$KICAD_API` if set, otherwise use the URL above.

```bash
# Health check
curl -s "https://coder.john-service-kicad-cli-5948815f6104358b.containers.adom.inc/proxy/8780/health"
# → {"ok":true,"kicad_version":"9.0.7","uptime_seconds":...}
```

## API Client

JavaScript client with all functions:

```javascript
import { checkHealth, symSearch, pcbDrc, pcbExportGerbers, ... } from '/home/adom/project/gallia/viewer/kicad-api-client.js';
```

## Available Operations

### Health Check

```javascript
const health = await checkHealth();
// → { ok: true, kicadVersion: "9.0.1", uptimeSeconds: 12345, cacheSizeMb: 42 }
```

### Symbol Operations

```javascript
// Search for symbols
const results = await symSearch("STM32F103", 20);

// Get symbol details
const sym = await symGet("Device", "R");

// Export symbol as SVG
const svg = await symExportSvg("/path/to/file.kicad_sym", "SYMBOL_NAME");

// Export by library+name (cached)
const svg = await symExportSvgByName("Device", "R");
```

### Footprint Operations

```javascript
// List footprints
const fps = await fpList({ library: "Package_SO" });

// Export footprint as SVG
const svg = await fpExportSvg("/path/to/file.kicad_mod", "SOT-23");
const svg = await fpExportSvgByName("Package_SO", "SOT-23");

// Export as GLB (3D model)
const glb = await fpExportGlbByName("Package_SO", "SOT-23", "/tmp/sot23.glb");

// Export as STEP
const step = await fpExportStepByName("Package_SO", "SOT-23", "/tmp/sot23.step");

// Download footprint file
await fpDownload("Package_SO/SOT-23.kicad_mod", "/tmp/sot23.kicad_mod");
```

### PCB / Board Operations

```javascript
// Run Design Rule Check
const drc = await pcbDrc("/path/to/board.kicad_pcb");
// → { violations: [...], errorCount: 2, warningCount: 5 }

// Export Gerbers
const gerbers = await pcbExportGerbers("/path/to/board.kicad_pcb", "/tmp/gerbers/");

// Export board as GLB (3D model)
const glb = await boardExportGlb("/path/to/board.kicad_pcb", "/tmp/board.glb");

// Export footprint from PCB as STEP
const step = await pcbExportStep("/path/to/board.kicad_pcb", "U1", "/tmp/u1.step");
```

### 3D Model Operations

```javascript
// List available 3D models
const models = await models3dList({ library: "Package_SO" });

// Download a 3D model
await models3dDownload("Package_SO/SOT-23.step", "/tmp/sot23.step");
```

## Error Handling

The health check distinguishes three failure modes:

1. **Service healthy** — KiCad CLI available, ready for operations
2. **Node process down** — Container running but Node server crashed. The service auto-restarts, retry in 30s.
3. **Container unreachable** — ECONNREFUSED/ETIMEDOUT. Container may be stopped or not provisioned.

```javascript
const health = await checkHealth();
if (!health.ok) {
  console.error(health.status);     // 'node_down' | 'container_unreachable' | 'unknown_error'
  console.error(health.suggestion); // Human-readable fix suggestion
}
```

## Which skills use the KiCad Service

- **board-creator** — DRC validation on generated PCB boards
- **symbol-creator** — SVG rendering of created symbols
- **footprint-creator** — SVG rendering, STEP/GLB export of footprints
- **3d-component-creator** — GLB export for 3D viewer
- **gerber-viewer** — Gerber file generation
- **instapcb** — DRC before manufacturing submission
- **library-creator** — Symbol/footprint validation

## NOT the same as adom-desktop

If the user wants to:
- **See the KiCad GUI** → they need `adom-desktop` (install the desktop app)
- **Open a schematic in the editor** → `adom-desktop`
- **Install a symbol into their local KiCad library** → `adom-desktop`
- **Control KiCad windows, handle dialogs** → `adom-desktop`

This service is for headless, API-driven operations only.