Pinion - La documentation de cartes électroniques

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.

 Installation

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.

~/.profile if [ -d "$HOME/.local/bin" ] ; then PATH="$HOME/.local/bin:$PATH" fi

En relançant notre terminal, ça marche !

pinion --help 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...

 Générer le modèle avec les composants intéressants

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.

script_pinion.sh #!/usr/bin/env bash pinion template --board carte.kicad_pcb \ --output carte_tmpl.yml \ --components "IC" \ --components "ALIM_"

 Première visualisation

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.

 Personnaliser les broches une par une

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.

carte_config.yml 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".

 Personnaliser les composants

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).

 Grouper les broches et les composants

À 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.

carte_config.yml 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.

 Calcul du rendu

Relancer le calcul avec votre fichier modifié :

pinion generate --board carte.kicad_pcb --specification carte_config.yml --pack web/

 Et si on veut modifier la carte...

... 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.

 Une démo !

Tout ça fait beaucoup de texte, voici à quoi ressemble le rendu !

Vous avez l’exemple officiel ici.

 Testez chez vous

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.


[1Les navigateurs ne laissent plus les pages web accéder à des ressources se situant sur le PC du client.

Commentaires

Il n'y a pas de commentaires

Ajouter un commentaire

Forum sur abonnement

Pour participer à ce forum, vous devez vous enregistrer au préalable. Merci d’indiquer ci-dessous l’identifiant personnel qui vous a été fourni. Si vous n’êtes pas enregistré, vous devez vous inscrire.

Connexions’inscriremot de passe oublié ?

Copyright "POIVRON" 2011-2021, tous droits réservés
Administration du site