Skip to content

project-structure.md

Latest commit

 

History

History
519 lines (399 loc) · 11.5 KB

project-structure.md

File metadata and controls

519 lines (399 loc) · 11.5 KB

Project Structure and File Organization

This guide explains how to organize CodeYourPCB projects, understand the different file types, and follow best practices for version control.

Overview

CodeYourPCB projects revolve around .cypcb files as the single source of truth. All other files (exports, routing data, manufacturing outputs) are generated artifacts that can be reproduced from the source file.

File Types

.cypcb Files (Source Files)

Purpose: The authoritative design specification

Contains:

  • Board dimensions and layer count
  • Component placement and values
  • Net definitions and constraints
  • Optional: manual traces, zones, custom footprints

Example: my_board.cypcb

Characteristics:

  • Plain text (UTF-8)
  • Human-readable and AI-editable
  • Version control friendly (meaningful diffs)
  • Can regenerate all other files from this

.dsn Files (Specctra DSN)

Purpose: Industry-standard design format for autorouters

Contains:

  • Board outline
  • Component placement
  • Net connectivity (ratsnest)
  • Design rules (clearances, trace widths)

Generated by: CodeYourPCB export command or desktop app Used by: FreeRouting, commercial autorouters Example: my_board.dsn

Characteristics:

  • S-expression format (Lisp-like)
  • Compatible with KiCad and other EDA tools
  • Intermediate format (not for manufacturing)

.ses Files (Specctra Session)

Purpose: Routing solution from autorouter

Contains:

  • All routed traces
  • Via placements
  • Autorouter metadata

Generated by: FreeRouting or other autorouters Imported by: CodeYourPCB to visualize routed board Example: my_board.ses

Characteristics:

  • S-expression format
  • Contains complete routing solution
  • Not committed to version control (can be regenerated)

.routes Files (CodeYourPCB Routes)

Purpose: Simplified route representation

Contains:

  • Trace paths in CodeYourPCB format
  • Can be merged back into .cypcb as locked traces

Generated by: Route import command Example: my_board.routes

Characteristics:

  • CodeYourPCB DSL syntax
  • Human-readable
  • Can be edited and copy-pasted into .cypcb files

Gerber Files (.gbr, .drl, etc.)

Purpose: Manufacturing output for PCB fabrication

Contains:

  • Copper layers (*.Cu.gbr)
  • Soldermask layers (*.Mask.gbr)
  • Silkscreen layers (*.SilkS.gbr)
  • Drill files (*.drl)
  • Edge cuts (*.Edge_Cuts.gbr)

Generated by: CodeYourPCB export command Used by: PCB manufacturers Location: Usually in gerbers/ or output/ directory

Characteristics:

  • Industry-standard RS-274X format
  • Binary-ish (not human-readable)
  • Commit to version control for reproducibility

Single-File Projects (Simple)

For simple designs, a single .cypcb file is sufficient:

my_project/
├── my_board.cypcb          # Source design
└── README.md               # Optional documentation

Workflow:

  1. Create and edit my_board.cypcb
  2. View in web app or desktop app
  3. Export Gerbers when ready for manufacturing

Best for:

  • Prototypes
  • Simple 2-layer boards
  • Learning projects
  • Quick iterations

Multi-File Projects (Production)

For production designs, organize files by purpose:

my_project/
├── design/
│   ├── my_board.cypcb      # Source design
│   └── my_board_v2.cypcb   # Design iterations
├── routing/
│   ├── my_board.dsn        # Specctra design
│   ├── my_board.ses        # Routing solution
│   └── my_board.routes     # Imported routes
├── output/
│   ├── gerbers/
│   │   ├── my_board-F.Cu.gbr
│   │   ├── my_board-B.Cu.gbr
│   │   ├── my_board-F.Mask.gbr
│   │   ├── my_board-B.Mask.gbr
│   │   ├── my_board-F.SilkS.gbr
│   │   ├── my_board-B.SilkS.gbr
│   │   ├── my_board-Edge_Cuts.gbr
│   │   └── my_board-PTH.drl
│   └── bom.csv             # Bill of materials
├── docs/
│   ├── schematic.pdf       # Optional schematic
│   └── assembly.md         # Assembly instructions
└── README.md

Workflow:

  1. Design in design/my_board.cypcb
  2. Export DSN to routing/my_board.dsn
  3. Autoroute with FreeRouting → routing/my_board.ses
  4. Import routes back to .cypcb or review .routes file
  5. Export Gerbers to output/gerbers/
  6. Commit significant versions to git

Best for:

  • Production designs
  • Team collaboration
  • Multiple design iterations
  • Manufacturing documentation

Version Control Best Practices

What to Commit

Always commit:

  • .cypcb source files (primary design artifact)
  • README.md and documentation
  • Final Gerber files (reproducibility)
  • BOM and assembly instructions

Optional to commit:

  • .dsn files (useful for collaboration)
  • .routes files (useful for review)

Never commit:

  • .ses files (regenerated from .dsn)
  • Temporary files (editor backups, OS files)
  • Large binary dependencies

Example .gitignore

# Autorouter session files (regenerate from .dsn)
*.ses

# Build artifacts
.cache/
.temp/

# Editor files
*.swp
*.swo
*~
.vscode/
.idea/

# OS files
.DS_Store
Thumbs.db

# Optional: ignore routing directory (if not collaborating on routes)
# routing/

Git Workflow

Feature branch workflow:

git checkout -b feature/add-usb-connector
# Edit my_board.cypcb
git add design/my_board.cypcb
git commit -m "feat: add USB-C connector for power input"
git push origin feature/add-usb-connector
# Create pull request

Version tagging:

git tag -a v1.0 -m "First production version"
git push --tags

Viewing changes:

git diff design/my_board.cypcb

Because .cypcb files are plain text, git diffs show exactly what changed:

+ component J1 connector "USB-C" {
+     at 5mm, 10mm
+ }

+ net VBUS {
+     J1.VBUS
+     U1.VIN
+ }

Design Iterations

Approach 1: Overwrite in Place

For rapid iterations, keep overwriting the same file:

my_project/
├── my_board.cypcb          # Current version
└── README.md

Pros:

  • Simple
  • Git history tracks all changes

Cons:

  • Can't easily compare old versions side-by-side
  • Git history required to retrieve old designs

Best for:

  • Early prototyping
  • Solo projects
  • When git history is sufficient

Approach 2: Versioned Files

For major revisions, create separate files:

my_project/
├── design/
│   ├── my_board_v1.cypcb   # Production version 1
│   ├── my_board_v2.cypcb   # Production version 2
│   └── my_board_v3.cypcb   # Current development
└── README.md

Pros:

  • Easy side-by-side comparison
  • Clear production versions
  • Can maintain multiple variants

Cons:

  • More files to manage
  • Need to track which is current

Best for:

  • Production designs with major revisions
  • Multiple board variants
  • Team collaboration

Approach 3: Git Branches

Use git branches for design alternatives:

git checkout -b variant/high-power
# Modify my_board.cypcb for high-power variant
git commit -m "variant: increase trace widths for 5A operation"

git checkout main
git checkout -b variant/low-cost
# Modify my_board.cypcb for cost-optimized variant
git commit -m "variant: replace high-end components with generic parts"

Pros:

  • Git handles version management
  • Easy to merge improvements across variants
  • Branch names document intent

Cons:

  • Requires git proficiency
  • Can't view multiple variants simultaneously in viewer

Best for:

  • Maintaining product variants
  • Experimental features
  • Team collaboration with code review

Multi-Board Projects

For projects with multiple boards:

my_product/
├── mainboard/
│   ├── mainboard.cypcb
│   └── output/
├── sensor_module/
│   ├── sensor.cypcb
│   └── output/
├── power_board/
│   ├── power.cypcb
│   └── output/
└── README.md

Each board has its own subdirectory with independent design files.

Collaborative Workflows

Code Review with Pull Requests

  1. Create feature branch
  2. Modify .cypcb file
  3. Create pull request
  4. Reviewers see text diff of changes
  5. Merge after approval

Example review comment:

In my_board.cypcb line 45:

> net VCC [current 500mA] {

This net should probably have width constraint:
net VCC [current 500mA width 0.4mm] {

Shared Library Setup

Team members share component library configuration:

my_project/
├── design/
│   └── my_board.cypcb
├── libraries/
│   ├── kicad/             # Shared KiCad libraries
│   └── custom/            # Team-specific footprints
└── .library-config.json   # Library paths

All team members configure LibraryManager to point to the shared libraries/ directory.

Naming Conventions

File Naming

Good:

  • mainboard.cypcb - Descriptive, lowercase
  • sensor_v2.cypcb - Version indicator
  • psu_12v.cypcb - Function indicator

Avoid:

  • Board 1.cypcb - Spaces and generic names
  • FINAL-FINAL-v3.cypcb - Redundant version markers
  • test.cypcb - Too generic

Component Reference Designators

Follow electronics conventions:

  • R1, R2 - Resistors
  • C1, C2 - Capacitors
  • U1, U2 - Integrated circuits
  • LED1, LED2 - LEDs
  • J1, J2 - Connectors
  • Q1, Q2 - Transistors
  • D1, D2 - Diodes

Net Names

Good:

  • VCC, GND - Standard power rails
  • USB_DP, USB_DN - Descriptive signal names
  • LED_ANODE - Clear function

Avoid:

  • net1, net2 - Generic names
  • Pin5 - Not descriptive
  • ThingConnectedToR1 - Too verbose

Directory Structure Recommendations

Small Projects (<5 components)

project/
└── my_board.cypcb

Medium Projects (5-50 components)

project/
├── my_board.cypcb
├── output/
│   └── gerbers/
└── README.md

Large Projects (>50 components)

project/
├── design/
│   └── *.cypcb
├── routing/
│   ├── *.dsn
│   └── *.routes
├── output/
│   ├── gerbers/
│   └── bom.csv
├── docs/
│   └── *.md
└── README.md

Multi-Board Products

product/
├── mainboard/
│   ├── design/
│   ├── output/
│   └── README.md
├── modules/
│   ├── sensor/
│   ├── power/
│   └── io/
├── libraries/
│   └── custom/
└── README.md

Export and Manufacturing

Gerber Export Location

Generate Gerbers in a dedicated output directory:

cypcb export my_board.cypcb --output output/gerbers/

Creates:

output/
└── gerbers/
    ├── my_board-F.Cu.gbr
    ├── my_board-B.Cu.gbr
    ├── my_board-F.Mask.gbr
    ├── my_board-B.Mask.gbr
    ├── my_board-F.SilkS.gbr
    ├── my_board-B.SilkS.gbr
    ├── my_board-Edge_Cuts.gbr
    └── my_board-PTH.drl

Archiving for Manufacturer

Create a zip file with Gerbers and documentation:

cd output/gerbers/
zip my_board_gerbers.zip *.gbr *.drl

Send my_board_gerbers.zip to PCB manufacturer.

Summary

Single source of truth: .cypcb file is authoritative Generated artifacts: .dsn, .ses, Gerbers are reproducible Version control: Commit .cypcb and final Gerbers Organization: Scale structure with project complexity Collaboration: Text-based diffs enable code review workflows

For more information: