TODO projet SHORDS¶

Ce document sert de fil conducteur pour les évolutions importantes du projet.

Légende complexité¶

Faible: ajout localisé, faible risque d'impact
Moyenne: plusieurs fichiers/modules, tests matériels requis
Élevée: architecture à définir, protocole ou stockage à structurer
Très élevée: impact système important, risque élevé, outillage côté PC + firmware

1. Utiliser le port SD du Teensy¶

Note d'architecture — stratégie mémoire pour les samples¶

Constat actuel
La mémoire audio temps réel est allouée via AudioMemory(80).
Des buffers de drums générés occupent déjà de la RAM classique.
Les petits samples de harpe actuels sont en flash/PROGMEM, ce qui est plus économique que la RAM.
Décision recommandée
Samples très courts (attaques, one-shots très brefs): flash/PROGMEM
Samples moyens ou longs (drums variés, instruments, boucles): SD en streaming
RAM: uniquement pour petits caches temporaires, métadonnées, ou préchargement très ciblé
Pourquoi
Stocker une banque complète en RAM n'est pas la voie la plus simple à moyen terme
La vraie difficulté n'est pas seulement la quantité de RAM, mais la coexistence avec l'audio temps réel
La SD est plus adaptée aux contenus évolutifs et volumineux
Optimisations possibles si besoin
Supprimer ou réduire les buffers RAM non indispensables
Déplacer les samples statiques vers const/PROGMEM
Préférer des samples mono, courts, et à fréquence modérée au départ
Commencer par un seul lecteur de sample simple avant la polyphonie

1.1 Journaliser des statistiques d'utilisation¶

[ ] Définir quelles stats enregistrer — Complexité: Moyenne
Temps total allumé
Nombre de boots
Temps de jeu cumulé
Accord/touche les plus joués
Utilisation des menus / profils
Erreurs matérielles détectées (I2C, SD, audio)
[ ] Définir le format de stockage — Complexité: Moyenne
Option simple: fichier texte/CSV
Option robuste: JSON compact ou binaire
Prévoir rotation ou taille max des logs
[ ] Créer un module stats dédié — Complexité: Moyenne
Initialisation SD au boot
Bufferisation des événements
Écriture périodique pour éviter d'user la carte SD
[ ] Instrumenter les événements utiles — Complexité: Moyenne
Boot/extinction
Déclenchement de notes/accords
Changement de menu
Chargement/sauvegarde de profils
[ ] Afficher un résumé dans l'UI — Complexité: Moyenne
Écran "Stats"
Valeurs clés lisibles rapidement
[ ] Prévoir l'export vers PC — Complexité: Faible
Lecture directe de la SD
Ou extraction via liaison PC/SHORDS

Risques / points d'attention¶

Éviter les écritures trop fréquentes sur la SD
Éviter de bloquer l'audio pendant les accès SD
Gérer le cas "pas de carte SD insérée"

1.2 Lire des samples depuis la SD pour la musique¶

[ ] Définir les usages des samples — Complexité: Moyenne
Drums
Attaques de harpe
One-shots
Boucles / backing layers
[ ] Choisir la stratégie de lecture audio — Complexité: Élevée
AudioPlaySdWav si .wav
Préchargement partiel en RAM si besoin de réactivité
Gestion mono/stéréo et fréquence d'échantillonnage
[ ] Définir l'organisation des fichiers sur la SD — Complexité: Faible
Exemple: /samples/drums/, /samples/harp/, /samples/boot/
Convention de nommage claire
[ ] Créer un gestionnaire de samples — Complexité: Élevée
Scan des dossiers
Chargement des métadonnées
Sélection d'un sample par instrument/menu
[ ] Intégrer les samples au moteur audio — Complexité: Élevée
Remplacement ou mix avec les oscillateurs actuels
Réglage du volume et du routage
Gestion des voix simultanées
[ ] Créer un menu de sélection des banques — Complexité: Moyenne
Choix des kits drums
Choix d'instruments harpe
[ ] Tester les performances audio + SD — Complexité: Élevée
Latence au déclenchement
Risque de glitch/clicks
Compatibilité avec le visualizer

Risques / points d'attention¶

Lecture SD et audio temps réel peuvent se gêner
Les formats doivent rester simples au début (wav PCM)
Il faudra probablement commencer par les drums, plus simples que la harpe multi-voix

Ordre conseillé¶

Initialisation SD stable
Lecture d'un .wav de test
Intégration sur un seul son drum
Généralisation aux autres instruments

2. Mettre en place une communication PC ↔ SHORDS¶

Objectif général¶

Créer un lien fiable entre le PC et le SHORDS pour la configuration, l'échange de données et la maintenance.

2.1 Choisir le meilleur mode de communication¶

[ ] Évaluer les options de transport — Complexité: Moyenne
USB Serial: simple, robuste, natif
USB MIDI SysEx: pertinent musicalement, mais plus contraignant
HID personnalisé: puissant mais plus complexe
Stockage de masse: peu adapté si configuration temps réel
[ ] Choisir une stratégie initiale — Complexité: Faible
Recommandation de départ: USB Serial + protocole simple
[ ] Définir un protocole d'échange — Complexité: Élevée
Messages texte JSON
ou protocole binaire compact
Commandes: lecture config, écriture config, état courant, logs, update
[ ] Créer un module firmware link / transport — Complexité: Moyenne
Réception
Parsing
Réponses
Gestion d'erreurs / timeouts

Pourquoi USB Serial semble le meilleur point de départ¶

Facile à déboguer
Facile à utiliser depuis un outil PC simple
Suffisant pour configuration, logs et préparation des updates
Évolutif vers un outil desktop plus complet plus tard

2.2 Rebind des touches / changement de range d'accords¶

[ ] Définir ce qui peut être rebindé — Complexité: Moyenne
Matrice d'accords complète
Ranges / banques d'accords
Mapping harpe
Actions joystick / raccourcis éventuels
[ ] Externaliser le mapping actuel — Complexité: Moyenne
Sortir les tables du code en structure configurable
Prévoir sérialisation vers fichier ou EEPROM/SD
[ ] Créer un format de preset de mapping — Complexité: Moyenne
JSON lisible
Versionné
Import/export simple
[ ] Ajouter les commandes PC pour lire/écrire le mapping — Complexité: Moyenne
GET_MAPPING
SET_MAPPING
SAVE_MAPPING
LOAD_MAPPING
[ ] Créer un validateur de mapping — Complexité: Moyenne
Éviter les configs invalides
Vérifier plages de notes et cohérence musicale
[ ] Prévoir stockage persistant — Complexité: Moyenne
EEPROM pour config active
SD pour presets multiples
[ ] Créer un outil PC minimal — Complexité: Élevée
Option 1: script Python/CLI
Option 2: petite app desktop
Visualisation claire de la matrice et des notes

Ordre conseillé¶

Rendre le mapping sérialisable
Lire/écrire le mapping par USB Serial
Sauvegarder sur SD/EEPROM
Ajouter une interface PC conviviale

2.3 Système de mise à jour du Teensy¶

[ ] Définir ce que signifie “mise à jour” — Complexité: Élevée
Envoi automatique d'un nouveau firmware depuis le PC
Mise à jour de contenus SD seulement
Mise à jour hybride firmware + assets
[ ] Étudier les contraintes du Teensy 4.1 — Complexité: Élevée
Le flash/reboot n'est pas aussi libre qu'un MCU avec bootloader custom complet
Le workflow Teensy officiel passe souvent par Teensy Loader côté PC
[ ] Choisir la stratégie la plus réaliste — Complexité: Très élevée
Option A recommandée: outil PC qui automatise le flash via Teensy Loader
Option B: mise à jour des assets/configs via USB + SD, firmware séparé
[ ] Séparer firmware et contenus — Complexité: Moyenne
Firmware = code compilé
Assets = samples, mappings, presets, logos, etc.
[ ] Construire un outil de release/update PC — Complexité: Très élevée
Détection du SHORDS
Vérification version firmware
Copie des fichiers SD
Lancement du flash firmware si nécessaire
[ ] Ajouter versionnement côté firmware — Complexité: Faible
Numéro de version
Réponse à commande GET_VERSION
[ ] Prévoir récupération en cas d'échec — Complexité: Élevée
Message clair côté PC
Processus de reflash manuel documenté

Recommandation pratique¶

Commencer par un système en 2 couches: 1. Update des fichiers SD/configs via liaison PC 2. Update firmware via outil PC qui pilote le workflow Teensy standard

C'est beaucoup plus réaliste qu'un auto-updater 100% embarqué.

Priorités recommandées¶

Roadmap proposée¶

v0.2 — Fondations stockage + liaison PC¶

[ ] Initialiser la SD proprement
[ ] Ajouter un protocole USB Serial simple
[ ] Ajouter GET_VERSION, GET_STATUS, GET_MAPPING
[ ] Poser les bases d'un mapping sérialisable

v0.3 — Config utilisateur + stats¶

[ ] Sauvegarder/charger le mapping depuis SD
[ ] Rebind des touches depuis PC
[ ] Journaliser les stats d'utilisation sur SD
[ ] Ajouter un premier écran ou export de stats

v0.4 — Premiers samples utilisables¶

[ ] Lire un .wav de test depuis SD
[ ] Remplacer un premier son drum par sample
[ ] Ajouter une structure de dossiers /samples/...
[ ] Vérifier qu'il n'y a pas de glitch audio

v0.5 — Outil PC et contenus¶

[ ] Outil PC minimal de configuration
[ ] Gestion de presets/mappings multiples
[ ] Sélection de banques de samples

v0.6+ — Maintenance et distribution¶

[ ] Outil PC de mise à jour des contenus
[ ] Automatisation du workflow de flash firmware
[ ] Gestion de versions et compatibilité firmware/assets

Phase 1 — Fondations utiles rapidement¶

[ ] Initialiser la SD proprement
[ ] Ajouter un protocole USB Serial simple
[ ] Exposer GET_VERSION, GET_STATUS, GET_MAPPING
[ ] Sauvegarder/charger un mapping depuis SD

Phase 2 — Fonctionnalités visibles¶

[ ] Rebind des touches depuis PC
[ ] Journalisation des stats sur SD
[ ] Lecture d'un premier sample drum depuis SD

Phase 3 — Industrialisation¶

[ ] Outil PC de configuration
[ ] Gestion de banques de samples
[ ] Outil PC de mise à jour firmware + contenus

Résumé de complexité¶

Sujet	Complexité estimée	Remarques
Stats sur SD	Moyenne	Très faisable rapidement
Samples sur SD	Élevée	Attention aux contraintes temps réel
Communication PC ↔ SHORDS	Moyenne à Élevée	USB Serial conseillé au départ
Rebind des touches	Moyenne	Dépend du format de mapping
Mise à jour du Teensy	Très élevée	À traiter avec un outil PC dédié

Décision d'architecture recommandée¶

Communication PC ↔ SHORDS: USB Serial
Stockage de config/presets/samples: carte SD
Mappings utilisateur: fichiers versionnés sur SD + config active en mémoire
Mise à jour firmware: orchestrée côté PC, pas directement par le firmware seul