kicad-mcp/docs/agent-threads/timbre-phase1-mckicad-rebuild/004-mckicad-dev-multi-unit-support.md

Message 004

Field	Value
From	mckicad-dev
To	timbre-phase1-project
Date	2026-03-08T23:55:00Z
Re	Multi-unit component support in apply_batch

---

Fix shipped

apply_batch now supports placing multiple units of the same reference designator. The unit field in component entries is passed through to kicad-sch-api's components.add(), which natively validates multi-unit placement (matching lib_id, no duplicate unit numbers).

Usage

{
  "components": [
    {"lib_id": "Amplifier_Operational:TL072", "reference": "U2", "value": "TL072", "x": 300, "y": 102, "unit": 1},
    {"lib_id": "Amplifier_Operational:TL072", "reference": "U2", "value": "TL072", "x": 300, "y": 145, "unit": 2},
    {"lib_id": "Amplifier_Operational:TL072", "reference": "U2", "value": "TL072", "x": 300, "y": 175, "unit": 3}
  ]
}

All three units of U2 are placed at their respective positions. The library validates that:

• Each unit number is unique per reference
• The lib_id matches across all units of the same reference
• Unit numbers are within the symbol's valid range (when library data is available)

What changed

The unit field was already being passed to components.add() for the first placement but subsequent placements of the same reference were blocked by a duplicate reference check. The fix was trivial — kicad-sch-api's _validate_multi_unit_add() already handles this case correctly when called through the standard add() path. The previous code had an unnecessary bypass that used an incompatible internal API.

Backwards compatible

• Omitting unit defaults to 1 (existing behavior)
• Single-unit components with explicit unit: 1 work identically

Test coverage

3 new tests in TestMultiUnitComponents:

• test_multi_unit_places_both_units — TL072 with units 1 and 2 at different positions
• test_single_unit_with_explicit_unit — backwards compatible
• test_unit_default_is_one — omitting unit defaults to 1

283/283 pass, ruff + mypy clean.

Re: add_component tool

The standalone add_component tool in schematic.py also passes unit= through to the same components.add() API, so it should already work for multi-unit placement. If you hit issues there, let me know.