davlug3/pcb-design-skill

Conception de PCB (KiCad 8/9)

Créez des fichiers PCB KiCad fabriquables et syntaxiquement valides, et exportez-les sous forme de fichiers s-expression .kicad_pcb. KiCad est le framework principal. Ne vous fiez pas à votre mémoire pour le format de fichier — utilisez la documentation développeur KiCad et les ressources fournies, validées et propres, comme source de vérité.

Dialecte cible : KiCad 9 ((version 20241229)). KiCad 8 (20240108) est pris en charge avec les différences listées dans references/pcb-file-format.md#version-dialect-matrix — notamment les ordinaux des couches, qui ont de nouveau changé dans la v9. Ne mélangez jamais les dialectes : les (tstamp ...) de l'ère v6/v7 ou les graphiques (width ...) de la v6 à l'intérieur d'un en-tête v8/v9 sont la cause la plus fréquente de fichiers qui ne se chargent pas.

Non-négociables

1. Un seul dialecte par fichier. L'en-tête version, generator_version, les UUID des pistes, la syntaxe des traits et les champs des empreintes doivent tous correspondre à la version déclarée.
2. Une carte est un fichier complet, pas un extrait. Elle doit s'ouvrir dans KiCad et passer le vérificateur structurel ci-dessous.
3. La connectivité est géométrique. Une piste avec le bon numéro de net qui ne touche ni un pad ni une autre piste n'est toujours pas routée.
4. Pas de suppositions électriques silencieuses. Le mappage broche-net, la polarité, le choix d'empreinte et les espacements de sécurité doivent être énoncés comme des hypothèses ou demandés.
5. Ne revendiquez pas la conformité de fabrication sans limites de fabrication vérifiées. Les chiffres de fabrication dépendent de l'empilement et du fabricant.
6. Pas de revendication de release sans un rapport validé. Une carte est prête pour la release uniquement lorsque report/design-report.json contient professional_claim: true. Sinon, listez les vérifications échouées et les validations manquantes.

Pipeline de Conception Automatique (recommandé pour les nouvelles cartes)

N'écrivez pas manuellement une carte de release quand cette pipeline peut le faire. La pipeline transforme un cahier des charges (design spec) en une carte avec de vraies empreintes de la bibliothèque KiCad, la route avec Freerouting, exécute DRC + DFM + vérification de la netlist KiCad, exporte les fichiers Gerber/forets/position/STEP/IPC-D-356, et écrit un rapport de vérification. Chaque sortie listée dans profile.fab_outputs est une contrainte obligatoire. Utilisez l'écriture manuelle uniquement pour revoir ou corriger une carte générée.

# 1. Valider l'intention (pas besoin de KiCad)
python3 scripts/design_spec.py validate specs/led-blinky.json

# 2. Conception automatique complète. Sélectionne automatiquement le mode local si KiCad 9 pcbnew, Java 25
#    et Freerouting 2.5.0 sont présents, sinon délègue à GitHub Actions.
python3 scripts/design_pipeline.py all specs/led-blinky.json

# La source de vérité électrique est un schéma ou une netlist ; le spec fournit la mécanique/les règles.
python3 scripts/design_pipeline.py all specs/led-blinky.json --schematic design.kicad_sch
python3 scripts/design_pipeline.py all specs/led-blinky.json --netlist design.net

# Carte existante : router/vérifier/exporter sans reconstruire.
python3 scripts/design_pipeline.py all specs/led-blinky.json --board existing.kicad_pcb --skip-build

# Étapes uniquement
python3 scripts/design_pipeline.py build specs/led-blinky.json -o build/led-blinky
python3 scripts/design_pipeline.py route build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json
python3 scripts/design_pipeline.py check build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json -o build/led-blinky/check
python3 scripts/design_pipeline.py fab   build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json -o build/led-blinky/fab

Entrées canoniques. specs/<name>.json est la source de vérité pour le chemin automatique. Utilisez schemas/design-spec.schema.json et specs/led-blinky.json comme modèles. Pour une requête en langage naturel, écrivez d'abord le spec, déclarez les hypothèses dans assumptions[], puis exécutez la pipeline. Pour un schéma/netlist KiCad, la netlist fait autorité pour les composants/pads nets ; le spec complémentaire fournit les dimensions de la carte, l'empilement, les règles, le placement et le routage.

Profils par classe de carte. Le profil sélectionne l'enveloppe de règles et les vérifications de release :

Profil	Automatisation	Validation humaine requise
2layer-low-speed	Complète : construire, placer, router, DRC, DFM, fab	aucune
4layer-impedance / 6layer-impedance	Conditionnée : empilement + impédance + vérification de longueur	stackup, impedance
rf-mixed-signal	Assistée ; les nets RF doivent être reroutées manuellement	rf, emc, thermal
flex-rigid	Assistée	mechanical, flex_bend, assembly
high-voltage	Conditionnée ; vérifications des distances d'isolement	safety, creepage

professional_claim est vrai uniquement lorsque chaque vérification obligatoire est réussie et que chaque validation requise est listée dans signoff.completed. Les aspects RF, CEM, thermique, sécurité et fatigue de flex ne peuvent pas être certifiés par la pipeline ; dites-le plutôt que de le revendiquer. Enregistrez un relecteur dans signoff.reviewer.

Sélection du backend : local ou CI (automatique). L'automatisation complète nécessite pcbnew (KiCad 9 Python), kicad-cli, Java 25 et freerouting-2.5.0.jar (Freerouting 2.5.0 est conçu pour Java 25). --backend auto est la valeur par défaut : il sonde l'environnement courant et s'exécute localement lorsque chaque étape demandée dispose de ses outils, sinon il déclenche .github/workflows/design.yml. Ce workflow s'exécute dans le conteneur officiel kicad/kicad:9.0, installe un JRE 25, télécharge Freerouting, exécute toute la pipeline, et télécharge design-output + design-report.

Environnement	Résultat de la sonde	Backend sélectionné
PC réel avec KiCad 9 + Java 25 + jar	toutes les étapes prêtes	local
Termux / conteneur sans KiCad ; gh authentifié ; repo propre poussé	pcbnew/kicad-cli manquant	CI
Pas d'outils locaux ni de CI utilisable	manquant	local, échoue avec la liste des outils manquants

python3 scripts/env_probe.py                        # que peut exécuter cette machine ?
python3 scripts/env_probe.py --json                 # sonde lisible par machine
python3 scripts/design_pipeline.py all specs/led-blinky.json                     # auto
python3 scripts/design_pipeline.py all specs/led-blinky.json --backend local
python3 scripts/design_pipeline.py all specs/led-blinky.json --backend ci --ci-download build/ci

Le déclenchement CI est conservateur : il refuse un arbre modifié ou une branche en avance sur son amont, car Actions vérifie la révision poussée et concevrait autrement la mauvaise carte. Commitez et poussez d'abord le spec, les profils, les schémas, les scripts et le workflow. gh doit être installé et authentifié (pkg install gh, puis gh auth login). Utilisez --ci-repo owner/name uniquement lors du déclenchement d'un dépôt autre que le courant. Les exécutions CI sont surveillées par défaut afin que le code de sortie reflète professional_claim ; ajoutez --no-ci-watch pour revenir immédiatement après le déclenchement.

Les commandes d'étape (build, route, check, fab) s'exécutent localement car la CI ne peut pas voir les fichiers d'étape non commités ; utilisez all --backend ci pour une exécution CI de bout en bout. Dans GitHub Actions, la pipeline reste toujours locale, donc une exécution CI ne se redéclenche jamais.

Règle d'itération. Lorsqu'une vérification échoue, modifiez le spec (placement, largeur, dégagement, empilement, affectation de classe) et régénérez. Ne modifiez pas une carte générée et prétendez ensuite que le rapport s'applique ; le rapport enregistre le spec exact résolu (<name>.spec.json).

Sources de Récupération (à utiliser avant de deviner)

Ressource	URL	Utilisation
Introduction aux S-Expression (syntaxe commune)	https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html	Syntaxe, guillemets, coordonnées, couches, empreintes, pads, graphiques, zones, groupes
Format de fichier Carte	https://dev-docs.kicad.org/en/file-formats/sexpr-pcb/index.html	Sections de premier niveau .kicad_pcb, en-tête, couches, configuration, nets, pistes, zones
Format de bibliothèque d'empreintes	https://dev-docs.kicad.org/en/file-formats/sexpr-footprint/index.html	Contexte .kicad_mod et champs d'empreinte
Index des formats de fichiers KiCad	https://dev-docs.kicad.org/en/file-formats/index.html	Formats de schéma/symbole lorsqu'un schéma correspondant est nécessaire
Documentation DRC KiCad	https://docs.kicad.org/9.0/en/pcbnew/pcbnew.html#design-rule-checking	Ce que le DRC réel vérifie et quelles règles sont configurables
Règles de conception personnalisées KiCad	https://docs.kicad.org/9.0/en/pcbnew/pcbnew.html#custom-design-rules	Syntaxe .kicad_dru et expressions de règles
Capacités JLCPCB	https://jlcpcb.com/capabilities/pcb-capabilities	Limites de fabrication actuelles (vérifier avant utilisation)
IPC-2221 / IPC-2152	https://www.ipc.org/	Fondamentaux de largeur de piste/courant, dégagement et distance d'isolement

La documentation développeur est parfois en retard sur l'application (elle décrit encore les graphiques (width ...) d'avant la v7 et les pistes (tstamp ...)). Lorsque la documentation et un fichier réel de la version cible de KiCad sont en désaccord, suivez le fichier réel et notez la divergence.

Références et Ressources Locales

Chemin	Contenu
references/pcb-file-format.md	Matrice de versions, sections, ordinaux des couches, configuration/empilement, empreintes, pads, pistes, zones, liste de contrôle
references/sexpr-primitives.md	Syntaxe des jetons, guillemets, traits, effets, UUID, primitives de pad/graphique/zone, jetons sensibles à la version
references/practical-rules.md	Empilement, placement, routage, courant/largeur, SI/PI/EMI, impédance, thermique, mécanique, DFM/DFA, valeurs par défaut
assets/minimal-2layer.kicad_pcb	Carte vierge 2 couches propre et validée (à copier comme point de départ)
assets/example-led.kicad_pcb	Exemple routé propre et validé : connecteur THT, résistance/LED CMS, vias, courtyard, trou de montage
assets/example.kicad_dru	Exemples de règles personnalisées (largeur de netclass, dégagement haute tension)
schemas/design-spec.schema.json	Spec de conception automatique canonique (carte, règles, nets, placement, empilement, vérifications)
profiles/*.json	Enveloppes de règles et vérifications de release par classe de carte
specs/led-blinky.json	Spec de référence pour la pipeline automatique
scripts/design_spec.py	Valideur de spec sans dépendance, importateur de netlist, calculs d'impédance/courant, rapport de vérification
scripts/pcb_build.py	Spec → carte KiCad utilisant de vraies empreintes de bibliothèque (pcbnew)
scripts/pcb_route.py	Export DSN → Freerouting → Import SES → remplissage de zone
scripts/pcb_check.py	Vérifications structurelles, DRC, DFM, parité de netlist et correspondance de longueur
scripts/pcb_fab.py	Gerbers, forets, position, STEP, IPC-D-356 et README de fabrication
scripts/design_pipeline.py	Orchestre toute la conception automatique et écrit le rapport de release ; --backend auto sélectionne local ou CI
scripts/env_probe.py	Détecte pcbnew, kicad-cli, Java 25, Freerouting, gh/git et recommande local vs CI
scripts/ci_dispatch.py	Déclenche .github/workflows/design.yml, surveille et télécharge optionnellement les artefacts
scripts/check_pcb.py	Vérificateur structurel/géométrique pré-vol sans dépendance
.github/workflows/design.yml	CI : construction, routage, DRC/DFM, export de fabrication et rapport dans le conteneur KiCad 9

Utilisez les termes de recherche dans ces références avant de récupérer une page entière de documentation : version, generator_version, layers, stackup, setup, net, footprint, property, attr, pad, stroke, segment, via, zone, keepout, filled_polygon, Edge.Cuts, embedded_fonts, remove_unused_layers, courtyard, impedance, differential, 3W, return path, DFM, trace width.

Flux de Travail Manuel / de Révision

Utilisez d'abord la pipeline automatique. Ce flux de travail sert à réviser une carte générée, à corriger une conception dont le spec ne peut pas exprimer une contrainte, ou à travailler dans un environnement où les outils de la pipeline ne sont pas disponibles.

1. Clarifiez l'intention de conception (ne devinez pas en silence sur les contraintes critiques).

   • Fonction de la carte, composants, connecteurs, nets d'alimentation/masse, dimensions cibles et contraintes mécaniques.
   • Hypothèses de fabrication : nombre de couches (par défaut 2), unités (mm), épaisseur de cuivre, empilement, finition de surface, processus d'assemblage.
   • Version cible de KiCad. Par défaut, utilisez KiCad 9 sauf indication contraire de l'utilisateur.
   • Si les exigences sont sous-spécifiées, énoncez explicitement les hypothèses dans la réponse et encodez des valeurs par défaut raisonnables dans le fichier.

2. Modélisez d'abord la netlist électrique.

   • Définissez (net 0 "") plus chaque net nommé avant que les éléments ne les référencent. Gardez les ordinaux stables et uniques.
   • Assurez-vous que chaque ordinal net de pad, piste, via et zone existe ; assurez-vous que les noms (net N "NAME") des pads correspondent exactement à la table des nets.
   • Si un schéma correspondant existe, les empreintes ont besoin de liens path/référence ; une conception sans schéma doit être marquée board_only le cas échéant.

3. Définissez la mécanique, les couches et l'empilement.

   • Partez de assets/minimal-2layer.kicad_pcb et gardez son en-tête/couches/configuration valides.
   • Définissez la section layers avec les noms canoniques et les bons ordinaux (voir le tableau dans references/pcb-file-format.md ; B.CrtYd/F.CrtYd ne sont pas séquentiels).
   • Définissez (general (thickness 1.6) (legacy_teardrops no)), (paper "A4"), et un stackup réaliste si l'empilement est important.
   • Fournissez une limite Edge.Cuts fermée (lignes/arcs ou un seul rect/cercle/polygone). Gardez le cuivre éloigné du bord.

4. Placez les empreintes.

   • Utilisez des définitions d'empreintes intégrées complètes : layer, uuid, at, champs property (Reference/Value), attr smd|through_hole, pads, sérigraphie, courtyard F.CrtYd/B.CrtYd, et optionnellement F.Fab et un modèle 3D.
   • Placez par fonction : connecteurs, entrée d'alimentation et MCU en premier ; regroupez les circuits connexes ; séparez les domaines analogique/numérique/bruyant.
   • Placez les condensateurs de découplage à chaque broche d'alimentation/masse d'un CI avec une boucle de surface minimale ; valeurs/boîtiers selon la fiche technique ou les hypothèses énoncées.
   • Respectez les espacements de courtyard et d'assemblage ; gardez les références lisibles et les pièces polarisées marquées.

5. Routez la connectivité.

   • segment pour les pistes, via pour les changements de couche, arc pour les pistes courbes. Les pistes KiCad 8/9 utilisent (uuid ...), pas (tstamp ...) (v6/7 utilisaient encore tstamp).
   • Définissez width par élément selon l'intention de courant/empilement ; l'alimentation plus large que les signaux. Les classes de net résident dans le fichier de projet/règles de conception, pas dans .kicad_pcb.
   • Gardez les pistes courtes/directes, préférez les coudes à 45°, minimisez les vias sur les chemins haute vitesse.
   • Préservez les chemins de retour : ne routez pas les pistes haute vitesse/sensibles à travers des coupures de plan. Appliquez un espacement ~3W pour les parcours parallèles sujets à la diaphonie.
   • Impédance/différentiel : utilisez references/sexpr-primitives.md pour les (stackup ...), (diff_pair_gap ...), (diff_pair_width ...), (impedance ...) et (target ...) ; l'empilement doit être défini pour que KiCad calcule l'impédance. Pour les paires différentielles, définissez (diff_pair_gap ...) et (diff_pair_width ...) avant le routage.
   • Tous les composants (IC, connecteurs, dissipateurs thermiques, montages) ont besoin d'une piste, d'un pad, d'un remplissage de zone ou d'une note explicitant qu'ils ne sont pas connectés. Nettoyez les soudures non connectées sauf si intentionnel (DNP).
   • Pistes de puissance : largeur suffisante pour le courant maximal (vérifiez avec les calculateurs IPC-2152 ou dans scripts/design_spec.py). Utilisez des plans sur des couches internes pour l'alimentation principale/masse.
   • Voies : via prend les paramètres (at x y), (size ...), (drill ...), layers (paire pour traversants, une seule couche pour enterrés/aveugles), net, uuid. free pour via non connecté.
   • Fins de piste : ne présumez pas (\top) / (\bot) ; les conventions de terminaison de piste dépendent du protocole ; utilisez des résistances de terminaison série si la disposition le permet.
   • La règle des 3W : espacement des pistes ≥3× la largeur de piste pour les voisins sensibles à la diaphonie ; la règle des 20H pour la réduction du rayonnement de bord de plan.

6. Gérez les zones et les dégagements.

   • Un plan de masse ininterrompu avec des connexions de zone, un dégagement thermique et des règles de forme de connexion. Utilisez des zones avec un remplissage solide solide pour les plans.
   • (zone (net N) ... (hatch ...) (fill ...)). Pour les plans de masse, utilisez (fill solid). Les règles de forme de connexion (plein, thermique, aucun) sont définies dans les propriétés du pad, pas dans la zone.
   • Zones de dégagement (keepout) pour les zones sans cuivre : (keepout (tracks not_allowed) (vias not_allowed) (copperpour not_allowed) (footprints not_allowed)).

7. Validez la carte.

   • Structurel : python3 scripts/check_pcb.py build/output.kicad_pcb.
   • DRC/DFM : python3 scripts/design_pipeline.py check .... La vérification DFM inclut les dégagements des bords, la densité, les ponts de soudure, les pastilles de test, etc.
   • Exhaustivité : chaque filet a-t-il une connexion ? Chaque pad est-il couvert par la couche de soudure ? La sérigraphie n'entre-t-elle pas en conflit avec les pads ?
   • Cohérence : pas de couches fantômes, pas de cisaillement de plan, pas de vias aveugles/enterrés d'une couche vers elle-même. Vérifiez que les couches de la section layers dans le fichier correspondent à (remove_unused_layers no).

8. Exportation de fabrication.

   • Utilisez python3 scripts/design_pipeline.py fab pour les Gerbers, forets, position, STEP et IPC-D-356.
   • Vérification fab pré-export dans check : épaisseur de cuivre, dégagements minimaux, couronnes annulaires via/pad.
   • Lors de l'exportation d'un panneau : (tedit ...) avec des lignes/arcs Edge.Cuts ; définissez (general (panels ...)).

Rédaction de Fichier de Carte (procédure pas à pas lorsque la pipeline est indisponible)

Lorsque la pipeline n'est pas disponible (pas d'Python/scripts/internet), utilisez la procédure suivante comme filet de sécurité. Commencez toujours par assets/minimal-2layer.kicad_pcb et gardez sa structure valide.

1. Écrire la section header : (version 20241229) (KiCad 9) ou (version 20240108) (KiCad 8), generator avec le bon (generator_version "9.0").
2. Définir les couches : Copiez depuis assets/minimal-2layer.kicad_pcb si 2 couches. Pour plus de couches, utilisez les ordinaux canoniques de references/pcb-file-format.md#layer-ordinal-table.
3. Définir la configuration : (setup (stackup ...) (solder_mask ...) (solder_paste ...) (pad_to_mask_clearance ...) (allow_soldermask_bridges_in_footprints no) (defaults ...)).
4. Définir les nets : (net 0 "") puis les nets nommés. Maintainez des ordinaux uniques/sans lacunes.
5. Placer les empreintes : (footprint ...) complet avec pads, sérigraphie, courthyard et fabric. Assurez-vous que l'attribut (attr through_hole) ou smd est correct pour les pads et la catégorie d'empreinte.
6. Router les pistes : (segment ...), (via ...), (arc ...). Utilisez les UUIDs du format v8/v9. Ne créez pas de pistes avec tstamp (v6).
7. Ajouter des zones, des keepouts : (zone ...), (keepout ...).
8. Valider avec des outils externes : scripts/check_pcb.py build/board.kicad_pcb explorer l'arbre s-expression.
9. Itérer : Ajustez le placement/les largeurs/les dégagements et répétez jusqu'à ce que la carte soit valide et bien formée.

Vérifications Manuelles Clés

• Les couches sont définies uniquement dans la section layers. Pas de (type) dans la configuration, pas de paramètres de couche en double, pas de zones F.Adhes (utilisation historique) – utilisez les noms canoniques F.Mask, F.Paste, F.Silkscreen, F.Fab, F.CrtYd et leurs homologues arrière.
• (setup (defaults ...)) inclut (track_clearance ...) et (track_width ...) comme valeurs par défaut pratiques.
• (pad ... (clearance ...) (zone_connection ...)) présent sur les pads des cartes multi-couches haute vitesse ; laissez-le aux valeurs par défaut ((clearance nil), (zone_connection 0) pour thermique) pour les conceptions à 2 couches.
• Les empreintes from the start ne dupliquent pas les pads ou la sérigraphie. Utilisez des définitions d'empreintes séparées (footprint ... (uuid ...) ...) ; ne créez pas de doublons dans le fichier carte.
• (net 0 "") défini avant tout net nommé et n'est pas supprimé ; laissez (net 1 "GND") solide après le net zéro.
• Fin de piste : les résistances de terminaison série ou les circuits de polarisation implicites ? Ne supposez pas une valeur de terminaison sans une note ou une autorisation explicite.
• Pièces polarisées correctement orientées : les diodes, les électrolytiques, les LED et les IC doivent avoir une orientation correcte (plots/broches 1, anode/cathode) et la sérigraphie doit le montrer.
• Les trous de montage sont placés, non plaqués et non connectés à aucun net (sauf si mis à la terre).

Priorité de Correction : structure → netlist → placement → routage → fab

Ne passez pas à l'étape suivante si la précédente a des erreurs : une carte avec une netlist invalide ne peut pas être correctement routée ; une carte mal placée ne peut pas être validée par fab.

[Le reste du contenu original a été tronqué. La traduction ci-dessus reflète le contenu jusqu'au point de troncature signalé.]