# KiCad 9 Project Template Guide

This document provides a comprehensive guide for using this KiCad 9 project template effectively.

## 🚀 Getting Started

### 1. Clone or Download Template
```bash
# Option A: Clone the repository
git clone https://git.buildfor.life/grabowski/b4l-project-template.git your-project-name
cd your-project-name

# Option B: Download as ZIP and extract to your desired location
```

### 2. Create Your KiCad Project
1. Open KiCad 9
2. **File → New Project**
3. Navigate to your template directory
4. Create project in the root directory (same level as README.md)
5. Name your project (creates `.kicad_pro`, `.kicad_sch`, `.kicad_pcb` files)

### 3. Configure KiCad Libraries
1. **Preferences → Manage Symbol Libraries**
   - Add path: `${KIPRJMOD}/kicad/libraries/symbols/`
2. **Preferences → Manage Footprint Libraries**
   - Add path: `${KIPRJMOD}/kicad/libraries/footprints/`
3. **Preferences → Configure Paths**
   - Add 3D models path: `${KIPRJMOD}/kicad/libraries/3dmodels/`

## 📁 Directory Structure Overview

```
your-project/
├── your-project.kicad_pro      # Main project file
├── your-project.kicad_sch      # Main schematic
├── your-project.kicad_pcb      # Main PCB layout
├── README.md                   # Project documentation
├── .gitignore                  # Git ignore rules
├── LICENSE                     # Project license
│
├── kicad/                      # KiCad-specific files
│   ├── libraries/              # Custom libraries
│   │   ├── symbols/            # Custom symbols (.kicad_sym)
│   │   ├── footprints/         # Custom footprints (.pretty)
│   │   └── 3dmodels/           # 3D models (.step, .wrl)
│   ├── schematics/             # Hierarchical sheets
│   ├── gerbers/                # Generated Gerbers (review)
│   ├── plots/                  # PDF plots
│   └── backups/                # Auto backups (git ignored)
│
├── hardware/                   # Hardware documentation
│   ├── bom/                    # Bill of Materials
│   ├── datasheets/             # Component datasheets
│   ├── simulations/            # SPICE simulations
│   └── assembly/               # Assembly instructions
│
├── manufacturing/              # Production files
│   ├── gerbers/                # Final production Gerbers
│   ├── drill/                  # Drill files
│   ├── pick-and-place/         # SMT placement files
│   └── assembly/               # Production assembly docs
│
├── docs/                       # Project documentation
│   ├── images/                 # Documentation images
│   ├── datasheets/             # Reference datasheets
│   ├── user-manual/            # End-user documentation
│   └── design-notes/           # Technical design docs
│
├── mechanical/                 # Mechanical design
├── firmware/                   # Embedded code (if applicable)
├── software/                   # PC software and tools
├── tests/                      # Testing procedures
├── tools/                      # Development tools
├── ci/                         # Continuous integration
├── certs/                      # Certifications
└── meta/                       # Project metadata
```

## 🔄 Recommended Workflow

### Phase 1: Design Setup
1. **Requirements**: Document in `docs/design-notes/requirements.md`
2. **Architecture**: Create system overview in `docs/design-notes/architecture.md`
3. **Component Research**: Save datasheets to `docs/datasheets/`

### Phase 2: Schematic Design
1. **Main Schematic**: Design in root `.kicad_sch` file
2. **Hierarchical Sheets**: Store in `kicad/schematics/`
3. **Custom Symbols**: Create in `kicad/libraries/symbols/`
4. **Design Review**: Document in `docs/design-notes/design-reviews/`

### Phase 3: PCB Layout
1. **PCB Design**: Layout in root `.kicad_pcb` file
2. **Custom Footprints**: Create in `kicad/libraries/footprints/`
3. **3D Models**: Add to `kicad/libraries/3dmodels/`
4. **Review Plots**: Generate to `kicad/plots/`

### Phase 4: Documentation
1. **BOM Generation**: Export to `hardware/bom/`
2. **Assembly Drawings**: Create in `hardware/assembly/`
3. **User Manual**: Write in `docs/user-manual/`
4. **Design Notes**: Update technical documentation

### Phase 5: Manufacturing
1. **Final Gerbers**: Generate to `manufacturing/gerbers/`
2. **Drill Files**: Generate to `manufacturing/drill/`
3. **Pick & Place**: Generate to `manufacturing/pick-and-place/`
4. **Package**: Create manufacturer submission package

## 🛠️ KiCad 9 Specific Features

### Project Settings
- Configure design rules in `.kicad_pro` file
- Set up custom library paths using `${KIPRJMOD}` variable
- Configure 3D viewer settings for custom models

### Library Management
- Use relative paths for portability
- Organize libraries by function (MCU, connectors, etc.)
- Version control custom libraries with project

### File Generation
- **Gerbers**: `File → Fabrication Outputs → Gerbers`
- **Drill Files**: Generated with Gerbers
- **Pick & Place**: `File → Fabrication Outputs → Component Placement`
- **BOM**: `Tools → Generate Bill of Materials`

## 📋 Quality Checklist

### Design Review
- [ ] Schematic review completed and documented
- [ ] PCB layout review completed
- [ ] Design rules check (DRC) passed
- [ ] Electrical rules check (ERC) passed
- [ ] 3D visualization reviewed

### Manufacturing Files
- [ ] Gerber files generated and reviewed
- [ ] Drill files generated and verified
- [ ] Pick and place files created (for SMT)
- [ ] BOM exported and verified
- [ ] Assembly drawings created

### Documentation
- [ ] README updated with project specifics
- [ ] Design notes documented
- [ ] User manual created (if applicable)
- [ ] Assembly instructions written
- [ ] Test procedures documented

## 🔧 Git Workflow and File Naming

This template follows **Semantic Versioning 2.0.0** and **Harvard Data Management file naming conventions**. See [FILE-NAMING-AND-VERSIONING.md](FILE-NAMING-AND-VERSIONING.md) for complete details.

### File Naming Standards
- **No spaces**: Use hyphens (-) instead of spaces
- **Date format**: YYYY-MM-DD for chronological sorting
- **Versioning**: Follow semantic versioning (MAJOR.MINOR.PATCH)
- **Structure**: `[project-name]_[component-type]_[description]_[version]_[date].extension`

### Examples
```
my-project_bom_v1.2.0_2024-08-04.csv
my-project_gerbers_v1.0.0_2024-08-04.zip
my-project_user-manual_v1.0.0_2024-08-04.pdf
my-project_housing-main_v2.0.0.sldprt
my-project_symbols_mcu_v1.0.0.kicad_sym
```

### Initial Setup
```bash
# After creating KiCad project
git add .
git commit -m "Initial KiCad project setup v1.0.0"
git tag -a v1.0.0 -m "Initial release - functional prototype"
git remote add origin https://your-git-server.com/username/your-project.git
git push -u origin main
git push --tags
```

### Development Workflow
```bash
# Regular development cycle
git add .
git commit -m "Update component values - v1.0.1"
git tag -a v1.0.1 -m "Bug fix - corrected resistor values"
git push
git push --tags

# For major milestones
git tag -a v2.0.0 -m "Major PCB redesign with new connector layout"
git push --tags
```

### Semantic Versioning Strategy
- **MAJOR**: PCB layout changes, connector changes, mechanical incompatibilities
- **MINOR**: Component changes, new features, firmware updates  
- **PATCH**: Documentation updates, BOM corrections, minor fixes

### Branch Strategy
- `main`: Stable, tested designs
- `develop`: Active development
- `feature/xxx`: Specific features or improvements
- `release/vx.x.x`: Release preparation

## 🎯 Best Practices

### File Organization
- Keep main project files in root directory
- Use consistent naming conventions
- Organize files by function and lifecycle
- Document file purposes in README files

### Version Control
- Commit frequently with descriptive messages
- Tag releases and major milestones
- Use `.gitignore` to exclude temporary files
- Include generated files for important releases

### Documentation
- Update documentation with design changes
- Use clear, descriptive language
- Include diagrams and images where helpful
- Version control all documentation

### Library Management
- Create custom libraries for project-specific components
- Use descriptive names for symbols and footprints
- Include 3D models for visualization
- Document custom component specifications

## 🆘 Troubleshooting

### Common Issues
- **Library not found**: Check library paths in preferences
- **Missing 3D models**: Verify 3D model paths in footprints
- **Gerber generation fails**: Check layer setup and output directory
- **Git conflicts**: Use proper .gitignore for KiCad files

### Getting Help
- KiCad documentation: https://docs.kicad.org/
- KiCad forums: https://forum.kicad.info/
- Build4Life community: https://buildfor.life

## 📞 Support

For template-specific issues:
- Repository: https://git.buildfor.life/grabowski/b4l-project-template
- Issues: Use the repository issue tracker
- Documentation: This file and individual README files

---

**Happy designing with KiCad 9!** 🎉