grabowski
3f5b4c7e97
- Add FILE-NAMING-AND-VERSIONING.md with complete Semantic Versioning 2.0.0 and Harvard Data Management file naming conventions - Update README.md with file naming standards and semantic versioning workflow - Update KICAD-PROJECT-TEMPLATE.md with comprehensive file naming examples and git workflow - Update hardware/bom/README.md with standardized BOM file naming conventions - Update manufacturing/gerbers/README.md with production-ready Gerber file naming - Update mechanical/stl/README.md with 3D printing file naming including material suffixes - Implement YYYY-MM-DD date format and hyphen-separated naming throughout - Add versioning strategies for hardware, software, and documentation components - Include git tagging strategy and release management guidelines - Provide comprehensive examples for all file types and directories
256 lines
9.1 KiB
Markdown
256 lines
9.1 KiB
Markdown
# 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!** 🎉
|