b4l-project-template/KICAD-PROJECT-TEMPLATE.md

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

# Option A: Clone the repository
git clone https://git.b4l.co.th/B4L/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 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

# 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

# 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! 🎉