jlcpcb-bom-generate-from-kicad

# KiCad to JLCPCB BOM/CPL Converter

Convert KiCad exported BOM and position files to JLCPCB PCBA order format.

## Quick Start

**IMPORTANT**: This skill includes ready-to-use Python scripts! Use them instead of copying inline code.

### Scripts Location

```
$HOME/.claude/skills/jlcpcb-bom-generate-from-kicad/scripts/
├── convert_to_jlcpcb.py      # Main conversion script
├── add_lcsc_numbers.py        # Add LCSC part numbers
└── create_parts_mapping.py    # Generate mapping template
```

### Basic Usage

```bash
# Step 1: Convert KiCad exports to JLCPCB format
python3 $HOME/.claude/skills/jlcpcb-bom-generate-from-kicad/scripts/convert_to_jlcpcb.py \
  bom.csv top.pos bottom.pos output_dir/

# Step 2: Add LCSC part numbers (interactive mode)
python3 $HOME/.claude/skills/jlcpcb-bom-generate-from-kicad/scripts/add_lcsc_numbers.py \
  output_dir/jlcpcb-bom.csv --interactive

# Or use mapping file
python3 $HOME/.claude/skills/jlcpcb-bom-generate-from-kicad/scripts/add_lcsc_numbers.py \
  output_dir/jlcpcb-bom.csv --map parts_mapping.json --filter-test-points
```

## Template Files

Reference templates (downloaded from JLCPCB) are located at:

- `$HOME/.claude/skills/jlcpcb-bom-generate-from-kicad/templates/sample-bom.xlsx`
- `$HOME/.claude/skills/jlcpcb-bom-generate-from-kicad/templates/sample-cpl.xlsx`

## Input Files (KiCad Exports)

### KiCad BOM CSV

Exported from KiCad's BOM tool. Format (semicolon-delimited):

```
"Id";"Designator";"Footprint";"Quantity";"Designation";"Supplier and ref";
1;"U6";"TO-263-2_L10.0-W9.1-P5.08-LS15.2-TL";1;"L7812CD2T-TR";;;
2;"R12,R3,R13";"R0603";3;"5.1k";;;
```

### KiCad Position Files (.pos)

Exported from KiCad's Fabrication Outputs > Component Placement. Format:

```
# Ref     Val               Package                   PosX       PosY       Rot  Side
C1        10uF              C1206                     46.7500   -12.4325  180.0000  top
R1        10k               R0603                     38.8600   -29.5025   90.0000  top
```

## Output Files (JLCPCB Format)

### JLCPCB BOM CSV

```csv
Comment,Designator,Footprint,JLCPCB Part #
L7812CD2T-TR,U6,TO-263-2_L10.0-W9.1-P5.08-LS15.2-TL,C13456
5.1k,"R13,R3,R12",R0603,C23186
```

### JLCPCB CPL (Component Placement List) CSV

```csv
Designator,Mid X,Mid Y,Layer,Rotation
C1,46.7500mm,12.4325mm,Top,180
R1,38.8600mm,29.5025mm,Top,90
```

## Conversion Rules

### BOM Conversion

| KiCad Field | JLCPCB Field | Notes |
|-------------|--------------|-------|
| Designation | Comment | Component value/name |
| Designator | Designator | Multiple refs comma-separated, sort alphanumerically |
| Footprint | Footprint | Keep as-is |
| (none) | JLCPCB Part # | Must be added - use scripts or `jlcpcb-component-finder` skill |

**Key transformations:**

- Designators are sorted alphanumerically (C1, C2, C10, R1, R2, etc.)
- Test points (TP*) can be auto-filtered
- Mounting holes (H*, MH*) can be excluded

### CPL Conversion

| KiCad Field | JLCPCB Field | Transformation |
|-------------|--------------|----------------|
| Ref | Designator | Keep as-is |
| PosX | Mid X | Add "mm" suffix |
| PosY | Mid Y | **Negate the value** (KiCad uses negative Y), add "mm" suffix |
| Side | Layer | Capitalize ("top" → "Top", "bottom" → "Bottom") |
| Rot | Rotation | Normalize to 0-360 (add 360 if negative) |

**Critical transformation:** Y-coordinates must be negated because KiCad and JLCPCB use different coordinate systems.

## Workflow

### Step 1: Export from KiCad

**BOM:**

1. Open schematic in KiCad
2. Tools → Generate BOM
3. Select CSV format with semicolon delimiter
4. Export as `bom.csv`

**Position Files:**

1. Open PCB layout in KiCad
2. File → Fabrication Outputs → Component Placement (.pos)
3. Export `top.pos` and `bottom.pos` (or just one side)

### Step 2: Convert Files

Use the bundled script:

```bash
python3 $HOME/.claude/skills/jlcpcb-bom-generate-from-kicad/scripts/convert_to_jlcpcb.py \
  dist/kicad-bom-outputs/bom.csv \
  dist/kicad-placement-outputs/top.pos \
  dist/kicad-placement-outputs/bottom.pos \
  dist/jlcpcb-ready/
```

Output:

- `dist/jlcpcb-ready/jlcpcb-bom.csv` - BOM (without LCSC numbers)
- `dist/jlcpcb-ready/jlcpcb-cpl.csv` - CPL (ready to upload)

### Step 3: Add LCSC Part Numbers

**Option A: Interactive Mode** (good for small projects)

```bash
python3 $HOME/.claude/skills/jlcpcb-bom-generate-from-kicad/scripts/add_lcsc_numbers.py \
  dist/jlcpcb-ready/jlcpcb-bom.csv \
  --interactive \
  --output dist/jlcpcb-ready/jlcpcb-bom-with-lcsc.csv
```

**Option B: Mapping File** (good for reusable projects)

```bash
# 1. Create mapping template
python3 $HOME/.claude/skills/jlcpcb-bom-generate-from-kicad/scripts/create_parts_mapping.py \
  --output parts_mapping.json

# 2. Edit parts_mapping.json to add your LCSC numbers
# {
#   "LM7805ABD2T-TR": "C86206",
#   "10k": "C25804",
#   ...
# }

# 3. Apply mapping
python3 $HOME/.claude/skills/jlcpcb-bom-generate-from-kicad/scripts/add_lcsc_numbers.py \
  dist/jlcpcb-ready/jlcpcb-bom.csv \
  --map parts_mapping.json \
  --filter-test-points \
  --output dist/jlcpcb-ready/jlcpcb-bom-with-lcsc.csv
```

**Option C: Use jlcpcb-component-finder skill**
For unknown parts, use the companion skill to search JLCPCB database:

```
User: "Find LCSC part for LM7805 TO-263 package"
Claude: [Uses jlcpcb-component-finder skill]
```

### Step 4: Upload to JLCPCB

1. Go to https://jlcpcb.com/quote
2. Upload Gerber files
3. Enable "SMT Assembly"
4. Upload:
- BOM: `jlcpcb-bom-with-lcsc.csv`
- CPL: `jlcpcb-cpl.csv`
5. Review component matching
6. Verify placements in viewer
7. Checkout!

## Filtering Components

Components typically excluded from JLCPCB PCBA:

- Test points (TP*)
- Mounting holes (H*, MH*)
- THT connectors (unless specifically supported)
- Components you want to solder manually

The `add_lcsc_numbers.py` script includes `--filter-test-points` flag to auto-exclude:

- Designators starting with TP, H, MH
- Comments like "GND", "+5V", "+12V" (test point labels)

## Real-World Example

From the zudo-power-usb-pd project:

```bash
# 1. Convert KiCad exports
python3 convert_to_jlcpcb.py \
  zudo-pd.csv \
  zudo-pd-top.pos \
  zudo-pd-bottom.pos \
  jlcpcb-ready/

# Output:
# ✅ Converted BOM saved to: jlcpcb-ready/jlcpcb-bom.csv
#    Total components: 43
# ✅ Converted CPL saved to: jlcpcb-ready/jlcpcb-cpl.csv
#    Total components: 72

# 2. Add LCSC numbers from project BOM documentation
python3 add_lcsc_numbers.py \
  jlcpcb-ready/jlcpcb-bom.csv \
  --map parts_mapping.json \
  --filter-test-points \
  --output jlcpcb-ready/jlcpcb-bom-with-lcsc.csv

# Output:
# ✅ Updated BOM saved to: jlcpcb-ready/jlcpcb-bom-with-lcsc.csv
#    Total components: 38
#    With LCSC part #: 38
#    Missing part #: 0

# 3. Ready for JLCPCB upload!
```

## Troubleshooting

### BOM Upload Fails

- Check CSV format (no special characters in designators)
- Verify LCSC part numbers are valid (all start with 'C')
- Ensure all required fields are present

### CPL Upload Fails

- Verify coordinate format (must include "mm" suffix)
- Check rotation values (must be 0-360)
- Ensure Layer field is "Top" or "Bottom" (capitalized)

### Components Don't Match

- Some LCSC parts may be out of stock temporarily
- Check JLCPCB's suggested alternatives
- Use `jlcpcb-component-finder` skill to find replacements

### Wrong Coordinate System

If components appear in wrong locations:

- Verify Y-coordinates were negated (script does this automatically)
- Check KiCad board origin settings
- Ensure Gerber and CPL use same origin

## Notes

- JLCPCB may adjust placement coordinates based on their manufacturing process
- Board origin in KiCad affects coordinates - use "Drill/Place file origin" for consistency
- Some footprints may need renaming to match JLCPCB's library conventions
- Always verify the first assembly order carefully

## Integration with Other Skills

This skill works well with:

- **jlcpcb-component-finder**: Search JLCPCB database for LCSC part numbers
- **easyeda2kicad**: Download footprints/symbols for JLCPCB parts

Example workflow:

```
1. Use easyeda2kicad to download footprints from LCSC
2. Design PCB in KiCad
3. Use THIS skill to convert BOM/CPL
4. Use jlcpcb-component-finder to find missing LCSC numbers
5. Upload to JLCPCB for assembly
```