Documenter une carte électronique

Ce qu’il faut documenter

Une carte électronique bien documentée répond à quatre questions : à quoi sert chaque partie du circuit, quels composants exactement, comment c’est câblé, et pourquoi ces choix. Ce dernier point rejoint Tracer ses choix techniques.

Où ranger les fichiers

Deux emplacements, deux rôles :

Le site n’affiche que ce qui se trouve dans le dossier docs/. Recopiez vos fichiers dans docs/assets/kicad/ à chaque évolution importante de la carte, sinon le site montre une ancienne version. Complétez aussi le README.md de project/ecad/ (un tableau : carte, dossier, rôle).

Afficher le schéma et le PCB

{% include kicad.html src="assets/kicad/carte-capteurs.kicad_sch" %}

{% include kicad.html src="assets/kicad/carte-capteurs.kicad_pcb" %}

Méthode de secours : exporter une image

Si votre carte n’est pas faite sous KiCad, ou si vous voulez une figure figée (pour un poster, par exemple), exportez une image. C’est la méthode qui marche toujours, sans rien installer de plus.

![Schéma du circuit](../../assets/images/schema.svg)

La nomenclature (BOM)

La nomenclature liste chaque composant du circuit. Elle se génère avec KiCad, pas à la main.

Une fois le CSV généré, reformatez les colonnes utiles en tableau Markdown pour l’intégrer proprement à votre page (référence exacte, pas juste “une résistance”). C’est le tableau que contient la page d’exemple du template :

| Référence | Composant | Valeur / réf. exacte | Quantité | Source |
|---|---|---|---|---|
| U1 | Microcontrôleur | ESP32-S3-DevKitC-1 | 1 | ... |
| R1-R4 | Résistance | 10kΩ, 1/4W | 4 | ... |
| D1 | Driver moteur | A4988 | 1 | ... |

Pour aller plus loin : nomenclature interactive avec un plugin KiCad

Le plugin InteractiveHtmlBom génère un fichier HTML autonome qui affiche le PCB et la nomenclature côte à côte : cliquez une ligne de la BOM, le composant correspondant s’illumine sur le circuit. Particulièrement utile pour le soudage manuel et pour Documenter l’assemblage et le montage.

[Voir la nomenclature interactive](../../assets/nomenclature-interactive.html)

Le brochage (pin mapping)

Le brochage dit quelle broche du microcontrôleur est reliée à quoi. C’est la première question de quiconque reprend votre carte ou votre code, et l’endroit où naissent les bugs les plus difficiles à trouver : une broche changée sur le schéma mais pas dans le code, ou l’inverse.

Il se documente en trois couches, avec une règle simple : le code fait foi, la documentation le reprend.

1. Dans le code : un seul fichier pins.h

Toutes les broches sont déclarées dans un seul fichier, include/pins.h du projet PlatformIO (par exemple project/firmware/mon-robot/include/pins.h), avec un nom parlant et un commentaire par ligne :

// Brochage de la carte principale (ESP32-S3).
// Documenté sur la page Carte principale du site : le mettre à jour en même temps.
#pragma once

// Pince
constexpr int PIN_SERVO_PINCE = 18;  // sortie PWM, servo SG90 alimenté en 5 V
constexpr int PIN_FIN_COURSE  = 19;  // entrée, pull-up interne, appuyé = LOW

// Capteur de couleur TCS3200
constexpr int PIN_COULEUR_S0  = 4;   // sortie, choix de l'échelle de fréquence
constexpr int PIN_COULEUR_OUT = 5;   // entrée, signal en fréquence

Le reste du code n’écrit jamais un numéro de broche : il utilise PIN_SERVO_PINCE, jamais 18. Changer une broche ne demande alors de modifier qu’une seule ligne, et personne n’en oublie une au fond d’un autre fichier.

2. Dans la documentation : un tableau

Sur la page de la carte, un tableau reprend pins.h. La colonne Nom dans le code fait le pont entre le schéma KiCad et le firmware :

| Broche | Nom dans le code | Composant | Sous-ensemble | Remarque |
|---|---|---|---|---|
| GPIO18 | `PIN_SERVO_PINCE` | Servo SG90 | Pince | Sortie PWM, servo alimenté en 5 V |
| GPIO19 | `PIN_FIN_COURSE` | Microrupteur | Pince | Entrée, pull-up interne, appuyé = LOW |
| GPIO4 | `PIN_COULEUR_S0` | TCS3200 (S0) | Capteur de couleur | Sortie, échelle de fréquence |
| GPIO5 | `PIN_COULEUR_OUT` | TCS3200 (OUT) | Capteur de couleur | Entrée, signal en fréquence |

La colonne Remarque est celle qu’on oublie le plus souvent, alors qu’elle évite les vraies erreurs : sens (entrée ou sortie), résistance de tirage, niveau actif, tension, broches à éviter au démarrage de la carte.

3. Pour la lisibilité : un schéma de brochage

Un schéma Mermaid, écrit en texte comme le reste de la documentation, montre le brochage d’un coup d’œil. Le sens des flèches indique les entrées (vers la carte) et les sorties (depuis la carte), et chaque subgraph regroupe les composants d’un sous-ensemble :

```mermaid
flowchart LR
    ESP[ESP32-S3]
    subgraph Pince
        SERVO[Servo SG90]
        FDC[Fin de course]
    end
    subgraph Capteur de couleur
        TCS[TCS3200]
    end
    ESP -- GPIO18 --> SERVO
    FDC -- GPIO19 --> ESP
    ESP -- GPIO4 : S0 --> TCS
    TCS -- GPIO5 : OUT --> ESP
```

flowchart LR
    ESP[ESP32-S3]
    subgraph Pince
        SERVO[Servo SG90]
        FDC[Fin de course]
    end
    subgraph Capteur de couleur
        TCS[TCS3200]
    end
    ESP -- GPIO18 --> SERVO
    FDC -- GPIO19 --> ESP
    ESP -- GPIO4 : S0 --> TCS
    TCS -- GPIO5 : OUT --> ESP

Pour la syntaxe de Mermaid, voir Documenter son code et son firmware.

Photos du montage réel

Le schéma montre l’intention, une photo montre la réalité, souvent différente (fils de couleur, position des composants sur une breadboard, bricolage temporaire). Prenez ces photos au moment du montage, pas après coup (voir Documenter au fil de l’eau). Une simple photo prise avec un smartphone, placée dans docs/assets/images/ (moins de 2 Mo : réduisez sa résolution si besoin) et ajoutée avec ![Montage réel](../../assets/images/montage.jpg), suffit.

Exercice

Sur votre partie électronique : copiez vos fichiers KiCad dans docs/assets/kicad/ et affichez le schéma et le PCB sur la page de votre carte, générez votre nomenclature depuis KiCad et intégrez-la (en tableau ou en CSV), rédigez le tableau de brochage à partir de votre fichier pins.h (créez-le s’il n’existe pas encore), et ajoutez au moins une photo du montage réel.

Crédit photo : carte électronique du robot Otto, MakerSpace UniLaSalle Amiens (voir Découvrez la carte du Otto).