Les Plans de l'Artificier

Git pour le hardware, KiCad et l'électronique

Le défi des fichiers binaires

Quand tu travailles avec du code source, Git excelle : chaque fichier est du texte, et Git peut calculer les différences ligne par ligne. Mais dans le monde du hardware et de l'électronique, la majorité des fichiers sont binaires :

• Schémas électroniques (.kicad_sch, .sch) - circuits et composants
• Circuits imprimés (.kicad_pcb, .brd) - le routage physique
• Modèles 3D (.step, .stl, .FCStd) - les boîtiers et pièces mécaniques
• Fichiers de fabrication (.gbr, .drl) - les Gerbers pour l'usine

Le problème fondamental : quand tu fais git diff sur un fichier binaire, Git te répond simplement Binary files differ. Impossible de savoir ce qui a changé.

# Sur un fichier texte, git diff montre les changements :
git diff main.py
# -  print("Hello")
# +  print("Bonjour")

# Sur un fichier binaire, git diff est muet :
git diff carte.kicad_pcb
# Binary files a/carte.kicad_pcb and b/carte.kicad_pcb differ

De plus, chaque modification d'un fichier binaire crée une copie complète dans l'historique Git. Un PCB de 5 Mo modifié 20 fois = 100 Mo d'historique. Le dépôt grossit vite.

KiCad + Git - le duo gagnant

KiCad est un logiciel libre de conception électronique (EDA). Sa grande force pour le versionnement : la plupart de ses fichiers sont en format texte (S-expressions), ce qui rend les diffs possibles.

Structure d'un projet KiCad

mon-projet-kicad/
├── mon-projet.kicad_pro     # Fichier projet (texte, JSON)
├── mon-projet.kicad_sch     # Schéma électronique (texte, S-expr)
├── mon-projet.kicad_pcb     # Circuit imprimé (texte, S-expr)
├── sym-lib-table             # Table des bibliothèques de symboles
├── fp-lib-table              # Table des bibliothèques d'empreintes
├── mon-projet.kicad_prl     # Préférences locales (NE PAS VERSIONNER)
├── fp-info-cache             # Cache d'empreintes (NE PAS VERSIONNER)
└── production/               # Fichiers de fabrication générés
    ├── gerbers/
    └── bom/

Bonne nouvelle : les fichiers .kicad_sch et .kicad_pcb sont du texte structuré. Git peut calculer des diffs, même si la lecture n'est pas toujours intuitive.

Le .gitignore KiCad complet

# .gitignore pour projet KiCad

# Fichiers de sauvegarde
*.kicad_sch-bak
*.kicad_pcb-bak
*-backups/
_autosave-*

# Préférences locales (propres à chaque poste)
*.kicad_prl

# Cache
fp-info-cache

# Netliste (générée, pas source)
*.net

# Fichiers de verrouillage
*.lck

# Dossier de fabrication (généré, versionner séparément si besoin)
# production/gerbers/
# production/bom/

# Fichiers 3D générés
*.wrl

# Divers
*~
\#*\#

Bonnes pratiques de commit KiCad

Comme les fichiers KiCad sont du texte, chaque sauvegarde dans KiCad peut modifier de nombreuses lignes (positions, identifiants internes). Pour garder un historique lisible :

• Un commit par changement logique : "Ajout du régulateur de tension 3.3V", pas "Modifications diverses"
• Séparer schéma et PCB : d'abord le schéma, puis le routage
• Ne pas commiter après chaque sauvegarde : attends d'avoir un état cohérent

Diff visuel pour les schémas

Même si les fichiers KiCad sont en texte, lire un diff de S-expressions n'est pas très parlant. C'est là qu'interviennent les outils de diff visuel : ils génèrent des images de chaque version et les comparent visuellement.

kidiff

kidiff est l'outil le plus populaire. Il génère des images PNG de chaque version du schéma ou du PCB, puis les affiche côte à côte dans un navigateur web.

# Installation
pip install kidiff

# Comparer le schéma entre deux commits
kidiff mon-projet.kicad_sch HEAD~1 HEAD

# Comparer le PCB entre une branche et main
kidiff mon-projet.kicad_pcb main feature-regulateur

# Comparer avec le répertoire de travail (modifications non commitées)
kidiff mon-projet.kicad_sch HEAD

plotgitsch (KiCad 5 et antérieur)

Pour les projets plus anciens utilisant KiCad 5, plotgitsch offre une fonctionnalité similaire :

# Installation (nécessite OCaml)
opam install plotgitsch

# Comparer entre deux commits
plotgitsch -ik mon-projet.sch HEAD~3 HEAD

kicad-diff

kicad-diff est un autre outil qui s'intègre directement dans Git comme outil de diff externe :

# Configuration dans .gitconfig
git config --global diff.kicad.command kicad-diff

# Puis dans .gitattributes du projet
# *.kicad_sch diff=kicad
# *.kicad_pcb diff=kicad

# Ensuite, git diff utilise automatiquement le diff visuel
git diff mon-projet.kicad_sch

Fichiers Gerber et BOM

Les fichiers de production sont ceux que tu envoies au fabricant de PCB. La question se pose : faut-il les versionner ?

Les fichiers Gerber

Les Gerbers (.gbr, .drl) sont les fichiers de fabrication du circuit imprimé. Chaque couche du PCB (cuivre, masque de soudure, sérigraphie, perçages) a son propre fichier.

• Avantage de les versionner : tu sais exactement quels Gerbers ont été envoyés pour chaque version du PCB
• Inconvénient : ils sont générés à partir du PCB, donc c'est de la donnée dérivée

La bonne pratique : générer les Gerbers lors d'une release et les attacher comme artefacts de la release Git, plutôt que de les commiter dans l'historique.

La BOM (Bill of Materials)

La BOM est la liste des composants nécessaires. En KiCad, tu peux l'exporter en CSV - un format texte parfait pour le versionnement.

# Exemple de BOM en CSV (versionnée dans Git)
# Reference, Value, Footprint, Quantity
# R1, 10k, 0805, 1
# R2, 4.7k, 0805, 1
# C1, 100nF, 0805, 1
# U1, ATmega328P, TQFP-32, 1

# Générer la BOM depuis KiCad CLI
kicad-cli sch export bom mon-projet.kicad_sch -o production/bom/bom.csv

CAD mécanique et Git

Le hardware ne se limite pas à l'électronique. Les boîtiers, les pièces mécaniques, les assemblages - tout cela doit aussi être versionné.

FreeCAD (.FCStd = archive ZIP)

FreeCAD est un logiciel libre de CAO 3D. Son format natif .FCStd est en réalité une archive ZIP contenant des fichiers XML. Git le traite comme un binaire, mais il existe des astuces :

# Un fichier .FCStd est un ZIP
unzip -l boitier.FCStd
# Archive:  boitier.FCStd
#   Length      Date    Time    Name
# ---------  ---------- -----   ----
#     12543  2026-03-09 14:30   Document.xml
#      2341  2026-03-09 14:30   GuiDocument.xml
#      8923  2026-03-09 14:30   Brep/Part__Feature.brp

# Astuce : utiliser un filtre Git pour extraire le XML
# .gitattributes
# *.FCStd diff=fcstd

# .gitconfig
# [diff "fcstd"]
#   textconv = unzip -p -c Document.xml

OpenSCAD (.scad = texte pur)

OpenSCAD est le rêve du versionneur : les fichiers .scad sont du code source pur. Tu décris ta pièce 3D avec du code, et Git gère les diffs parfaitement.

# Exemple OpenSCAD - boîtier pour un PCB
// boitier.scad - Boîtier pour carte électronique v1.2

pcb_largeur = 50;
pcb_longueur = 80;
pcb_epaisseur = 1.6;
marge = 2;  // Jeu autour du PCB
epaisseur_paroi = 2;

module boitier_bas() {
    difference() {
        // Extérieur
        cube([pcb_largeur + 2*marge + 2*epaisseur_paroi,
              pcb_longueur + 2*marge + 2*epaisseur_paroi,
              15]);
        // Intérieur (creux)
        translate([epaisseur_paroi, epaisseur_paroi, epaisseur_paroi])
            cube([pcb_largeur + 2*marge,
                  pcb_longueur + 2*marge,
                  15]);
    }
}

boitier_bas();

Avec OpenSCAD, un git diff te montre exactement ce qui a changé : « la marge est passée de 2 mm à 3 mm ». Limpide.

Fusion 360 et les outils cloud

Fusion 360 (Autodesk) stocke les fichiers dans le cloud. Le versionnement est géré par la plateforme elle-même, pas par Git. Si tu utilises Fusion 360 :

• Exporte régulièrement en STEP (.step) pour archiver dans Git
• Le STEP est un standard ouvert, lisible par tous les logiciels CAO
• Versionne les exports STEP comme « instantanés » de référence

Organisation d'un repo hardware

Un projet hardware bien organisé dans Git suit une structure claire qui sépare les sources, le firmware, la documentation et les fichiers de production :

mon-projet-hw/
├── hw/                          # Tout ce qui est hardware
│   ├── electronics/             # Conception électronique
│   │   ├── mon-projet.kicad_pro
│   │   ├── mon-projet.kicad_sch
│   │   ├── mon-projet.kicad_pcb
│   │   ├── sym-lib-table
│   │   ├── fp-lib-table
│   │   └── libs/                # Bibliothèques custom
│   │       ├── symbols/
│   │       └── footprints/
│   └── mechanical/              # Pièces mécaniques
│       ├── boitier.scad         # ou .FCStd
│       └── exports/             # STEP, STL exportés
│           ├── boitier-v1.step
│           └── boitier-v1.stl
├── firmware/                    # Code embarqué
│   ├── src/
│   ├── include/
│   └── platformio.ini           # ou Makefile, CMakeLists.txt
├── docs/                        # Documentation
│   ├── architecture.md
│   ├── pinout.md
│   └── images/
├── production/                  # Fichiers de fabrication
│   ├── gerbers/
│   ├── bom/
│   │   └── bom.csv
│   └── pick-and-place/
├── .gitignore
├── LICENSE
├── CHANGELOG.md
└── README.md

Gestion des releases hardware

En logiciel, une release est une version du code. En hardware, une release correspond à une version physique du PCB - une fois fabriqué, tu ne peux plus le modifier avec un simple commit.

Convention de tags pour le hardware

Les tags Git sont parfaits pour marquer les versions de PCB :

# Première version du PCB envoyée en fabrication
git tag -a v1.0-rev-a -m "PCB v1.0 Rev A - Premier prototype"

# Correction de bugs (piste manquante, valeur de résistance)
git tag -a v1.1-rev-b -m "PCB v1.1 Rev B - Correction alimentation"

# Changement majeur (nouveau microcontrôleur, refonte du layout)
git tag -a v2.0-rev-a -m "PCB v2.0 Rev A - Migration vers STM32"

La convention vX.Y-rev-Z est courante dans l'industrie :

• X (majeur) : changement d'architecture, nouveau composant principal
• Y (mineur) : correction de bugs, ajustement de valeurs
• rev-Z (révision) : lettre de révision du PCB (a, b, c...)

Fichiers de fabrication dans les releases

Plutôt que de commiter les Gerbers dans l'historique, attache-les aux releases :

# Générer les Gerbers
kicad-cli pcb export gerbers mon-projet.kicad_pcb -o production/gerbers/

# Générer les fichiers de perçage
kicad-cli pcb export drill mon-projet.kicad_pcb -o production/gerbers/

# Créer une archive de fabrication
cd production/gerbers/
zip ../../mon-projet-v1.0-rev-a-gerbers.zip *.gbr *.drl
cd ../..

# Créer le tag et la release
git tag -a v1.0-rev-a -m "PCB v1.0 Rev A"
git push origin v1.0-rev-a

# Sur GitHub, créer une release et y attacher le ZIP des Gerbers
gh release create v1.0-rev-a mon-projet-v1.0-rev-a-gerbers.zip \
  --title "PCB v1.0 Rev A - Premier prototype" \
  --notes "Première version du PCB envoyée en fabrication."

Changelog hardware

Un CHANGELOG.md est encore plus important en hardware qu'en logiciel - tu dois savoir exactement ce qui a changé entre deux révisions physiques :

# CHANGELOG.md

## [v1.1-rev-b] - 2026-03-15
### Corrigé
- Résistance R12 : 10k -> 4.7k (diviseur de tension incorrect)
- Piste manquante entre U3 pin 7 et C15
- Empreinte de J2 corrigée (pitch 2.0mm au lieu de 2.54mm)

### Ajouté
- LED de diagnostic D4 sur GPIO PA5
- Point de test TP3 sur rail 3.3V

## [v1.0-rev-a] - 2026-03-01
### Version initiale
- Microcontrôleur STM32F103
- Alimentation 5V USB + régulateur 3.3V
- 4 entrées analogiques, 2 sorties PWM

Bonnes pratiques - récapitulatif

Exercice pratique - Initialiser un repo hardware

Étape 1 - Créer la structure

# Créer le dépôt
mkdir capteur-temperature
cd capteur-temperature
git init -b main

# Créer l'arborescence hardware
mkdir -p hw/electronics/libs/symbols
mkdir -p hw/electronics/libs/footprints
mkdir -p hw/mechanical/exports
mkdir -p firmware/src
mkdir -p firmware/include
mkdir -p docs/images
mkdir -p production/gerbers
mkdir -p production/bom
mkdir -p production/pick-and-place

Étape 2 - Le .gitignore

# Créer le .gitignore
cat > .gitignore << 'EOF'
# KiCad
*.kicad_sch-bak
*.kicad_pcb-bak
*-backups/
_autosave-*
*.kicad_prl
fp-info-cache
*.net
*.lck
*.wrl
*~
\#*\#

# Firmware (PlatformIO)
.pio/
.vscode/

# OS
.DS_Store
Thumbs.db
EOF

git add .gitignore
git commit -m "Ajout du .gitignore KiCad + firmware"

Étape 3 - README et CHANGELOG

# Créer le README
cat > README.md << 'EOF'
# Capteur de température

Carte électronique pour capteur de température DS18B20.

## Structure
- hw/ - Conception électronique et mécanique
- firmware/ - Code embarqué (PlatformIO)
- docs/ - Documentation
- production/ - Fichiers de fabrication
EOF

# Créer le CHANGELOG
cat > CHANGELOG.md << 'EOF'
# Changelog

## [v1.0-rev-a] - 2026-03-09
### Version initiale
- Schéma : MCU + capteur DS18B20 + USB
- PCB : carte 40x30mm, 2 couches
EOF

git add README.md CHANGELOG.md
git commit -m "Ajout README et CHANGELOG"

Étape 4 - Simuler des fichiers sources

# Simuler un fichier schéma (un vrai serait généré par KiCad)
cat > hw/electronics/capteur.kicad_sch << 'EOF'
(kicad_sch (version 20230121) (generator eeschema)
  (uuid "exemple-uuid-schema")
  (paper "A4")
  (title_block (title "Capteur Temperature") (rev "A"))
)
EOF

git add hw/
git commit -m "Ajout du schéma électronique - capteur DS18B20"

# Simuler un fichier PCB
cat > hw/electronics/capteur.kicad_pcb << 'EOF'
(kicad_pcb (version 20221018) (generator pcbnew)
  (general (thickness 1.6))
  (paper "A4")
  (layers (0 "F.Cu" signal) (31 "B.Cu" signal))
)
EOF

git add hw/electronics/capteur.kicad_pcb
git commit -m "Routage PCB - carte 2 couches 40x30mm"

Étape 5 - Marquer la version

# Créer le tag de release hardware
git tag -a v1.0-rev-a -m "PCB v1.0 Rev A - Premier prototype capteur température"

# Vérifier
git log --oneline --decorate
# abc1234 (HEAD -> main, tag: v1.0-rev-a) Routage PCB - carte 2 couches 40x30mm
# def5678 Ajout du schéma électronique - capteur DS18B20
# ghi9012 Ajout README et CHANGELOG
# jkl3456 Ajout du .gitignore KiCad + firmware

Récapitulatif des concepts