serv_benchmark/docs/IMPORT_MARKDOWN.md

Import de périphériques depuis fichiers Markdown

Le module périphériques permet d'importer automatiquement des spécifications de périphériques depuis des fichiers Markdown (.md).

Formats supportés

Le parser supporte deux formats de fichiers .md :

Format simple

Le format minimal avec juste un titre et une description :

# USB Device ID 0b05_17cb

## Description
Broadcom BCM20702A0 – Bluetooth USB (ASUS)

Extraction automatique :

• Nom du périphérique depuis la description
• Vendor ID et Product ID depuis le titre ou le nom de fichier
• Type de périphérique déduit de la description (souris, clavier, WiFi, etc.)
• Marque extraite de la description

Format détaillé

Le format complet avec toutes les spécifications USB :

# USB Device Specification — ID 0781:55ab

## Identification
- **Vendor ID**: 0x0781 (SanDisk Corp.)
- **Product ID**: 0x55ab
- **Commercial name**: SanDisk 3.2 Gen1 USB Flash Drive
- **Manufacturer string**: USB
- **Product string**: SanDisk 3.2Gen1
- **Serial number**: 040123d47e7a47e4ac9e89dd25318ac819d7be0fe18a9961190fdffe1052426fd4ae00000000000000000000a8e587bdff867418ab55810792a96c46

## USB Characteristics
- **USB version**: USB 3.2 Gen 1 (SuperSpeed)
- **Negotiated speed**: 5 Gb/s
- **bcdUSB**: 3.20
- **Max packet size (EP0)**: 9 bytes
- **Power mode**: Bus-powered
- **Max power draw**: 896 mA

## Device Class
- **Interface class**: 08 — Mass Storage
- **Subclass**: 06 — SCSI transparent command set
- **Protocol**: 80 — Bulk-Only Transport (BOT)

## Functional Role
- USB flash storage device
- Removable mass storage
- No HID or radio functionality

## Classification Summary
**Category**: USB Mass Storage Device
**Subcategory**: USB 3.x Flash Drive
**Criticality**: Low (non real-time device)

Extraction complète :

• Vendor ID et Product ID
• Nom commercial et modèle
• Marque (manufacturer)
• Numéro de série
• Version USB
• Vitesse de connexion
• Classe USB, sous-classe et protocole
• Catégorie fonctionnelle
• Notes sur le rôle, la performance, etc.

Nommage des fichiers

Le parser peut extraire les IDs USB depuis le nom de fichier :

• ID_0781_55ab.md → Vendor: 0x0781, Product: 0x55ab
• id_0b05_17cb.md → Vendor: 0x0b05, Product: 0x17cb
• ID_046d_c52b.md → Vendor: 0x046d, Product: 0x c52b

Détection automatique du type

Le parser détecte automatiquement le type de périphérique depuis la description :

Mots-clés détectés	Type assigné
souris, mouse	USB / Souris
clavier, keyboard	USB / Clavier
wifi, wireless	WiFi / Adaptateur WiFi
bluetooth	Bluetooth / Adaptateur Bluetooth
usb flash, clé usb, flash drive	USB / Clé USB
dongle	USB / Dongle

Extraction de la marque

Les marques courantes sont détectées automatiquement :

• Logitech
• SanDisk
• Ralink
• Broadcom
• ASUS
• Realtek
• TP-Link
• Intel
• Samsung
• Kingston
• Corsair

Utilisation

Via l'interface web

1. Accédez à http://localhost:8087/peripherals.html
2. Cliquez sur "Importer .md"
3. Sélectionnez votre fichier .md
4. Cliquez sur "Importer"
5. Le formulaire d'ajout s'ouvre avec les données pré-remplies
6. Vérifiez et complétez les informations
7. Enregistrez

Via l'API

curl -X POST http://localhost:8007/api/peripherals/import/markdown \
  -F "file=@/path/to/ID_0781_55ab.md"

Réponse :

{
  "success": true,
  "filename": "ID_0781_55ab.md",
  "parsed_data": {
    "nom": "SanDisk 3.2 Gen1 USB Flash Drive",
    "type_principal": "USB",
    "sous_type": "Clé USB",
    "marque": "SanDisk",
    "modele": "3.2Gen1",
    "numero_serie": "040123d47e7a...",
    "description": "SanDisk Corp. SanDisk 3.2Gen1",
    "caracteristiques_specifiques": {
      "vendor_id": "0x0781",
      "product_id": "0x55ab",
      "usb_version": "USB 3.2 Gen 1 (SuperSpeed)",
      "usb_speed": "5 Gb/s",
      "bcdUSB": "3.20",
      "max_power": "896 mA",
      "interface_class": "08",
      "interface_class_name": "Mass Storage",
      "category": "USB Mass Storage Device",
      "subcategory": "USB 3.x Flash Drive"
    }
  },
  "suggested_peripheral": {
    "nom": "SanDisk 3.2 Gen1 USB Flash Drive",
    "type_principal": "USB",
    "sous_type": "Clé USB",
    "marque": "SanDisk",
    "modele": "3.2Gen1",
    "numero_serie": "040123d47e7a...",
    "description": "SanDisk Corp. SanDisk 3.2Gen1",
    "caracteristiques_specifiques": { ... },
    "etat": "Neuf",
    "quantite_totale": 1,
    "quantite_disponible": 1
  }
}

Sections reconnues

Le parser reconnaît les sections markdown suivantes :

• ## Description - Description générale du périphérique
• ## Identification - Vendor/Product ID, nom commercial, marque, modèle, S/N
• ## USB Characteristics - Version USB, vitesse, alimentation
• ## Device Class - Classe, sous-classe, protocole USB
• ## Functional Role - Rôle fonctionnel (ajouté aux notes)
• ## Performance Notes - Notes de performance
• ## Power & Stability Considerations - Recommandations d'alimentation
• ## Recommended USB Port Placement - Emplacement recommandé
• ## Typical Use Cases - Cas d'usage typiques
• ## Operating System Support - Support OS
• ## Classification Summary - Catégorie et sous-catégorie

Les sections non listées ci-dessus sont ignorées.

Caractéristiques spécifiques

Les informations USB techniques sont stockées dans le champ JSON caracteristiques_specifiques :

{
  "vendor_id": "0x0781",
  "product_id": "0x55ab",
  "usb_version": "USB 3.2 Gen 1",
  "usb_speed": "5 Gb/s",
  "bcdUSB": "3.20",
  "max_power": "896 mA",
  "interface_class": "08",
  "interface_class_name": "Mass Storage",
  "interface_subclass": "06",
  "interface_subclass_name": "SCSI transparent command set",
  "interface_protocol": "80",
  "interface_protocol_name": "Bulk-Only Transport (BOT)",
  "category": "USB Mass Storage Device",
  "subcategory": "USB 3.x Flash Drive"
}

Exemple de workflow complet

1. Créer un fichier de spécification

Créez ID_046d_c52b.md :

# USB Device ID 046d_c52b

## Description
Logitech Unifying Receiver – Dongle clavier/souris

2. Importer via l'API

curl -X POST http://localhost:8007/api/peripherals/import/markdown \
  -F "file=@ID_046d_c52b.md"

3. Le backend analyse et retourne

{
  "success": true,
  "filename": "ID_046d_c52b.md",
  "suggested_peripheral": {
    "nom": "Logitech Unifying Receiver – Dongle clavier/souris",
    "type_principal": "USB",
    "sous_type": "Dongle",
    "marque": "Logitech",
    "caracteristiques_specifiques": {
      "vendor_id": "0x046d",
      "product_id": "0xc52b"
    },
    "etat": "Neuf",
    "quantite_totale": 1,
    "quantite_disponible": 1
  }
}

4. Frontend pré-remplit le formulaire

L'utilisateur vérifie et complète :

• Prix d'achat
• Emplacement
• Photos
• Rating

5. Sauvegarde dans la base de données

Le périphérique est créé avec toutes les informations extraites.

Gestion des erreurs

Fichier non .md

{
  "detail": "Only markdown (.md) files are supported"
}

Encodage invalide

{
  "detail": "File encoding error. Please ensure the file is UTF-8 encoded."
}

Format invalide

{
  "detail": "Failed to parse markdown file: ..."
}

Fichiers d'exemple

Des fichiers d'exemple se trouvent dans le dossier fichier_usb/ :

ls fichier_usb/
ID_0781_55ab.md      # Format détaillé
ID_0b05_17cb.md      # Format simple
ID_046d_c52b.md      # Logitech dongle
ID_148f_7601.md      # Adaptateur WiFi
...

Code source

• Parser backend : backend/app/utils/md_parser.py
• Endpoint API : backend/app/api/endpoints/peripherals.py
• Frontend modal : frontend/peripherals.html
• JavaScript handler : frontend/js/peripherals.js

---

Note : Cette fonctionnalité complète l'import USB (lsusb -v) pour permettre l'import de spécifications pré-formatées en markdown.