EasyEDA BOM CLI

Outil CLI pour importer en masse les composants d'une BOM CSV (LCSC / JLCPCB) directement dans des bibliothèques KiCad.

• Parse un fichier CSV de BOM avec colonnes flexibles (LCSC, JLCPCB, ou BOM manuelles)
• Détecte automatiquement les passifs (R/C/L) → footprints standard KiCad
• Télécharge les footprints .kicad_mod, modèles 3D .step/.wrl, et symboles .kicad_sym via l'API EasyEDA
• Écrit un CSV enrichi avec le statut de chaque composant (disponibilité footprint, 3D, symbole)
• Génère des fichiers .kicad_sch hiérarchiques depuis les en-têtes de section du CSV (--generate-sch)
• Opération idempotente : les fichiers existants sont ignorés sauf avec --overwrite

Prérequis

pip install requests pydantic

Configuration du chemin de bibliothèque

L'outil cherche automatiquement le chemin de la bibliothèque dans cet ordre :

1. Argument CLI --lib-path /chemin/vers/libs
2. Variable d'environnement OS EASYEDA2KICAD=/chemin/vers/libs
3. Configuration KiCad → Préférences → Configurer les chemins → EASYEDA2KICAD

La méthode recommandée est de configurer EASYEDA2KICAD dans KiCad :

• Ouvrir KiCad → Préférences → Configurer les chemins...
• Ajouter une entrée : Nom = EASYEDA2KICAD, Chemin = /home/user/Documents/Kicad/easyeda2kicad
• Le chemin est stocké dans ~/.config/kicad/<version>/kicad_common.json

Utilisation rapide

Import basique

python main.py --csv bom.csv

Si EASYEDA2KICAD est configuré dans KiCad, c'est tout ce qu'il faut.

Import avec chemin de bibliothèque explicite

python main.py --csv bom.csv --lib-path ~/Documents/Kicad/easyeda2kicad

Dry-run (voir ce qui serait fait sans rien créer)

python main.py --csv bom.csv --dry-run --verbose

Affiche un rapport complet de chaque composant (footprint trouvé, 3D disponible, symbole créé) sans écrire aucun fichier.

Dry-run avec logs détaillés

python main.py --csv bom.csv --dry-run -v

Écraser les fichiers existants

python main.py --csv bom.csv --overwrite

Re-télécharge tous les footprints, modèles 3D et symboles même s'ils existent déjà.

Importer uniquement footprints et modèles 3D (sans symboles)

python main.py --csv bom.csv --skip-symbols

Utile si vous gérez vos symboles manuellement ou avec un autre outil.

Mode hors-ligne (passifs uniquement)

python main.py --csv bom.csv --no-fetch

Ne fait aucun appel API. Seuls les composants passifs (R/C/L) seront associés aux footprints standard KiCad.

CSV enrichi avec nom personnalisé

python main.py --csv bom.csv --output result.csv

Par défaut le CSV enrichi est écrit dans <input>_enriched.csv.

Nom de bibliothèque personnalisé

python main.py --csv bom.csv --lib-name myproject_libs

Crée myproject_libs.pretty/, myproject_libs.3dshapes/, et myproject_libs.kicad_sym.

Chemin séparé pour les modèles 3D

python main.py --csv bom.csv --3d-path ~/Documents/Kicad/3d_models

Enregistrer les bibliothèques dans un projet KiCad

python main.py --csv bom.csv --register-libs ~/Documents/Kicad/MonProjet/

Ajoute les entrées dans fp-lib-table et sym-lib-table du répertoire projet. KiCad verra les bibliothèques automatiquement au prochain chargement.

Rate-limiting personnalisé

python main.py --csv bom.csv --rate-limit 1.0

1 seconde entre chaque appel API (défaut : 0.4s). Utile si vous rencontrez des erreurs 429.

Mode silencieux (erreurs uniquement)

python main.py --csv bom.csv --quiet

Générer les schématiques KiCad depuis la BOM

python main.py --csv bom.csv --generate-sch ~/Documents/Kicad/MonProjet/projet.kicad_sch

Le CSV doit contenir des en-têtes de section (voir Format des sections). L'outil crée :

• Un schématique racine avec des blocs de feuilles hiérarchiques
• Un fichier .kicad_sch par section, avec les composants placés automatiquement
• Des rectangles nommés pour chaque bloc fonctionnel dans les sous-feuilles

Les schématiques générés sont au format KiCad 9 (version 20241209), taille A3.

Générer les schématiques en mode hors-ligne

python main.py --csv bom.csv --generate-sch projet.kicad_sch --no-fetch

Utile pour regénérer les .kicad_sch sans appels API (les bibliothèques doivent déjà exister).

Combinaison complète

python main.py \
  --csv bom_jlcpcb.csv \
  --lib-path ~/Documents/Kicad/easyeda2kicad \
  --lib-name easyeda2kicad \
  --output bom_enriched.csv \
  --generate-sch ~/Documents/Kicad/MonProjet/projet.kicad_sch \
  --register-libs ~/Documents/Kicad/MonProjet/ \
  --overwrite \
  --rate-limit 0.5 \
  --verbose

Options CLI complètes

  --csv, -c             Chemin vers le fichier CSV de BOM (requis)
  --output, -o          Chemin du CSV enrichi en sortie (défaut: <input>_enriched.csv)
  --lib-path            Répertoire de base pour les fichiers bibliothèque KiCad
                        (défaut: EASYEDA2KICAD depuis config KiCad ou variable d'env)
  --lib-name            Préfixe de nom de bibliothèque (défaut: easyeda2kicad)
                        Crée {name}.pretty, {name}.3dshapes, {name}.kicad_sym
  --3d-path             Chemin alternatif pour les modèles 3D
                        (défaut: {lib-path}/{lib-name}.3dshapes)
  --overwrite           Écraser les fichiers existants (footprints, 3D, symboles)
  --skip-symbols        Ne pas importer les symboles (footprints et 3D seulement)
  --no-fetch            Mode hors-ligne, pas d'appels API EasyEDA
  --rate-limit          Délai entre les appels API en secondes (défaut: 0.4)
  --dry-run             Afficher ce qui serait fait sans créer de fichiers
  --register-libs DIR   Enregistrer les bibliothèques dans fp-lib-table et
                        sym-lib-table du répertoire projet spécifié
  --generate-sch ROOT   Générer des fichiers .kicad_sch hiérarchiques depuis
                        les en-têtes de section du CSV. ROOT est le chemin du
                        schématique racine à créer (ex: projet/projet.kicad_sch)
  --verbose, -v         Afficher les logs détaillés (debug)
  --quiet, -q           N'afficher que les erreurs

Format du CSV d'entrée

Le parser accepte des noms de colonnes flexibles. Voici les alias reconnus :

Champ	Alias acceptés
Reference	reference, ref, designator, references, comment, refdes, part reference
Value	value, val, part value, component value, nominal, part name
LCSC	lcsc, lcsc part, lcsc part number, jlcpcb part, part number, mpn
Package	package, pkg, case/package, package size, case, size, boitier
Description	description, desc, name, component description
Quantity	quantity, qty, count, nb, qte

Les références multiples par ligne sont supportées (ex: R1, R2, R3 dans la colonne Reference).

Exemple de CSV minimal

Reference,Value,LCSC
R1,10k,C25804
R2,100k,C25999
C1,100nF,C14663
U1,STM32F103C8T6,C8734

Exemple CSV JLCPCB natif

Designator,Comment,Footprint,LCSC Part #
R1,10k,0402,C25804
C1,100nF,0603,C14663
U1,STM32F103C8T6,LQFP-48,C8734

En-têtes de section pour --generate-sch

Pour utiliser --generate-sch, le CSV doit contenir des lignes de section qui décrivent l'arborescence hiérarchique des schématiques :

Reference,Value,LCSC,Package

# POWER/power.kicad_sch (LDO + BUCK-BOOST + DECOUPLING)
U4,BQ24074RGTR,C54313,QFN-16
U5,TPS63020DSJR,C15483,VSON-14
C4,10uF,C15525,0402
C5,22pF,C52923,0402

# BATTERY/battery.kicad_sch (BAT-CONNECTOR + FUEL-GAUGE)
J2,"JST-PH 2P 2.0mm (LiPo)",C295747,JST-PH-SMD-2P
U6,MAX17048G+T10,C2682616,TDFN-8
C12,100nF,C1525,0402

Format de la ligne de section :

# DOSSIER/fichier.kicad_sch (BLOC1 + BLOC2 + BLOC3)

• DOSSIER/fichier.kicad_sch — Chemin relatif du sous-schématique (le dossier est créé automatiquement)
• (BLOC1 + BLOC2 + ...) — Noms des blocs fonctionnels, affichés comme rectangles étiquetés dans la sous-feuille (optionnel)
• Les lignes de composants qui suivent sont assignées à cette section
• Les valeurs contenant des virgules dans des parenthèses sont gérées automatiquement (ex: "47k (VBAT->ADC top, option)")

L'outil génère :

• Schématique racine : contient un bloc (sheet ...) par section
• Sous-schématiques : contiennent les composants placés en grille avec espacement automatique, plus les rectangles nommés pour chaque bloc

CSV enrichi en sortie

Le CSV de sortie contient toutes les colonnes d'origine plus les informations d'import :

Colonne	Description
Reference	Référence du composant (R1, C1, U1…)
Value	Valeur (10k, 100nF, STM32F103…)
LCSC	Numéro LCSC (C25804)
Package	Taille du boîtier (0402, 0603, LQFP-48…)
Description	Description du composant
Manufacturer	Fabricant (depuis l'API)
Datasheet	URL de la datasheet
Footprint	Footprint KiCad assigné (ex: Resistor_SMD:R_0402_1005Metric)
Footprint_Source	KiCad_Standard, EasyEDA, ou vide
Footprint_Created	True si le fichier .kicad_mod a été créé
Has_3D_Model	True / False
3D_Model_Source	KiCad_Standard, EasyEDA, ou vide
3D_Model_Created	True si le(s) fichier(s) 3D ont été créés
Symbol_Name	Nom du symbole KiCad
Symbol_Created	True si le symbole a été ajouté dans .kicad_sym
EasyEDA_Footprint	Nom brut du footprint EasyEDA
Status	OK, WARNING, ou ERROR
Warnings	Messages d'avertissement
Errors	Messages d'erreur

Structure des bibliothèques créées

{lib-path}/
├── {lib-name}.pretty/          # Footprints (.kicad_mod)
│   ├── STM32F103C8T6.kicad_mod
│   └── AMS1117-3.3.kicad_mod
├── {lib-name}.3dshapes/        # Modèles 3D
│   ├── STM32F103C8T6.wrl
│   ├── STM32F103C8T6.step
│   ├── AMS1117-3.3.wrl
│   └── AMS1117-3.3.step
└── {lib-name}.kicad_sym        # Symboles (fichier unique)

Les passifs (R/C/L) ne créent pas de fichiers ici — ils utilisent les bibliothèques standard de KiCad (Resistor_SMD, Capacitor_SMD, Inductor_SMD).

Fonctionnement

Composants passifs (R, C, L)

Les résistances, condensateurs et inductances sont automatiquement associés aux footprints de la bibliothèque standard KiCad :

• R1 + package 0402 → Resistor_SMD:R_0402_1005Metric
• C1 + package 0603 → Capacitor_SMD:C_0603_1608Metric
• L1 + package 0805 → Inductor_SMD:L_0805_2012Metric

Les modèles 3D standard KiCad correspondants sont aussi référencés automatiquement. Aucun fichier n'est téléchargé, car tout est déjà dans KiCad.

Tailles supportées : 01005, 0201, 0402, 0603, 0805, 1206, 1210, 1806, 1812, 2010, 2512

Composants actifs / complexes (ICs, connecteurs…)

Pour les ICs, connecteurs, etc. :

1. L'outil récupère les données depuis l'API EasyEDA/LCSC
2. Télécharge le footprint (.kicad_mod) dans {lib-name}.pretty/
3. Télécharge les modèles 3D (.wrl + .step) dans {lib-name}.3dshapes/
4. Crée l'entrée symbole dans {lib-name}.kicad_sym
5. Les fichiers existants sont ignorés sauf avec --overwrite

Détection automatique de la taille de boîtier

L'outil détecte la taille du boîtier depuis (par ordre de priorité) :

1. La colonne Package du CSV
2. Le nom du footprint EasyEDA (ex: "C0402" → 0402)
3. La description du composant

Architecture

easyeda_cli/
├── main.py                          # Point d'entrée CLI
├── README.md
├── easyeda/
│   ├── __init__.py
│   ├── easyeda_api.py               # Client API EasyEDA/LCSC REST
│   ├── easyeda_importer.py          # Parse les données API → objets structurés
│   ├── parameters_easyeda.py        # Modèles de données EasyEDA (Pydantic)
│   └── svg_path_parser.py           # Parsing SVG pour les arcs de symboles
├── kicad/
│   ├── export_kicad_footprint.py    # EasyEDA → .kicad_mod
│   ├── export_kicad_3d_model.py     # OBJ → .wrl + téléchargement .step
│   ├── export_kicad_symbol.py       # EasyEDA → entrée .kicad_sym
│   ├── parameters_kicad_footprint.py# Structures de données footprint KiCad
│   └── parameters_kicad_symbol.py   # Structures de données symbole KiCad
└── bom_cli/
    ├── __init__.py
    ├── csv_parser.py                # Parsing du CSV BOM flexible + sections
    ├── passive_matcher.py           # Auto-match R/C/L → KiCad standard
    ├── easyeda_fetcher.py           # Récupération données EasyEDA avec cache
    ├── library_manager.py           # Gestion des répertoires et lib-tables
    └── kicad_sch_generator.py       # Génération .kicad_sch hiérarchiques

Notes

• Aucun fichier .kicad_sch existant n'est modifié. Avec --generate-sch, de nouveaux fichiers sont créés à partir de zéro.
• Les appels API EasyEDA sont limités à 1 appel toutes les 0.4s par défaut pour éviter le rate limiting.
• Les résultats API sont mis en cache en mémoire : si plusieurs lignes CSV pointent vers le même numéro LCSC, l'API n'est appelée qu'une fois.
• L'opération est idempotente : relancer la commande ne re-télécharge que les fichiers manquants.
• Le code de sortie est 0 si tout est OK, 1 si au moins un composant est en erreur.