Clavier macro multifonction SuperKey¶

Qu'est-ce que SuperKey ?¶

SiFliSparks/SuperKey est une implémentation de référence d'un clavier macro multifonction à écrans, basée sur le SF32LB52. Son firmware open source fonctionne sous RT-Thread et LVGL v9 ; il pilote trois écrans LCD GC9107 de 128 × 128, trois LED RGB, quatre touches physiques, un encodeur rotatif et un capteur de température/humidité SHT30, et se connecte à un ordinateur comme périphérique USB composite HID/CDC.

SuperKey est plus qu'un pavé de raccourcis. Cette référence opérationnelle combine les fonctions suivantes :

• sortie USB HID pour clavier et commandes multimédias ;
• données de performances, météo, configuration et état d'alimentation de l'ordinateur via USB CDC ou UART à 1 Mbit/s ;
• pages réparties sur trois écrans pour la supervision des performances, la météo, l'horloge, les utilitaires, la musique et les mappages personnalisés ;
• application compagnon SuperKeyHub qui collecte les données de l'hôte, configure les fonctions et déclenche les mises à jour du firmware ;
• matériel reproductible grâce au design ouvert sf32-keyboard.

Pourquoi l'implémentation SF32 ?¶

SuperKey requiert des graphismes, plusieurs écrans, un périphérique USB composite, des touches et un encodeur, des capteurs, des effets RGB, un système de fichiers et éventuellement l'audio. Le SF32LB52 exécute ces tâches temps réel sur le MCU ; l'appareil peut ainsi démarrer son interface et fournir les fonctions HID de base même si l'application compagnon n'est pas lancée. L'application hôte traite la télémétrie de l'ordinateur et les données Internet, qui relèvent plutôt du système d'exploitation de bureau.

Cette répartition convient aux contrôleurs de bureau, claviers de productivité, panneaux d'état et IHM compactes, mais crée des dépendances explicites. Les affichages de données avancés nécessitent l'application compagnon, des pilotes et des API externes ; les versions du firmware et de l'hôte doivent rester compatibles ; les pertes USB, la veille de l'hôte et les configurations endommagées nécessitent des tests de récupération distincts.

Résultat, portée et critères d'entrée¶

Résultat attendu : reproduire une configuration SuperKey avec des versions figées, valider HID, CDC, l'interface sur trois écrans, les entrées, les capteurs et la reprise après veille, puis ne modifier qu'une catégorie de comportement à la fois en conservant des preuves de compilation, de communication et de non-régression pour la revue produit.

Cette page ne démontre pas que le circuit imprimé ouvert est prêt pour la production, ni que toutes les sources de télémétrie PC, tous les services météo, ponts série, hôtes USB ou systèmes d'exploitation sont compatibles. Les cours boursiers, les données météo et les données de performance peuvent dépendre de la version de SuperKeyHub, d'API tierces, des autorisations système et du matériel hôte.

Avant de commencer, préparez :

• matériel SuperKey assemblé selon le design ouvert, avec trois écrans LCD GC9107, des touches, un encodeur et une connexion USB de données ;
• un ordinateur sous Windows 10/11 pour le parcours principal documenté. Le dépôt SuperKeyHub annonce la prise en charge de Windows et macOS ; validez toutefois le flashage de la carte, la communication CDC et la récupération sur l'OS choisi ;
• une version de SuperKeyHub compatible avec le firmware ;
• un environnement SiFli-SDK, le sous-module SDK récupéré récursivement et une connexion de flashage/récupération opérationnelle ;
• si la météo est dans le périmètre, une clé API QWeather valide, l'API Host et la configuration de ville ;
• un rapport de test couvrant l'énumération USB, les journaux série, le comportement des touches, l'état des écrans et la récupération après veille.

Spécifications matérielles et logicielles¶

Spécification matérielle¶

Spécification logicielle¶

Choisir une configuration de référence prise en charge¶

La liste des releases amont inclut le firmware v1.4.2, qui constitue un point de départ figé. Les sources citées ne précisent pas de version SuperKeyHub compatible. Choisissez et figez une release ou un commit de Hub, testez avec v1.4.2 la télémétrie, la configuration et DFU, puis consignez le couple testé au lieu de déduire la compatibilité des numéros de version.

La CI amont utilise la cible suivante. Installez et exportez l'environnement SiFli-SDK avant d'exécuter ces commandes localement :

git clone --recursive https://github.com/SiFliSparks/SuperKey.git
cd SuperKey/SiFli-SDK
./install.sh
. ./export.sh
cd ../app/project
scons --board=sf32lb52-superkey --board_search_path="../boards" -j8

Sous Windows, utilisez les scripts PowerShell d'installation et d'environnement SiFli-SDK correspondants. Le niveau de parallélisme peut varier, mais le nom de la carte, le chemin de recherche des fichiers de carte et les révisions des sous-modules doivent figurer dans le rapport de compilation.

Étapes du projet¶

Architecture système et dépendances¶

flowchart LR
    U["Utilisateur\ntouches et encodeur rotatif"] --> F["Firmware SF32LB52\nRT-Thread + LVGL v9"]
    F --> D["Trois LCD GC9107\nLED RGB, SHT30, audio facultatif"]
    F -->|"USB HID\névénements clavier et multimédia"| P["Hôte Windows / macOS"]
    P -->|"USB CDC ou UART 1 Mbit/s\ntélémétrie, météo, configuration, mode d'alimentation"| F
    H["SuperKeyHub\ncollecte, configuration, mise à jour"] <--> P
    H <--> A["API météo et sources de télémétrie de l'hôte"]
    H -->|"DFU CDC"| F

Répartissez les pannes en cinq domaines : matériel/écran du périphérique, entrées HID, canal de données CDC/UART, application compagnon/autorisations système et services de données externes. Un panneau météo vide n'indique pas nécessairement un défaut du firmware ; la clé API, l'API Host, la configuration de la ville ou l'envoi des données peuvent être en cause.

Étape 1 — Établir la référence intacte¶

Objectif : vérifier l'ensemble du parcours de référence avant de modifier le code.

1. Suivez les instructions d'assemblage amont pour vérifier l'orientation des câbles LCD, les interrupteurs, l'encodeur, le boîtier et le connecteur USB ; consignez les révisions de la PCB et du firmware.
2. Installez la version correspondante de SuperKeyHub. Vérifiez l'énumération du périphérique, puis testez séparément HID et CDC.
3. Configurez les identifiants météo, le port et la liaison série à 1 Mbit/s. Consignez le comportement sans l'application compagnon, puis connectez-la et activez l'envoi de données.
4. Vérifiez la navigation sur les trois écrans, le mappage des touches, les commandes multimédias, l'encodeur, les données SHT30, les effets LED et un cycle complet d'actualisation de la télémétrie.
5. Effectuez un démarrage à froid et répétez les tests. Enregistrez des photos de l'interface, les journaux de l'application et du périphérique ainsi que le résultat de la requête de version.

Éléments à conserver : révision matérielle, tag/commit du firmware, commit du SDK, version de l'application compagnon, système d'exploitation, configuration du port et de l'API, énumération USB, journaux, affichages et relevé des entrées.

Critère de sortie du point de contrôle 1 : deux démarrages à froid valident les entrées HID, l'actualisation des données CDC et l'interaction avec les trois écrans ; chaque domaine de panne peut être identifié par les journaux ou un état observable.

Étape 2 — Valider les limites de défaillance et de récupération¶

Objectif : vérifier que les interruptions courantes en environnement de bureau ne réduisent pas l'appareil à un démonstrateur qu'il faut flasher à nouveau pour récupérer.

Critère de sortie du point de contrôle 2 : chaque panne applicable dispose d'un résultat reproductible de détection et de récupération, sans réparation manuelle d'état non documentée.

Étape 3 — Établir une base de code reproductible¶

Objectif : permettre à un second ingénieur de compiler, flasher l'image et répéter l'étape 2 depuis un checkout propre.

1. Clonez récursivement et consignez les commits de SuperKey et de SiFli-SDK.
2. Compilez proprement avec sf32lb52-superkey et le chemin de recherche ../boards.
3. Conservez le journal de compilation, les sorties mémoire/partition, le script de flashage, les images générées et le journal série.
4. Recompilez sur un second ordinateur ou après suppression du répertoire de compilation, flashez le même matériel et répétez les tests de non-régression principaux.

Critère de sortie du point de contrôle 3 : aucun fichier non suivi, artefact obsolète ou remplacement manuel de binaire n'est nécessaire pour produire une image qui réussit l'étape 2.

Étape 4 — Adapter une variable produit à la fois¶

Objectif : valider le périmètre des modifications tout en préservant la référence fonctionnelle.

Critère de sortie du point de contrôle 4 : la modification est relue, l'image d'origine peut être restaurée et les tests HID, CDC, écran, entrées, veille et récupération réussissent.

Étape 5 — Revue de préparation produit¶

Avant de concevoir du matériel spécifique ou de lancer une présérie, l'équipe doit répondre aux questions suivantes :

• Le produit dépendra-t-il encore de SuperKeyHub, de privilèges administrateur et d'un service météo tiers ? Qui est responsable de ces dépendances ?
• Comment les versions du firmware, du compagnon et du protocole sont-elles gérées, et comment les combinaisons invalides sont-elles bloquées ?
• Quelles combinaisons de PC cibles, hubs USB, câbles, politiques de veille et logiciels de sécurité ont été testées ?
• Quelle est la mémoire utilisée, la température et le courant lorsque les trois écrans, les données USB, les LED, les capteurs et l'audio facultatif fonctionnent simultanément ?
• Comment restaurer la configuration, les mappages de touches et l'état de mise à jour après une coupure d'alimentation ou un stockage endommagé ?
• La PCB ouverte, le boîtier, les polices, icônes, musiques et API tierces sont-ils sous licence pour la distribution prévue ?

Critère de sortie du point de contrôle 5 : chaque risque résiduel a un responsable, des preuves et une décision de traitement ; l'équipe a décidé de poursuivre, différer ou arrêter.

Passage à la conception du produit¶

Transférez à la conception le choix du SF32 et de la mémoire, les descripteurs USB HID/CDC, les connexions des trois écrans et du rétroéclairage, les interfaces d'entrée et de capteur, la politique d'alimentation et de veille, les partitions du système de fichiers et des mises à jour, le protocole compagnon, les points de test en production et le chemin de récupération validé. Consultez SF32LB52x, le guide de conception matérielle SF32LB52x, SiFli-SDK : compiler, flasher et surveiller la sortie série et Conception pour la production.

Sources de référence¶

• Dépôt du firmware SiFliSparks/SuperKey
• Version SuperKey v1.4.2
• Dépôt de l'application compagnon SiFliSparks/SuperKeyHub
• Documentation du projet SuperKey
• Matériel ouvert sf32-keyboard
• OpenSiFli/SiFli-SDK

Dernière mise à jour: 2026-10-21