Portage QMK raté, bootloader et assignation des pins

J’ai quasi réussi à adapter le firmware QMK au MCU du Ironclad. Il ne reste que 4 colonnes qui refusent de s’allumer mais l’intégralité des touches de la matrice fonctionnent correctement désormais.

” Euh. J’ai pas compris, tu peux nous expliquer les termes barbares utilisés dans ton titre et en introduction ? “

Ah oui, j’étais complètement noyé par la charge de travail, je n’ai pas eu l’occasion de vous mettre au courant de mes avancées. Dernièrement, au mois de février, j’avais décidé de développer le firmware de mes propres mains, mais face à la charge de travail et la quantité énorme d’informations à ingurgiter, je n’ai pas réussi à avancer aussi vite que prévu.

J’ai donc choisi une méthode intermédiaire à celle d’un développement de zéro, celle d’adapter un firmware open source à mon clavier.

Je vais commencer par écrire un petit glossaire pour que vous suivez ce qui est en train de se passer :

Firmware : je pense que vous vous en doutez, votre clavier ne fonctionne pas par la magie du saint esprit. L’éclairage, la remontée des informations vers l’ordinateur sont traités par un logiciel embarqué dans la puce du clavier. Ce logiciel c’est ce qu’on appelle le firmware.

Si je devais faire une grosse analogie, le firmware est au clavier ce que Windows est au PC. C’est grosso modo le “système d’exploitation” du clavier.

MCU :

“Marvel Cinematic Universe ?”

Eeeerh nope, c’est sans doute le premier résultat qui va sortir si vous tapez le terme MCU sur Google, mais MCU correspond à “microcontroller unit” dans notre cas. Je disais que le firmware correspondait au système d’exploitation du clavier, eh bien le MCU correspond au hardware du clavier. C’est une puce embarquant un processeur, de la RAM et une mémoire programmable.

Bien entendu, la quantité de RAM et de mémoire est dans un tout autre ordre de grandeur par rapport à un PC. Par exemple, le Sonix SN32F248B que nous utilisons dans notre clavier n’embarque que 8 ko de RAM et 64 ko de ROM.

QMK : QKM pour Quantum Mechanical Keyboard est un firmware open source, c’est à dire que nous avons directement accès au code source. Je disais dans le point un que le firmware du clavier, c’est l’équivalent du système d’exploitation pour votre PC.

Si je devais continuer dans cette analogie, la solution actuellement utilisée par notre clavier est équivalent à Windows, un logiciel propriétaire.

Et par analogie, QMK serait l’équivalent de Linux, une solution open source.

Bootloader : Toujours la même analogie avec le PC. Votre ordinateur dispose d’un BIOS, pour Basic Input Output System. Notre microcontrôleur qui n’est en fait rien de moins qu’un PC simplifié et miniaturisé possède aussi un BIOS.

Dans le cas où un firmware raté est installé dessus, il suffit de redémarrer sur le BIOS du clavier pour pouvoir réinstaller un firmware au propre.

Ayant terminé le petit glossaire, je vais essayer de vous expliquer comment faire un portage de QMK sur le Ironclad et aussi comment développer votre propre firmware si jamais vous en avez envie.

I. Le bootloader

1.Principe de base du bootloader

Je consacre une première partie au bootloader, qui est selon moi l’élément le plus important dans la mesure où vous allez souvent “bricker” (bloquer) le clavier en faisant des tentatives de portage. J’ai dû bloquer mon propre clavier une bonne cinquantaine de fois avant de faire un truc fonctionnel.

Le bootloader, comme précédemment expliqué, correspond au BIOS du clavier.

Quand vous démarrez normalement le clavier, il exécute le code que vous avez créé. Si vous démarrez le clavier en mode bootloader, dans le cas du SN32F248B, il va charger un code de base, installé lors de la fabrication de la puce et stocké dans une mémoire protégée. Exactement comme le BIOS de votre PC.

Ce code de base va permettre au clavier de se présenter à l’ordinateur. En l’occurrence, il permettra trois choses :

1. Se présenter avec un VID/PID, VID pour Vendor ID et PID pour Product ID. Ce couple de matricule unique à chaque produit, permet d’identifier précisément le périphérique qui est branché dessus.
   
   Le Sonix SN32F248B que nous utilisons prends par la valeur VID:0C45 et PID:7040 en mode bootloader.
   
   Le firmware que vous allez créer peut bien évidemment prendre des valeurs différentes mais en mode bootloader, il prend systématiquement le VID/PID par défaut.
   
2. Dire au PC : “Je suis prêt à recevoir un nouveau programme via la connexion USB.”
   
3. Démarrer le code qui permet de réécrire le contenu du microcontrôleur à partir des informations reçus par le port USB.

Ainsi, une fois que vous démarrer en mode bootloader, le clavier va ignorer le code défectueux précédemment installé et vous pouvez directement installer votre nouveau programme via une simple connexion USB. Le terme exact est “ISP” pour “In System Programming” ou “In Situ Programming”.

2. Accéder au bootloader

Le clavier démarre avec cette séquence :

Le clavier reçoit de l’énergie -> Il exécute le bootloader -> Le bootloader détecte un code utilisateur (firmware) -> Le firmware démarre -> Le firmware permet de présenter le clavier au PC.

Il existe trois méthodes dans notre situation pour faire entrer le clavier en mode bootloader. De la plus simple à la plus barbare.

a. Accéder au bootloader grâce à un signal envoyé par le PC

C’est la méthode standard, actuellement utilisée. Le firmware du clavier contient un petit bout de code, qui une fois appelé par le PC va redémarrer le clavier en mode bootloader.

Ainsi, les MaJ que je vous proposerais dans le futur fonctionneront comme ceci :

• L’installateur appelle le bout de code permettant de basculer le clavier en mode bootloader
• Le clavier se met en mode bootloader
• L’installateur met à jour le firmware. Le nouveau firmware contient ce même bout de code pour basculer en mode bootloader.
• Le clavier est à jour et dispose de ce morceau de code pour une prochaine mise à jour.

b. Accéder au bootloader grâce à une touche enfoncée pendant le démarrage

“Comme pour le BIOS du PC!”

Oui. Exactement, comme pour le BIOS du PC. Dans cette situation, la séquence de démarrage se passe comme ceci :

Le clavier reçoit de l’énergie -> Il exécute le bootloader -> Le bootloader détecte un code utilisateur (firmware) -> Le firmware démarre -> Le firmware détecte une touche enfoncée, et il a été programmé pour basculer en mode bootloader si cette condition est remplie -> Il bascule en bootloader

Je pense que si vous avez suivi les deux premiers points, vous allez me faire la remarque suivante :

“Excuse moi Christophe, mais dans le point a et b, on part du principe que nous avons un firmware qui marche. Au point a, le firmware se présente correctement au PC. Au point b, le firmware fonctionne au moins suffisamment correctement pour détecter la présence d’une touche enfoncée. Que faire si le firmware ne fonctionne pas du tout et que les deux premières méthodes ne marchent pas ? “

Et c’est ce qui m’amène au point c.

c. Accéder au bootloader en court-circuitant un pin

Nous arrivons à la troisième méthode permettant d’accéder au bootloader. Comme vous l’aurez compris, les deux méthodes précédentes nécessitent un firmware fonctionnel. Ce n’est pas toujours le cas. Il nous faut donc une méthode qui fonctionne à coup sûr.

Cette troisième méthode est une condition codée dans le bootloader lors de la fabrication du MCU. Il dit “Si le pin n°3 est relié au GROUND lors du démarrage, je ne sors pas du mode bootloader. “

Ainsi, en court-circuitant ces deux pins :

Le clavier démarrera en mode bootloader de manière certain, ignorant totalement le firmware défectueux.

C’est particulièrement important dans la mesure où cette méthode rend le clavier impossible à bloquer.

Conclusion 1 : ayant présenté les différentes méthodes pour accéder au bootloader, je vais pouvoir passer à la suite, qui est l’assignation des pins du MCU et la structure de la matrice de touches.

II. Fonctionnement d’une matrice et assignation des pins

1. Le principe d’une matrice

Voici un MCU connecté à un interrupteur :

Comme vous pouvez le voir, les pattes 1 et 8 sont connectées à un interrupteur. Quand vous appuyez sur un interrupteur, le circuit est fermée, le MCU détecte une frappe.

Voici un circuit avec 4 interrupteurs :

Nous avons donc besoin de 2 pattes sur le MCU, pour chaque interrupteur. Et si nous comptons correctement, 8 pins pour un clavier avec 4 interrupteurs. Ce qui est très peu, car pour un clavier standard de 105 touches, nous aurions besoin de 210 pins.

La solution trouvée, c’est de créer ce que nous appelons une matrice, c’est à dire un tableau de touches.

Les interrupteurs ne sont plus branchés en direct au MCU mais sont placés sur un tableau. Ensuite nous allons ordonner au MCU de faire un balayage, c’est à dire que nous allons vérifier l’état de l’interrupteur sur chaque case du tableau.

Nous allons faire passer un courant entre la broche 8 et 1. Nous verrons si l’interrupteur A1 est ouvert ou fermé.
Nous allons faire passer un courant entre la broche 8 et 2. Nous verrons si l’interrupteur A2 est ouvert ou fermé.

Nous allons faire passer un courant entre la broche 8 et 3. Nous verrons si l’interrupteur A3 est ouvert ou fermé… Etc etc etc.

Une fois que le MCU arrive à l’interrupteur D4, elle a terminée son cycle complet et recommence à partir de la case A1.

Avec cette méthode, nous avons réussi à faire tenir 16 interrupteurs sur 8 broches seulement. Magique n’est ce pas ?

Et dans le cas d’un clavier pour PC, nous faisons tenir les 105 touches sur 6 rangées et 21 colonnes. Soit 27 broches.

2. Le placement des touches du Ironclad sur la matrice

“Attends, les comptes ne sont pas bons. 6 rangées de 21 colonnes, 6 x 21, c’est 126 touches. Notre clavier n’en comporte que 105, des touches. “

Exactement. Certaines cases du tableau sont vides tout simplement. Il n’y a ni switches, ni connexions. Il n’y a rien.

Je vais vous donner le placement des touches sur la matrice du Ironclad (valable pour le Bane aussi. )

Les cases vides correspondent à rien. Il n’y a simplement pas de contact entre la colonne et la rangée.

3. Placement des LED sur la matrice

Vous l’avez sans doute deviné, si nous pouvons placer des interrupteurs dans un tableau, nous pouvons aussi installer des LED dans le tableau et les allumer une à une pour donner une impression d’animation.

Voici donc le placement des LED du Ironclad dans la matrice :

Un o signale la présence d’une LED. Une case vide signifie l’absence de LED.

4. Assignation des pins au microcontrôleur

Chaque code que vous voyez dans le tableau (CL0, R0, LR0, LB0 etc etc ) correspond à un pin du MCU. Ils sont donc branchés dans un ordre précis au contrôleur. Voici l’ordre de branchement :

Conclusion 2 : Dans cette seconde partie j’ai donc expliqué le principe de fonctionnement d’une matrice et l’assignation des pins. Je vais désormais vous montrer une application concrète de la théorie, le portage de QMK sur le Ironclad.

III. Portage de QMK sur le Ironclad

Je tiens d’abord à remercier CalcProgrammer1 pour son portage de QMK sur les MCU de Sonix. Sans lui, la suite de ce que je décris aurait été totalement impossible.

Mon adaptation de QMK au Ironclad n’étant pas parfait, je vous déconseille fortement (pour ne pas dire TOTALEMENT) d’installer QMK sur votre clavier pour l’instant. Je trouverais un moyen de résoudre le soucis plus tard, mais actuellement, sauf si vous êtes un aventurier prêt à démonter le clavier, n’installez pas QMK. Je refuserais toutes demandes en charge du SAV après une tentative raté tant que je n’ai pas donné un feu vert officiel.

Si toutes les touches marchent, l’éclairage a encore un problème et quatre des colonnes de LED du clavier ne fonctionnent pas. Et il est encore impossible de revenir au firmware d’origine sans démonter le clavier.

1. Installation de QMK MSys

Cet article de mon blog étant particulièrement long, je vais essayer de raccourcir au maximum. Vous trouverez le guide d’installation détaillé sur cette page :

2. Ajout des fichiers de portage du Ironclad

L’adaptation du firmware n’étant pas parfaitement au point, je n’ai pas mis en place un fork du projet. Je me contente de vous laisser télécharger les fichiers :

J’ai effectué l’adaptation en me basant sur celui du Aukey KMG12 et en réassignant les pins. L’assignation des pins est déjà la bonne.

Ce que vous devez faire :

• Télécharger le fichier
• Aller créer un dossier nommé “test” dans :

C:\Users\[nom d’utilisateur]\qmk_firmware\keyboards

• Copier dans le dossier test les fichiers présent dans le fichier ZIP téléchargé
• Exécuter QMK MSYS avec et entrer dans la console “qmk compile -j 8 -kb test/kmg12 -km default”
  Vous obtenez un fichier .bin dans le dossier “C:\Users\[nom d’utilisateur]\qmk_firmware\”
• Vous utilisez ensuite l’outil suivant pour flasher le firmware :

Vous cliquez sur “Load File”, vous sélectionnez SN32F24xB dans la “CHIP LIST”, puis vous sélectionnez le firmware précédemment généré.

Vous rentrez dans le champs VID 320F et PID 5041 et vous cliquez sur START.

3. Retour au firmware d’origine du Ironclad

Enfin, dans le cas où vous souhaitez retourner sur le firmware d’origine du Ironclad, vous devez démonter votre clavier. En utilisant une trombonne, vous court-circuitez ces deux pins, puis vous branchez le clavier pour entrer en mode bootloader :

Une fois effectué, vous cliquez téléchargez le logiciel ci-dessous et vous cliquez sur le bouton bleu :

Et vous vous retrouvez ainsi avec le firmware d’origine.

Conclusion :

C’est sans doute l’article le plus long que j’ai écris jusque là. Mais avec cet article, vous pourrez désormais développer votre propre firmware sans problème et revenir à la configuration d’origine si vous le souhaitez.