kicad-sch-tweak

# KiCad Schematic Editor

Edit KiCad 6+ schematic files (.kicad_sch) using S-expression text format.

## Quick Reference

- **Format docs**: See [references/kicad-sch-format.md](references/kicad-sch-format.md) for complete S-expression syntax

## Recommended Workflow: User + AI Collaboration

**Best practice for adding components:**

1. **User adds components via KiCad GUI**: Use KiCad's graphical interface to add new symbol types. This automatically:
- Populates the `lib_symbols` section with full symbol definitions
- Ensures correct UUID formats
- Handles footprint assignments
- Places components roughly where needed

2. **AI performs text-based tweaks**: After user adds components, AI can efficiently:
- Add/modify global labels and net labels
- Add wires and junctions
- Change component values
- Adjust coordinates
- Add text annotations
- Duplicate existing components (copy from file)

**Why this workflow?**

- Adding NEW symbol types programmatically requires copying entire symbol definitions to `lib_symbols` - tedious and error-prone
- KiCad GUI handles library caching automatically
- AI excels at repetitive text operations (adding 80 labels for 8 IDC headers)
- Reduces risk of file corruption from format mismatches

**Workflow example:**

1. User: "I need 8 IDC headers and 4 fuses" → adds in KiCad, saves
2. AI: "Let me add power rail labels to all headers" → edits .kicad_sch
3. User: Opens KiCad, adjusts layout, verifies connections

## Workflow

### 1. Safety Check & Discover Project

Before editing, always:

1. **Verify file is version-controlled**: Run `git status` to confirm changes can be reverted
2. **Read the target .kicad_sch file** to understand current structure
3. **Find symbol libraries**: Read `sym-lib-table` for available symbol library names
4. **Find available symbols**: Read the project's `.kicad_sym` file(s) referenced in sym-lib-table
5. **Get sheet UUIDs**: Read root `.kicad_sch` for sheet hierarchy and UUIDs

### 2. Understand User Request

Clarify with user if needed:

- Which components to add/modify/remove
- Component values (resistance, capacitance, etc.)
- Connection requirements (what connects to what)
- For new circuits: reference documentation or ASCII diagram

### 3. Make Edits

Use the Edit tool for targeted changes. **Always copy patterns from existing components in the same file.**

**Change component value:**

```lisp
(property "Value" "10k"   ;; Change to new value
```

**Add new component:** Copy existing symbol block from same file, then update:

- `uuid` (generate new unique UUID)
- `(at X Y rotation)` coordinates
- `(property "Reference" "R99"` - next available designator
- `(property "Value" "..."` - component value
- Pin UUIDs (generate new unique ones)
- Instance path (copy from similar component, update reference)

**Add wire:**

```lisp
(wire
  (pts (xy X1 Y1) (xy X2 Y2))
  (stroke (width 0) (type default))
  (uuid "a1b2c3d4-e5f6-7890-abcd-ef1234567890")
)
```

**Add net label:**

```lisp
(label "SIGNAL_NAME"
  (at X Y rotation)
  (effects (font (size 1.27 1.27)) (justify left bottom))
  (uuid "a1b2c3d4-e5f6-7890-abcd-ef1234567890")
)
```

### 4. Validate

After editing:

- Ensure all UUIDs are unique (36-char format, lowercase hex: `a1b2c3d4-e5f6-7890-abcd-ef1234567890`)
- Check S-expression syntax (balanced parentheses)
- Verify library references exist (`lib_id` matches library in sym-lib-table)
- **Suggest user open in KiCad** to visually verify - Claude cannot confirm connectivity
- **For complex edits**: Recommend running KiCad ERC (Electrical Rules Check)

## Project Discovery

For any KiCad project, find these key files:

| File | Purpose | Key Info |
|------|---------|----------|
| `*.kicad_pro` | Project config | Project name, settings |
| `sym-lib-table` | Symbol libraries | Library names and paths |
| `fp-lib-table` | Footprint libraries | Footprint library names |
| Root `.kicad_sch` | Main schematic | Sheet UUIDs, hierarchy |
| `*.kicad_sym` | Symbol definitions | Available component symbols |

**Get library prefix**: Read `sym-lib-table` to find `(name "...")` - use as `lib_id` prefix (e.g., `"mylib:ComponentName"`).

**Get sheet UUID**: Read root schematic's `(uuid "...")` field for root UUID. For sub-sheets, find `(sheet ... (uuid "..."))` blocks.

## Symbol Template

**CRITICAL: Copy from existing component in same file first!** This ensures UUID format and other details match.

If creating from scratch, check the file's UUID format first (quoted vs unquoted), then use:

```lisp
(symbol
	(lib_id "LIBRARY:SYMBOL_NAME")
	(at X Y ROTATION)
	(unit 1)
	(exclude_from_sim no)
	(in_bom yes)
	(on_board yes)
	(dnp no)
	(uuid UNIQUE-UUID-HERE)
	(property "Reference" "R1"
		(at X Y 0)
		(effects
			(font
				(size 1.27 1.27)
			)
		)
	)
	(property "Value" "10k"
		(at X Y 0)
		(effects
			(font
				(size 1.27 1.27)
			)
		)
	)
	(property "Footprint" "LIBRARY:FOOTPRINT"
		(at X Y 0)
		(effects
			(font
				(size 1.27 1.27)
			)
			(hide yes)
		)
	)
	(property "Datasheet" ""
		(at X Y 0)
		(effects
			(font
				(size 1.27 1.27)
			)
			(hide yes)
		)
	)
	(property "Description" ""
		(at X Y 0)
		(effects
			(font
				(size 1.27 1.27)
			)
			(hide yes)
		)
	)
	(pin "1"
		(uuid PIN1-UUID-HERE)
	)
	(pin "2"
		(uuid PIN2-UUID-HERE)
	)
	(instances
		(project ""
			(path "/ROOT-UUID"
				(reference "R1")
				(unit 1)
			)
		)
	)
)
```

**Notes**:

- **UUID format**: Check existing file - use quoted `"uuid"` or unquoted `uuid` to match
- `PROJECT_NAME_OR_EMPTY`: Check existing components - usually `""`
- `ROTATION`: 0, 90, 180, or 270 degrees
- Pin count varies by component - check symbol definition in `.kicad_sym` file

## Power Symbols

Use built-in `power:` library:

```lisp
(symbol
  (lib_id "power:GND")
  (at X Y 0)
  (unit 1)
  (exclude_from_sim no)
  (in_bom yes)
  (on_board yes)
  (dnp no)
  (fields_autoplaced yes)
  (uuid "UNIQUE-UUID")
  (property "Reference" "#PWR01" (at X Y 0) (effects (font (size 1.27 1.27)) (hide yes)))
  (property "Value" "GND" (at X Y 0) (effects (font (size 1.27 1.27))))
  (pin "1" (uuid "PIN-UUID"))
  (instances
    (project "..."
      (path "/..." (reference "#PWR01") (unit 1))
    )
  )
)
```

Common power symbols: `power:GND`, `power:+5V`, `power:+12V`, `power:-12V`, `power:VCC`, `power:VDD`

## Coordinate System

- Origin: top-left of page
- Units: millimeters
- Rotation: degrees (0, 90, 180, 270)
- Grid: 2.54mm (0.1 inch) typical spacing
- **Tip**: Look at nearby components for reasonable coordinates

## Reference Designators

| Prefix | Component |
|--------|-----------|
| R | Resistors |
| C | Capacitors |
| L | Inductors |
| D | Diodes |
| U | ICs/Modules |
| J | Connectors |
| TP | Test points |
| F | Fuses |
| #PWR | Power symbols (hidden) |

## Limitations

- **Layout quality**: Components placed programmatically may overlap. User adjusts in KiCad GUI.
- **Wire routing**: Prefer net labels over complex wire routing for drafts.
- **Pin positions**: Estimated from symbol definitions; may need adjustment.

## CRITICAL: lib_symbols Section (KiCad 9.0+)

**When adding a NEW symbol type to a schematic, you MUST also add its definition to the `lib_symbols` section.**

KiCad caches symbol definitions inside the schematic file. If you add a symbol instance without adding its definition to `lib_symbols`, the file will crash on open.

### How to add a new symbol:

1. **Copy symbol definition** from the `.kicad_sym` library file
2. **Add to lib_symbols** with library prefix (e.g., `"zudo-bus:CL10B104KB8NNNC"`)
3. **Add symbol instance** referencing the same lib_id

Example lib_symbols entry:

```lisp
(lib_symbols
	(symbol "library-name:SymbolName"
		(exclude_from_sim no)
		(in_bom yes)
		(on_board yes)
		(property "Reference" "C"
			...
		)
		;; Copy entire symbol definition from .kicad_sym file
		;; Including all properties, graphics, and pins
		(embedded_fonts no)
	)
)
```

**Notes**:

- Symbol name in lib_symbols must include library prefix: `"library:Symbol"` not just `"Symbol"`
- Copy the ENTIRE symbol definition including all `(symbol "Name_0_1" ...)` graphics blocks
- Add `(embedded_fonts no)` at the end of each symbol in lib_symbols
- If adding multiple symbols, each needs its own definition in lib_symbols

## CRITICAL: Format Matching

**ALWAYS match the existing file's format exactly.** Different KiCad projects may use slightly different S-expression styles. Key variations:

### UUID Format (CRITICAL - causes crashes if wrong!)

Check how UUIDs appear in the existing file:

```lisp
;; Some projects use UNQUOTED UUIDs:
(uuid 26efc87e-0264-438c-bf9f-152a5d6f0f11)

;; Some projects use QUOTED UUIDs:
(uuid "26efc87e-0264-438c-bf9f-152a5d6f0f11")
```

**You MUST use the same format as existing UUIDs in the file!** Mixing formats causes KiCad to crash on open.

### Pin Format

Pins should have uuid on its own line:

```lisp
(pin "1"
	(uuid 00000001-0001-0001-0001-000000000002)
)
```

### Instances Format

The path should have reference and unit on separate lines:

```lisp
(instances
	(project ""
		(path "/26efc87e-0264-438c-bf9f-152a5d6f0f11"
			(reference "C1")
			(unit 1)
		)
	)
)
```

### Text Elements

Text elements should NOT have `(exclude_from_sim no)`:

```lisp
;; CORRECT:
(text "POWER INPUT"
	(at 25.4 25.4 0)
	(effects (font (size 3.81 3.81) (bold yes)))
	(uuid a0000001-0001-0001-0001-000000000001)
)

;; WRONG - causes crashes:
(text "POWER INPUT"
	(exclude_from_sim no)  ;; <-- DO NOT ADD THIS TO TEXT
	(at 25.4 25.4 0)
	...
)
```

### Labels Format

Net labels follow this format:

```lisp
(label "SIGNAL_NAME"
	(at X Y rotation)
	(effects
		(font
			(size 1.27 1.27)
		)
		(justify left bottom)
	)
	(uuid c0000001-0001-0001-0001-000000000001)
)
```

## sym-lib-table Required

If the project doesn't have a `sym-lib-table` file, create one:

```lisp
(sym_lib_table
  (version 7)
  (lib (name "library-name")(type "KiCad")(uri "${KIPRJMOD}/symbols/library-name.kicad_sym")(options "")(descr ""))
)
```

**All libraries referenced by `lib_id` in the schematic MUST be listed in sym-lib-table.**

## Error Recovery

If schematic won't open in KiCad:

**KiCad crashes on open**:

1. Check UUID format - must match existing file (quoted vs unquoted)
2. Check text elements don't have `(exclude_from_sim no)`
3. Verify sym-lib-table exists and references all used libraries

**Parenthesis mismatch**: Check line-by-line for missing `)`. Common: deleted symbol block with dangling reference.

**Invalid UUID**: Must be exactly 36 chars, lowercase hex (0-9, a-f). Quick fix: copy existing UUID and change last 4 digits.

**Missing lib_id**: Symbol not in library. Check:

1. `sym-lib-table` file exists
2. Library is listed in sym-lib-table
3. Symbol name exists in the `.kicad_sym` file

**Revert changes**:

```bash
git checkout -- path/to/file.kicad_sch
```

**Required properties**: Reference, Value, Footprint (Datasheet and Description recommended).