10 août 2021
Attention : Lisez notre brève du 13 novembre 2022 pour utiliser Pinion, qui présente actuellement des problèmes de compatibilité avec ses dépendances.
Nous présentons ici notre utilisation de Pinion, un outil qui nous parait bien pour documenter une carte électronique. La carte doit avoir été réalisée avec Kicad pour que l’outil fonctionne.
Nous testons l’outil dans sa version v0.2.0, en août 2021. L’outil n’est pas parfait et il faut accepter de passer un peu de temps à configurer le rendu pour avoir un résultat qui nous satisfasse.
Pas tout à fait un tutoriel, ni une traduction de la documentation, notre article est plutôt une description de notre utilisation de l’outil. Le but principal étant de vous le faire découvrir.
Il faut avoir Kicad d’installé et Python dans la même version que celle utilisée par Kicad.
Pour connaitre la version de Python utilisée par Kicad, dans Kicad ouvrez l’éditeur de PCB (pcbnew), allez dans Outil -> console de script. une console python s’ouvre, indiquant la version de Python.
L’installation de Pinon se fait avec "pip3", il s’agit du principal gestionnaire de paquet pour Python. L’installation de pip3 est décrite ici.
pip3 install pinion
Et vérifiez que Pinion fonctionne :
pinion --help
Nous rencontrons notre premier soucis. L’exécutable pinion est dans /.local/bin qui ne fait pas partie de notre PATH.
Nous rajoutons les lignes suivantes à notre fichiers /.profile. Ceci teste l’existence du répertoire et l’ajoute au PATH.
if [ -d "$HOME/.local/bin" ] ; then
PATH="$HOME/.local/bin:$PATH"
fi
En relançant notre terminal, ça marche !
Usage: pinion [OPTIONS] COMMAND [ARGS]...
Generate beautiful pinout digrams of your PCBs for web.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
generate Generate a pinout diagram
get Get Pinion resource files - e.g., template, pinion-widget...
serve Serve pinion digram generated with the '--packed' option.
template Output a template for pinout specification based on specified...
Pinion utilise le fichier Kicad et un fichier de configuration. Il est possible de partir de zéro pour réaliser ce fichier, mais Pinion propose de créer un modèle à partir du fichier Kicad, c’est une fonction que je recommande vivement.
Créez un répertoire de travail. Dans ce répertoire, copier votre fichier carte.kicad_pcb de votre carte. Créez un script qui générera votre modèle. Chaque ligne components contient une expression à chercher. Si le nom des composants contient l’une de ces expression, les composants seront pris en compte par Pinion.
#!/usr/bin/env bash
pinion template --board carte.kicad_pcb \
--output carte_tmpl.yml \
--components "IC" \
--components "ALIM_"
Si vous en arrivez là, vous aurez probablement envie d’avoir une idée du rendu. Utilisez la commande suivante pour générer les fichiers web :
pinion generate --board carte.kicad_pcb --specification carte_tmpl.yml --pack web/
Il est possible (certain même si vous utilisez cet exemple), que vous ayez des message de ce type :
Warning: component 'Quartz_488.back' for footprint 'X1' from library '' was not found
C’est du au fait que le composant n’est pas trouvé dans la bibliothèque de composant. Cela impactera le rendu, le composant ne sera pas représenté.
Les fichiers sont générés dans le répertoire web/.
À cause des mesures de sécurité, vous ne pourrez pas visualiser directement le fichier .html dans votre navigateur [1]. Pinion inclut un serveur web que vous pouvez utiliser ainsi :
pinion serve -b --directory web/
La commande lance le serveur web et un navigateur. Par la suite, vous pouvez laisser le serveur web tourner et rafraichir votre navigateur à chaque fois que les fichiers du répertoire web/ sont mis à jour.
En utilisant les codes de l’article, seules les broches les deux PICs, les L298 et les deux connecteurs d’alimentation réagissent au passage de la souris.
Avant de modifier le fichier pour personnaliser les broches, gardez une copie du fichier généré en le nommant "carte_base.yml".
Copier ce fichier "base" pour personnaliser les broches, nommez le "carte_config.yml"
Éditer carte_config.yml et renommez les broches (pin) qui vous intéressent.
Si vous souhaitez que plusieurs broches se surlignent en même temps, elle doivent porter le même nom.
Voici un extrait du fichier carte_config.yml. C’est un fichier YAML. L’indentation est critique, attention lors de son édition, à ne pas mélanger les espaces avec les tabulations.
name: CartePrincipale2014 # Put the name of diagram here
description: Example diagram # Put a short description of the diagram here
components:
IC1:
description: DSPIC33FJ128MCX02 # Arbitrary comment
groups: [] # Specify component groups
pins:
'1': # Connected to /LED_1
name: IC1.1
description: ''
groups: []
'2': # Connected to /LED_2
name: IC1.2
description: ''
groups: []
...
highlight: false # Make the component active
Même si les broches ont le même nom, elles ont chacune leur propre description. Si vous souhaitez avoir une description commune, supprimez le champs description de la broche et créez un champ alias qui porte le nom de la broche ayant la description qui vous intéresse. Ainsi, vous n’aurez qu’une description à renseigner pour un lot de broches.
Les descriptions sont au format Markdown.
Nous donnons une description aux broches des microcontrôleurs et des alias aux autres broches. Ceci suffit à documenter les signaux "intéressants".
Les composants ont chacun leur propre description, aussi au format Markdown.
Pour que cette description apparaisse, il faut mettre à true le champ highlight. Le composant sera alors mis en évidence par un rectancle quand l’utilisateur à la souris dessus et la description s’affichera (à côté ou sous la carte).
À la fin du fichier carte_config.yml, nous définissons les groupes auxquels appartiennent les éléments sur la carte. Ce sont ces groupes qui apparaissent sur le côté de la carte et que l’utilisateur peut sélectionner.
groups:
Connecteurs:
- Alimentation
- Codeurs
...
Composants:
- Régulateurs de tension
- Hacheurs
- PIC
Broche connecteur RPi:
Nous groupons les composants par famille pour aider le lecteur à les identifier sur la carte. Nous avons deux grandes catégories, les composants et les connecteurs.
Au niveau des broches, l’intérêt des les grouper ne nous a paru utile que pour le connecteur du Raspberry Pi. C’est un connecteur de 26 broches dont seuls quelques unes sont utilisées. En créant un groupe, nous mettons aisément en évidence les broches utilisées.
Relancer le calcul avec votre fichier modifié :
pinion generate --board carte.kicad_pcb --specification carte_config.yml --pack web/
... doit-on tout recommencer ?
Non, re-générez le fichier carte_tmpl.yml, comparez le avec carte_base.yml et reportez ces modifications sur votre fichier carte_config.yml.
Tout ça fait beaucoup de texte, voici à quoi ressemble le rendu !
Vous avez l’exemple officiel ici.
En fichier joint, vous trouverez le circuit Kicad carte.kicad_pcb, le fichier généré par Pinion carte_tmpl.yml et le fichier édité par nos soins carte_config.yml.
[1] Les navigateurs ne laissent plus les pages web accéder à des ressources se situant sur le PC du client.