Contrôle de version pour le matériel Open Source : 10 étapes

2024 Auteur: John Day | [email protected]. Dernière modifié: 2024-01-30 09:08

L'équipe de Brainbow a un certain nombre de projets électroniques à son actif, et nous voulions partager notre processus d'utilisation du contrôle de version pour gérer notre flux de travail de conception électronique. Ce flux de travail a été utilisé pour des projets grands et petits, des simples cartes à 2 couches aux mastodontes complexes à 10 couches, et est basé sur des outils open source. Espérons que d'autres pourront adopter notre flux de travail pour eux-mêmes et bénéficier des avantages du contrôle de version pour leurs propres projets. Mais quels avantages le contrôle de version peut-il offrir à un projet électronique ?

Étape 1: Pourquoi contrôler la version de vos appareils électroniques ?

Le contrôle de version (alias contrôle de source ou contrôle de révision) est un concept bien compris et largement adopté en génie logiciel. L'idée derrière le contrôle de source est de suivre systématiquement les modifications apportées au code source d'un programme ou d'une application. Si des modifications interrompent l'application, vous pouvez rétablir les fichiers de code source dans un état de fonctionnement connu du passé. En pratique, les systèmes de contrôle de source vous permettent de suivre l'historique d'une collection de fichiers (généralement les fichiers de code source d'un programme informatique, d'un site Web, etc.) et de visualiser et de gérer les modifications apportées à ces fichiers.

Suivre l'historique des modifications d'un projet semble utile pour les projets électroniques; si vous faites une erreur dans le schéma du circuit ou si vous utilisez la mauvaise empreinte de composant dans la disposition du PCB, ce serait bien de garder une trace des erreurs commises et des correctifs mis en œuvre dans les différentes révisions d'un projet. Il serait également utile pour d'autres créateurs de voir cette histoire et de comprendre le contexte et les motivations de divers changements.

Étape 2: Les outils: KiCad et Git

Nous utilisons deux outils principaux dans ce projet: le système de contrôle de version (VCS) et le programme d'automatisation de la conception électronique (EDA ou ECAD).

Il existe BEAUCOUP de systèmes de contrôle de version, mais nous utilisons le VCS Git distribué. Nous l'utilisons pour un certain nombre de raisons, mais la clé est qu'il est open source (vérifiez !), facile à utiliser (vérifiez !) et le VCS standard de facto pour les logiciels open source (vérifiez !). Nous utiliserons Git comme VCS pour suivre les modifications apportées aux fichiers que notre programme ECAD utilise. Ce Instructable ne nécessite pas de familiarité avec Git, mais le confort général à l'aide de la ligne de commande est supposé. Je vais essayer de créer un lien vers des ressources utiles pour l'utilisation de Git et de la ligne de commande si nécessaire.

La plupart des systèmes de contrôle de source fonctionnent particulièrement bien pour les fichiers texte, donc un programme ECAD qui utilise des fichiers texte serait parfait. Entrez KiCad, la « Suite d'automatisation de la conception électronique multiplateforme et open source » en open source soutenue par des chercheurs du CERN. KiCad est également open source (vérifiez !), facile à utiliser (bien que certains ne soient pas d'accord avec moi sur ce point) et très performant pour les travaux de conception électronique avancés.

Étape 3: Installation

Pour installer ces programmes, suivez les instructions de leurs différents sites de téléchargement liés ci-dessous.

• KiCad est multiplateforme (et étourdissant; leur page de téléchargement répertorie 13 systèmes d'exploitation pris en charge et propose un téléchargement de code source si aucun de ceux-ci ne vous convient). Utilisez l'installation par défaut unifiée de kicad, et non la version de développement nocturne. Voir l'étape 4 pour des détails optionnels avancés sur l'installation de la bibliothèque.
• Git est également multiplateforme. Si vous utilisez Windows, je recommanderais l'impressionnant projet Git for Windows pour une expérience plus utile et complète.

La documentation d'installation disponible sur ces deux sites sera plus complète que toute description que je peux offrir ici. Une fois les deux programmes téléchargés et installés, vous pouvez cloner le modèle de projet de Brainbow à partir de notre référentiel Github. La commande git clone prend la structure `git clone {répertoire src} {répertoire cible}`; pour notre projet, utilisez `git clone https://github.com/builtbybrainbow/kicad-starter.git {target directory}`.

Le clonage d'un dépôt git est une forme spéciale de copie; lorsque vous clonez un projet, vous obtenez une copie de tous les fichiers inclus dans le référentiel ainsi que l'intégralité de l'historique suivi par Git du projet. En clonant notre repo, vous obtenez un répertoire de projet déjà structuré avec nos recommandations d'utilisation de Git avec KiCad. Nous aborderons plus en détail la structure du projet à l'étape 6, ou vous pouvez passer à l'étape 7 si vous avez hâte de travailler.

Quelques tâches d'entretien rapides - exécutez `git remote rm origin` pour supprimer le lien vers le projet Github à partir duquel vous avez cloné. Exécutez également `git commit --amend --author="John Doe "`, en remplaçant le paramètre author par votre nom et votre adresse e-mail. Cela modifie le dernier commit (qui dans ce cas est également le premier commit) et change l'auteur en vous, plutôt qu'en Brainbow.

Étape 4: Note d'installation: Bibliothèques KiCad

Une note rapide sur la structure de la bibliothèque de KiCad. KiCad fournit un ensemble de bibliothèques gérées par l'équipe de développeurs pour une large gamme de composants électriques. Il existe trois bibliothèques principales:

• Symboles schématiques: symboles utilisés pour représenter les composants électroniques dans un schéma de circuit.
• Empreintes PCB: dessins 2D représentant l'empreinte réelle (patins de cuivre, texte sérigraphié, etc.) à utiliser lors de la disposition du circuit sur un PCB.
• Modèles 3D: modèles 3D de composants électroniques.

Ces bibliothèques sont téléchargées avec la suite de programmes KiCad que vous venez d'installer. Vous pouvez utiliser KiCad sans plus d'effort. Cependant, pour les "utilisateurs expérimentés", les fichiers sources des bibliothèques sont stockés dans un référentiel git sur Github, permettant aux utilisateurs qui souhaitent rester au courant des dernières modifications de cloner les référentiels de la bibliothèque sur leur propre machine. Le suivi des bibliothèques avec git présente un certain nombre d'avantages: vous pouvez choisir quand vous souhaitez mettre à jour vos bibliothèques, et les mises à jour n'ont besoin que d'incorporer les modifications apportées aux fichiers, plutôt que de télécharger à nouveau l'ensemble des fichiers de bibliothèque. Cependant, vous êtes responsable de la mise à jour des bibliothèques, ce qui peut être facile à oublier.

Si vous souhaitez cloner les librairies, ce site détaille les différentes offres Github repos KiCad. Git clone les bibliothèques sur votre ordinateur (ex: `git clone https://github.com/KiCad/kicad-symbols.git`), puis ouvrez KiCad, sélectionnez l'élément "Préférences" de la barre de menu, et cliquez sur "Configurer les chemins… ". Cela vous permet d'indiquer à KiCad le chemin du répertoire dans lequel rechercher chaque bibliothèque. Ces variables d'environnement sont par défaut le chemin des bibliothèques installées avec l'installation de KiCad; J'ai pris note de ces valeurs afin de pouvoir revenir aux bibliothèques par défaut si nécessaire. Le chemin KICAD_SYMBOL_DIR doit pointer vers votre bibliothèque clonée de symboles kicad, KISYSMOD vers la bibliothèque clonée kicad-footprints et KISYS3DMOD vers la bibliothèque clonée kicad-packages3d.

Lorsque vous souhaitez mettre à jour les bibliothèques, vous pouvez exécuter une simple commande "git pull" dans le référentiel de la bibliothèque qui indiquera à Git de vérifier les différences entre votre copie locale du référentiel de la bibliothèque et le référentiel Github "à distance", et de mettre automatiquement à jour votre copie locale pour incorporer les modifications.

Étape 5: Principes de base de Git

Git est un programme complexe et aux multiples facettes, avec des livres entiers consacrés à sa maîtrise. Cependant, il existe quelques concepts simples qui vous aideront à comprendre comment nous utilisons Git dans notre workflow.

Git suit les modifications apportées aux fichiers en utilisant une série d'étapes. Les modifications normales ont lieu dans le répertoire de travail. Lorsque vous êtes satisfait des modifications que vous avez apportées à une série de fichiers, vous ajoutez les fichiers que vous avez modifiés à la zone de transfert. Une fois que vous avez apporté toutes les modifications que vous prévoyez et que vous avez mis en scène tous les fichiers que vous souhaitez suivre dans Git, vous validez ces modifications dans le référentiel. Les commits sont essentiellement des instantanés de l'état des fichiers dans un référentiel à un moment précis. Étant donné que Git suit les modifications apportées aux fichiers et stocke ces modifications dans les commits, vous pouvez à tout moment rétablir un projet dans l'état dans lequel il se trouvait lors de tout commit précédent.

Il existe des sujets plus complexes, comme les branchements et les télécommandes, mais nous n'avons pas besoin de les utiliser pour profiter des avantages du contrôle de source. Tout ce dont nous avons besoin est de suivre les modifications apportées à nos fichiers de conception KiCad avec une série de commits.

Étape 6: Structure du projet KiCad

Examinons de plus près la structure du projet KiCad-Starter que vous avez cloné précédemment. Il est divisé en plusieurs sous-répertoires pour une organisation facile:

• Circuit: Ce dossier contient les fichiers réels du projet KiCad (schéma, PCB, etc.). Je ne renomme pas ce dossier, mais je renomme tous les fichiers à l'intérieur avec le nom du projet (Circuit.pro => ArduinoMini.pro).

  • Circuit.pro: le fichier projet KiCad
  • Circuit.sch: le fichier schématique KiCad.
  • Circuit.kicad_pcb: le fichier de mise en page du PCB KiCad.
• Documentation: ce dossier sert à stocker la documentation concernant le projet. Nous avons des plans pour améliorer cet espace à l'avenir, mais pour l'instant il contient un simple fichier README. Utilisez-le pour stocker des notes sur le projet pour que vous puissiez les revoir ultérieurement.
• Fabrication: ce dossier est l'endroit où vous stockerez les fichiers Gerber que la plupart des usines de fabrication utiliseront pour fabriquer votre circuit imprimé. Nous l'utilisons également pour stocker des fichiers de nomenclature et d'autres documents pouvant être nécessaires à la fabrication et à l'assemblage.
• Bibliothèques: ce dossier sert à stocker les fichiers de bibliothèque spécifiques au projet (nous y reviendrons plus en détail dans quelques étapes).

Vous avez peut-être également remarqué quelques autres fichiers (en particulier si vous `ls -a` le répertoire). Le répertoire.git est l'endroit où Git fait sa magie, stockant l'historique du référentiel. Le fichier.gitignore est utilisé pour indiquer à Git quels fichiers il doit ignorer et ne pas stocker dans le contrôle de source. Il s'agit principalement de fichiers de sauvegarde générés par KiCad, ou de quelques fichiers "générés" différents, tels que des listes d'interconnexions, qui ne doivent pas être stockés dans le contrôle de source car ils sont générés à partir de la source qui est le fichier schématique.

Cette structure de projet n'est qu'un point de départ. Vous devez l'adapter à vos besoins et ajouter des sections si nécessaire. Dans certains projets, nous avons inclus un dossier logiciel ou un dossier de boîtier, dans lequel nous avons stocké des modèles pour les boîtiers d'impression 3D pour le projet.

Étape 7: Utiliser Git pour les projets KiCad

Nous sommes enfin prêts à voir comment utiliser Git pour suivre vos projets. Ce Instructable n'est pas destiné à vous apprendre à utiliser KiCad (bien que je puisse en faire un à l'avenir s'il y a une demande pour cela), nous allons donc passer en revue quelques exemples triviaux pour vous montrer comment fonctionne le flux de travail. Il doit être facile de comprendre comment adapter ces idées à un projet réel.

Ouvrez le répertoire kicad-starter, puis exécutez `git log` pour afficher l'historique des commits. Il devrait y avoir un commit ici, l'initialisation du repo par Brainbow. L'exécution de `git status` vous indiquera l'état des fichiers dans votre référentiel (non suivis, modifiés, supprimés, mis en scène).

Pour le moment, vous ne devriez avoir aucun changement dans votre repo. Faisons un changement. Ouvrez le projet KiCad et ajoutez une résistance au schéma, puis enregistrez. Maintenant, l'exécution de `git status` devrait montrer que vous avez modifié le fichier schématique, mais que vous n'avez pas encore préparé ces modifications pour la validation. Si vous êtes curieux de savoir ce que KiCad a fait exactement lorsque vous avez ajouté la résistance, vous pouvez exécuter la commande diff sur le fichier modifié `git diff Circuit/Circuit.sch`. Cela mettra en évidence les changements entre la version actuelle du fichier dans le répertoire de travail et l'état du fichier lors du dernier commit.

Maintenant que nous avons effectué une modification, essayons de valider cette modification dans l'historique de notre projet. Nous devons déplacer les modifications de notre répertoire de travail vers la zone de transit. Cela ne déplace pas réellement les fichiers dans le système de fichiers, mais est conceptuellement un moyen de faire savoir à Git que vous avez effectué toutes les modifications prévues pour un fichier particulier et que vous êtes prêt à valider ces modifications. Utilement, Git fournit quelques conseils lorsque vous exécutez `git status` pour la prochaine action. Notez le message `(utilisez "git add …" pour mettre à jour ce qui sera validé)` sous `Modifications non mises en place pour la validation:`. Git vous dit comment déplacer les modifications vers la zone de transit. Exécutez « git add Circuit/Circuit.sch » pour effectuer les modifications, puis « git status » pour voir ce qui s'est passé. Nous voyons maintenant le fichier schématique sous les modifications à valider. Si vous ne souhaitez pas encore valider ces modifications, Git propose une autre astuce: `(utilisez "git reset HEAD …" pour unstage)`. Nous voulons valider ces modifications, nous lançons donc `git commit -m "Ajout de la résistance au schéma"`. Cela valide les modifications avec le message fourni. L'exécution de git log affichera ce commit dans l'historique des commits du projet.

Quelques conseils supplémentaires sur les commits.

1. Ne vous engagez pas à chaque sauvegarde. Engagez-vous lorsque vous sentez que vous avez atteint un point où vos changements se sont quelque peu solidifiés. Je m'engage après avoir terminé un schéma, pas après chaque ajout de composant. Vous ne voulez pas non plus vous engager trop rarement, car il peut être difficile de se souvenir du contexte pour lequel vous avez fait les changements que vous avez apportés 3 semaines plus tard. Déterminer quand s'engager est un peu un art, mais vous deviendrez plus à l'aise à mesure que vous utiliserez davantage Git.
2. Ne stockez que la source (principalement). Cela inclut les fichiers de projet, de schéma et de mise en page, ainsi que les bibliothèques spécifiques au projet. Cela peut également inclure des fichiers de documentation. Soyez prudent lorsque vous stockez des objets dérivés car ils peuvent facilement se désynchroniser avec la source d'origine, ce qui provoque des maux de tête plus tard. Les fichiers BOM et gerber se désynchronisent particulièrement facilement, il vaut donc mieux les éviter (bien que des conseils plus détaillés soient couverts à l'étape 9).
3. Les messages de validation sont très utiles, mais les messages de validation bien structurés sont inestimables. Cet excellent article fournit quelques directives pour rédiger des messages de commit clairs, concis et utiles. Cela peut nécessiter l'utilisation d'un éditeur de texte en ligne de commande, ce qui peut être compliqué pour les débutants (`git commit` sans l'option de message -m ouvrira un éditeur de texte). Pour la plupart des gens, je recommande l'éditeur Nano. StackOverflow a une bonne explication du changement de votre éditeur

Étape 8: Avancé: Version sémantique pour l'électronique

Pour les âmes aventureuses, les conseils suivants sont des idées avancées, glanées à partir de nombreuses heures de développement de KiCad. Ils ne sont pas particulièrement utiles sur les petits projets, mais ils peuvent vraiment vous éviter des chagrins au fur et à mesure que vos projets deviennent de plus en plus complexes.

Dans le logiciel, il existe un concept de Versioning Sémantique (semver). Semver définit une méthodologie de nommage commune pour identifier les versions logicielles par "numéro de version", suivant un modèle de "Major. Minor. Patch". Pour citer les spécifications de semver, vous avancez le numéro de version en fonction des catégories de modifications suivantes.

1. Version MAJEURE lorsque vous apportez des modifications d'API incompatibles,
2. version MINEURE lorsque vous ajoutez des fonctionnalités de manière rétrocompatible,
3. version PATCH lorsque vous apportez des corrections de bogues rétrocompatibles.

Chez Brainbow, nous utilisons notre propre version de semver adaptée aux besoins des projets matériels. Notre spécification suit le même modèle "Major. Minor. Patch", bien que nos définitions des changements qui relèvent de quelle catégorie diffèrent évidemment.

1. Version MAJOR: utilisée pour des changements significatifs aux fonctionnalités de base du circuit (ex: commutation du processeur d'ATmegaa à ESP8266).
2. Version MINEURE: utilisée pour les échanges de composants susceptibles d'affecter le fonctionnement du circuit (par exemple: échange de flash SPI avec une partie compatible avec les broches pouvant avoir un jeu de commandes différent) ou l'ajout de certaines fonctionnalités supplémentaires mineures (par exemple: ajout d'un capteur de température supplémentaire).
3. Version PATCH: utilisée pour les corrections de bugs mineurs qui ne changeront pas le fonctionnement du circuit (ex: ajustement de la sérigraphie, ajustement mineur de la disposition des traces, échanges de composants simples comme le condensateur 0603 à 0805).

Dans le serveur de matériel, le numéro de version n'est mis à jour qu'à la fabrication (tout comme dans le logiciel, les numéros de version ne changent qu'avec les versions, chaque individu ne s'engage pas dans un projet). En conséquence, de nombreux projets ont des numéros de version faibles. Nous n'avons pas encore utilisé de projet avec plus de 4 versions majeures.

Outre les avantages en termes de cohérence et de compréhension que vous obtenez en passant à un système de nommage bien défini, vous bénéficiez également d'avantages en termes de compatibilité du micrologiciel et de satisfaction client. Le firmware peut être écrit en tenant compte de la version de la carte qu'il cible, et il peut être plus facile de déboguer pourquoi un programme particulier ne fonctionne pas sur une carte particulière ("c'est vrai, le firmware 2.4.1 ne fonctionne pas sur 1.2 planches parce que nous n'avons pas …"). Les clients ont également bénéficié de notre serveur de matériel, car le service client et le dépannage sont beaucoup plus faciles avec une norme définie.

Étape 9: Avancé: Utilisation du contrôle de version sémantique du matériel

Pour utiliser le semver matériel dans vos propres projets, nous utilisons une fonctionnalité Git appelée tagging. Lorsque vous fabriquez une carte pour la première fois, il s'agit de la version 1.0.0 de cette carte. Assurez-vous que vous avez validé toutes les modifications de votre projet, puis exécutez `git tag -a v1.0.0`. Cela ouvrira un éditeur afin que vous puissiez écrire un message d'annotation pour cette balise (très similaire à un message de validation). J'inclus des détails sur la fabrication (qui a fabriqué le PCB, qui a assemblé la carte), qui peuvent être des informations utiles plus tard.

La balise release est ajoutée à l'historique des commits et indique l'état des fichiers à la fabrication 1.0.0. Cela peut être particulièrement utile plusieurs révisions plus tard lorsque vous devez vous référer à ce point pour le dépannage. Sans une étiquette de version spécifiée, il pourrait être difficile de déterminer quel commit était le plus récent au moment de la fabrication. Une balise 1.0.0 (et 1.1, 1.1.1, etc.) vous permet de spécifier que ces fichiers sources spécifiques étaient ceux utilisés dans un cycle de fabrication particulier.

Une note sur Gerbers. Certaines fabuleuses maisons nécessitent des fichiers gerber pour créer votre planche, et vous pouvez les générer avec KiCad. Ce sont des objets dérivés, générés à partir du fichier source.kicad_pcb, et nous ne contrôlons normalement pas la version des fichiers dérivés. Chez Brainbow, nous ne stockons pas les gerbers dans le contrôle de version SAUF lorsque nous étiquetons une version. Lorsque nous sommes prêts à construire, nous générons les fichiers gerber, les stockons dans le dossier Fabrication, puis validons et étiquetons. Ensuite, nous supprimons les gerbers et commettons la suppression. Cela peut sembler un peu déroutant au début, mais cela garantit que les commits normaux ne stockent que les fichiers source, et que les versions étiquetées stockent également les fichiers exacts utilisés pour fabriquer les cartes. Cela s'est avéré remarquablement utile pour traquer les erreurs de fabrication des semaines plus tard.

Étape 10: Étapes suivantes

Espérons que cette introduction vous a suffisamment appris pour commencer à utiliser le contrôle de version sur vos propres projets électroniques. Nous n'avons pas abordé certains des sujets les plus avancés, comme le contrôle de version pour les bibliothèques partagées entre les projets ou les branches de fonctionnalités. Pourtant, le contrôle de version, c'est comme manger vos légumes: vous n'obtiendrez peut-être pas ce que vous pensez devoir, mais chaque morceau que vous obtenez compte.

Brainbow travaille sur un guide plus détaillé de certaines des fonctionnalités les plus avancées de notre flux de travail. Nous espérons le publier dans les prochains mois. Suivez-nous ici sur Instructables, et nous ne manquerons pas de vous faire savoir quand vous pourrez le lire.

Merci d'avoir lu, et nous avons hâte de voir ce que vous faites!