Apple-ADB-Ressurector/KEYBOARD_CV_README.md

Clavier Musical CV/GATE Polyphonique pour STM32F3 Discovery

Vue d'ensemble

Cette fonctionnalité transforme votre clavier Apple ADB en synthétiseur polyphonique avec sorties CV/GATE ! Le système utilise une approche innovante :

• CV1 : Voix principale (touches blanches ASDFGHJ)
• CV2 : Voix harmonique (touches noires + numériques)
• Modulation de pitch : Les mouvements de souris X/Y modulent finement les CV
• GATE commun : Signal de déclenchement pour les deux voix

Configuration matérielle

Sorties utilisées (système intégré souris+clavier)

• CV1 (PA4) : Voix principale + modulation par mouvement X souris
• CV2 (PA5) : Voix harmonique + modulation par mouvement Y souris
• GATE (PA0) : Signal de déclenchement commun aux deux voix

Comportement révolutionnaire

• Variables partagées : Le clavier modifie les mêmes variables current_cv1_value et current_cv2_value que la souris
• Modulation cumulative : Souris ajoute sa modulation par-dessus les notes du clavier
• CV de base : Clavier définit la hauteur de note de base
• Pitch bend : Souris module cette hauteur en temps réel
• GATE intelligent : Actif tant qu'au moins une touche est pressée
• Polyphonie partielle : Deux voix indépendantes avec modulation croisée

Mapping des touches

Layout "Synthétiseur Polyphonique"

Le mapping suit une logique musicale de voix principales + harmoniques :

Voix principale (CV1) - Touches blanches

[A] [S] [D] [F] [G] [H] [J]  → CV1 + modulation X
 Do  Ré  Mi  Fa Sol La  Si   (voix de base)

Voix harmonique (CV2) - Touches noires et numériques

[Q] [W]     [R] [T] [Y]     → CV2 + modulation Y
Do# Ré#     Fa# Sol# La#    (harmoniques)

[1] [2] [3] [4] [5] [6] [7] → CV2 + modulation Y  
Do  Ré  Mi  Fa Sol La  Si  (leads octave +1)

Modulation hybride clavier + souris

Clavier A (Do) → current_cv1_value = 2048 (note de base)
Souris X +100  → current_cv1_value += 100 (pitch bend)
           ↓
     Résultat final sur CV1 : 2148 (note + modulation)

Clavier Q (Do#) → current_cv2_value = 2082 (note de base)  
Souris Y -50    → current_cv2_value -= 50 (pitch bend)
            ↓
     Résultat final sur CV2 : 2032 (note + modulation)

Spécifications techniques

Notes MIDI

• Do central (C4) : Note MIDI 60 = ~2.0V
• Plage : C4 à B5 (notes 60 à 83)
• Standard : 1V/octave (limité par 3.3V du STM32)

Conversion CV

// Formule de conversion MIDI → DAC
CV_value = (midi_note * 4095) / 120

Table de correspondance avec modulation

Touche	Note	MIDI	CV base	Sortie	Modulation
A	Do	60	2.0V	CV1	Souris X
S	Ré	62	2.1V	CV1	Souris X
D	Mi	64	2.2V	CV1	Souris X
F	Fa	65	2.2V	CV1	Souris X
G	Sol	67	2.3V	CV1	Souris X
H	La	69	2.4V	CV1	Souris X
J	Si	71	2.4V	CV1	Souris X
Q	Do#	61	2.1V	CV2	Souris Y
W	Ré#	63	2.2V	CV2	Souris Y
1	Do	72	2.5V	CV2	Souris Y
2	Ré	74	2.5V	CV2	Souris Y

Utilisation

Activation

La fonctionnalité est automatiquement active quand KEYBOARD_CV_ENABLED est défini.

Jeu hybride clavier+souris

1. Pressez une touche principale (ASDFGHJ) → current_cv1_value = note de base
2. Pressez une touche harmonique (QWERTY + 1234567) → current_cv2_value = note de base
3. Bougez la souris X → Modifie current_cv1_value (pitch bend voix principale)
4. Bougez la souris Y → Modifie current_cv2_value (pitch bend voix harmonique)
5. Les deux systèmes → Travaillent sur les mêmes variables partagées !

Monitoring série détaillé

CV1 (voix principale) - Note MIDI: 60 CV: 2048 (1.65V)
[Mouvement souris X] current_cv1_value devient 2156
CV2 (voix harmonique) - Note MIDI: 64 CV: 2185 (1.76V)
[Mouvement souris Y] current_cv2_value devient 2089
GATE ON - Notes actives

Compatibilité synthétiseurs

Eurorack

• Attention : Le STM32 sort 0-3.3V, les modules Eurorack attendent ±5V
• Solution : Ajouter un amplificateur opérationnel pour mise à l'échelle

Synthés vintage

• Compatible directement avec la plupart des synthés attendant 0-5V
• CV/GATE standard reconnu par tous les synthétiseurs modulaires

Circuit d'interface (recommandé)

Pour une utilisation professionnelle avec Eurorack :

STM32 CV → Op-Amp TL072 → Sortie ±5V
         ↑
    Alimentation ±12V
    Résistances de précision

Fonctions disponibles

// Conversion ADB vers MIDI
uint8_t hid_keyboard_adb_to_midi_note(uint8_t adb_key);

// Conversion MIDI vers CV DAC
uint16_t hid_keyboard_midi_note_to_cv(uint8_t midi_note);

// Traitement principal CV/GATE
void hid_keyboard_process_cv_output(hid_key_report* report);

Personnalisation

Changer le mapping

Modifiez le tableau adb_to_midi_map[] dans hid_keyboard.cpp :

{0x00, KEY_NOTE_C4},      // A = Do
{0x01, KEY_NOTE_D4},      // S = Ré
// Ajoutez vos mappings...

Transposition

Changez la note de référence :

#define KEY_NOTE_C4     72    // Do une octave plus haut

Courbe CV personnalisée

Modifiez la fonction hid_keyboard_midi_note_to_cv() pour des courbes exponentielles, tempérament inégal, etc.

Limitations actuelles

• Polyphonie limitée : Deux voix simultanées maximum (CV1 + CV2)
• Pas de vélocité : GATE binaire uniquement
• Plage limitée : 0-3.3V (2.75 octaves environ)
• Modulation fixe : Sensibilité de pitch bend non configurable
• GATE partagé : Une seule enveloppe pour les deux voix

Améliorations futures

• Vélocité via PWM du GATE
• Portamento/glide entre notes par voix
• Modulation configurable (intensité, courbes)
• GATE indépendant par voix
• Modes gammes/accords préprogrammés
• Séquenceur polyphonique intégré
• LFO intégré pour modulation auto

Test et debug

Utilisez le moniteur série pour voir l'activité polyphonique en temps réel :

CV1 (voix principale) - Note MIDI: 60 Base CV: 2048 Modulé: 2156 (1.73V)
CV2 (voix harmonique) - Note MIDI: 64 Base CV: 2185 Modulé: 2089 (1.68V)
GATE ON - Notes actives
CV1 OFF - Voix principale arrêtée
GATE OFF - Aucune note

Schéma de patch recommandé :

CV1 → VCO1 (Bass/Lead) → VCF1 → VCA1 ┐
                                      ├─→ Mix → Out
CV2 → VCO2 (Harmony)   → VCF2 → VCA2 ┘
 
GATE → EG (enveloppe commune) → VCA1 & VCA2

Modulation:
Souris X → Fine tune VCO1
Souris Y → Fine tune VCO2

Votre clavier Apple ADB est maintenant un synthétiseur polyphonique professionnel avec modulation en temps réel ! 🎹🔥⚡