# JLCPCB Basic Parts Generator

This guide describes how to use the automated symbol generation for JLCPCB Basic Parts.

## 🎯 Purpose

The generator creates KiCad symbol libraries with proper **Fabrication Toolkit** properties for seamless JLCPCB assembly integration. All symbols use standard KiCad footprints - no custom footprints needed!

## 📋 Compatible with Fabrication Toolkit

The generated symbols include all properties required by [bennymeg/JLC-Plugin-for-KiCad](https://github.com/bennymeg/JLC-Plugin-for-KiCad):

- `LCSC Part #` - For automatic part matching
- `Manufacturer` - Component manufacturer  
- `MFG Part #` - Manufacturer part number
- `FT Rotation Offset` - Pick-and-place rotation correction
- Standard KiCad footprint references

## 🗂️ Input Database

The database `docs/JLCPCB_Basic_Parts.csv` contains:
- **Resistors**: UniOhm Basic Parts (0603 preferred)
- **Capacitors**: Samsung Basic Parts (0603, 0805)
- **Inductors**: Murata Basic Parts (0603, 0805)
- **ICs**: STM32, CAN, Power, Interface ICs
- **Components**: LEDs, Diodes, Crystals

All parts are JLCPCB Basic Parts for lowest assembly cost.

## ⚙️ Usage

### Windows PowerShell
```powershell
# Generate all libraries and reports
.\scripts\Generate_JLCPCB_Symbols.ps1 -CsvPath ".\docs\JLCPCB_Basic_Parts.csv" -OutputPath "."

# Dry run (preview only)
.\scripts\Generate_JLCPCB_Symbols.ps1 -CsvPath ".\docs\JLCPCB_Basic_Parts.csv" -OutputPath "." -DryRun
```

### Linux/macOS Bash
```bash
# Generate all libraries and reports  
./scripts/generate_jlcpcb_symbols.sh -c ./docs/JLCPCB_Basic_Parts.csv -o .

# Dry run (preview only)
./scripts/generate_jlcpcb_symbols.sh -c ./docs/JLCPCB_Basic_Parts.csv -o . --dry-run

# Skip symbol generation, only generate reports
./scripts/generate_jlcpcb_symbols.sh -c ./docs/JLCPCB_Basic_Parts.csv -o . --skip-symbols
```

## 📤 Output

### Symbol Libraries
- `symbols/Standard_Passives.kicad_sym` - Resistors, Capacitors, Inductors
- `symbols/Standard_ICs.kicad_sym` - Microcontrollers, CAN, Power ICs  
- `symbols/Standard_Components.kicad_sym` - LEDs, Diodes, Crystals

### BOM Template
- `docs/JLCPCB_BOM_Template.csv` - Ready for JLCPCB assembly upload

### Reports
- Component statistics by package and manufacturer
- Cost analysis for complete starter kit
- Footprint mapping summary

## 🔧 KiCad Integration

### 1. Add Symbol Libraries
```
KiCad → Preferences → Manage Symbol Libraries → Project Specific Libraries

Add:
- Nickname: Standard_Passives
- Library Path: ${KIPRJMOD}/kicad_libs/my-kicad-libs/symbols/Standard_Passives.kicad_sym

- Nickname: Standard_ICs  
- Library Path: ${KIPRJMOD}/kicad_libs/my-kicad-libs/symbols/Standard_ICs.kicad_sym

- Nickname: Standard_Components
- Library Path: ${KIPRJMOD}/kicad_libs/my-kicad-libs/symbols/Standard_Components.kicad_sym
```

### 2. Use Standard Footprints
No footprint configuration needed - symbols automatically reference standard KiCad footprints:
- Resistors → `Resistor_SMD:R_0603_1608Metric`
- Capacitors → `Capacitor_SMD:C_0603_1608Metric`
- ICs → `Package_SO:SOIC-16_3.9x9.9mm_P1.27mm`

### 3. JLCPCB Assembly Workflow
1. Design schematic using generated symbols
2. Create PCB layout
3. Export BOM with Fabrication Toolkit plugin
4. Upload to JLCPCB with automatic part matching

## 📊 Example Components

### Standard Passives
| Component | Value | Package | LCSC | Footprint |
|-----------|-------|---------|------|-----------|
| Resistor | 10k | 0603 | C25804 | Resistor_SMD:R_0603_1608Metric |
| Capacitor | 100nF | 0603 | C14663 | Capacitor_SMD:C_0603_1608Metric |
| Inductor | 10µH | 0805 | C1046 | Inductor_SMD:L_0805_2012Metric |

### Standard ICs
| Component | Package | LCSC | Footprint |
|-----------|---------|------|-----------|
| STM32F103C8T6 | LQFP-48 | C8734 | Package_QFP:LQFP-48_7x7mm_P0.5mm |
| MCP2515 | SOIC-18 | C55199 | Package_SO:SOIC-18W_7.5x11.6mm_P1.27mm |
| AMS1117-3.3 | SOT-223 | C6186 | Package_TO_SOT_SMD:SOT-223-3_TabPin2 |

## 🔄 Updating the Database

### Adding New Parts
1. Edit `docs/JLCPCB_Basic_Parts.csv`
2. Add new line with format: `Component,Value,Package,LCSC Part #,Manufacturer,MFG Part #,Description,FT Rotation Offset,Stock Status,Price 1k,Last Update`
3. Run generator script
4. Test symbols in KiCad

### Verifying LCSC Numbers
- Check [lcsc.com](https://lcsc.com) for current availability
- Prefer "Basic Parts" (marked with green "Basic" label)
- Verify pricing and stock status

## ⚠️ Important Notes

### Rotation Offsets
- Most components: `0` (no rotation needed)
- SOT-223 regulators: `180` (common requirement)
- Check actual assembly if rotation issues occur

### Symbol Limitations
- ICs use generic rectangular symbols
- Actual pinout must be defined manually for complex ICs
- Passives are ready-to-use with correct pin assignments

### Cost Optimization
- All parts are JLCPCB Basic Parts
- Complete kit cost: ~$50 for 1000 pieces each
- Setup fee applies for each unique part (~$3)
- Minimize unique parts to reduce cost

## 🛠️ Customization

### Adding New Component Types
1. Add entries to CSV database
2. Update `get_kicad_footprint()` function in scripts
3. Add symbol graphics in `get_symbol_graphics()`
4. Test generation

### Custom Footprints
If standard KiCad footprints don't fit:
1. Create custom footprint in your library
2. Update footprint mapping in script
3. Ensure 3D model compatibility

---

*Compatible with KiCad 7.0+ and Fabrication Toolkit plugin*