ZSA Moonlander : QMK : compilation
Ma compilation QMK personnalisée
Guide complet pour compiler et flasher le firmware QMK sur le Moonlander avec ma keymap AZERTY
Pourquoi compiler soi-même ?
Bien que ZSA propose Oryx (leur configurateur en ligne), compiler le firmware QMK directement offre plusieurs avantages :
- Accès à toutes les fonctionnalités avancées de QMK
- Possibilité d’ajouter du code personnalisé
- Contrôle total sur la configuration
- Apprentissage approfondi du fonctionnement
- Pas de limitation des couches ou fonctionnalités
Mon Objectif
Je voulais implémenter des fonctionnalités spécifiques comme des macros complexes pour mon workflow de développement Python/Django, des signatures email automatisées, et des raccourcis optimisés pour mon environnement Linux que Oryx ne permettait pas.
Prérequis et installation
Environnement de développement
IMPORTANT : J’utilise exclusivement une machine Ubuntu 22.04. Oubliez Windows et sa merde – même avec WSL2 c’est galère. Prenez une vraie distribution basée sur Debian (Ubuntu, Debian, Mint, Pop!_OS) ou au pire macOS.
Windows = Problèmes garantis
J’ai testé sur Windows 11 avec WSL2 : drivers USB foireux, permissions de merde, bugs aléatoires. Économisez-vous des heures de galère et utilisez un vrai OS Unix-like.
sudo apt update
sudo apt install git python3-pip build-essential
python3 -m pip install –user qmk
# Ajouter le chemin de QMK
echo ‘export PATH=$PATH:~/.local/bin’ >> ~/.bashrc
source ~/.bashrc
Clonage du dépôt (repository) QMK
git clone https://github.com/qmk/qmk_firmware.git
cd qmk_firmware
# Configuration initiale
qmk setup
Structure de ma configuration
Ma keymap se trouve dans le dossier keyboards/zsa/moonlander/keymaps/hqf/ avec cette structure :
├── keymap.c # Configuration principale (1000+ lignes)
├── config.example.local.h # Template de configuration personnelle
├── config.local.h # Ma configuration personnelle (git-ignored)
├── rules.mk # Fonctionnalités activées
└── README.md # Documentation complète
Système de configuration modulaire
J’ai implémenté un système intelligent de configuration personnelle :
#if __has_include(« config.local.h »)
#include « config.local.h »
#else
// Valeurs par défaut si config.local.h n’existe pas
#define SIGNATURE_1 « Example Name – Role »
#define SIGNATURE_2 « Example Name – Role\nhttps://example.com »
#define EMAIL_1 « example@domain.com »
#define EMAIL_2 « example@company.com »
#define CUSTOM_SOUND SONG(STARTUP_SOUND)
#endif
Avantage de cette approche
Le fichier config.local.h est ignoré par git, ce qui permet de partager la configuration publiquement sans exposer mes informations personnelles (emails, signatures).
Compilation et flash
Configuration rules.mk
Mon fichier rules.mk optimisé pour toutes les fonctionnalités :
TAP_DANCE_ENABLE = yes
# Enable Audio features
AUDIO_ENABLE = yes
MUSIC_ENABLE = yes
# Commented features that can be enabled if needed
# MIDI_ENABLE = yes
# CONSOLE_ENABLE = no
# COMMAND_ENABLE = no
Commandes de compilation
qmk compile -kb zsa/moonlander -km hqf
# Compilation et flash en une fois
qmk flash -kb zsa/moonlander -km hqf
# Compilation avec verbose pour debug
qmk compile -kb zsa/moonlander -km hqf –verbose
Ma méthode de build
Voici comment je procède concrètement pour compiler et flasher :
cd ~/keyboards/moonlander/qmk_firmware.2024-12-11.pour.moi
qmk compile -kb moonlander -km hqf && qmk flash -kb moonlander -km hqf
Cette approche en une ligne combine compilation et flash : si la compilation réussit (&&), le flash se lance automatiquement. Simple et direct.
Troubleshooting Courants
Problèmes de Compilation
Erreurs Fréquentes
- avr-gcc not found : Installer les outils de développement manquants
- Permission denied : Problèmes de droits sur le port USB
- Device not found : Clavier pas en mode bootloader
- Memory overflow : Trop de fonctionnalités activées
Solutions Testées
python3 -m pip uninstall qmk
python3 -m pip install –user qmk
qmk setup
# Permissions USB Linux
sudo usermod -a -G dialout $USER
# Puis se reconnecter
# Forcer le mode bootloader
# Appuyer sur le petit bouton à l’arrière du clavier
# Ou maintenir le bouton reset pendant le branchement
Résultats et performance
Métriques de performance
Après plusieurs mois d’utilisation intensive :
- Gain de productivité : ~25% sur les tâches de développement
- Réduction de fatigue : Diminution significative des douleurs au poignet
- Vitesse de frappe : Maintien de 85 WPM avec une précision accrue
- Workflow optimisé : Macros email et raccourcis spécialisés
Optimisation mémoire
Statistiques de mon firmware final :
📊 Utilisation Mémoire
Flash: 85% utilisé
RAM: 60% utilisée
⌨️ Fonctionnalités
7 couches complètes
40 effets sonores
20+ macros personnalisées
🎯 Performance
Latence < 1ms
Rapid Fire configurable
N-Key Rollover
🔧 Code
1000+ lignes C
Documentation complète
Config modulaire
Ressources et documentation
Liens essentiels
- QMK Documentation officielle : https://docs.qmk.fm/
- Repository QMK : https://github.com/qmk/qmk_firmware
- ZSA Moonlander Support : https://blog.zsa.io/
- QMK Discord : Communauté active pour l’aide technique
Outils complémentaires
QMK Toolbox
Interface graphique pour flasher les firmwares sans ligne de commande
Via/Vial
Configuration en temps réel pour certaines fonctionnalités de base
QMK Configurator
Interface web pour générer des configurations simples
Oryx (ZSA)
Configurateur officiel ZSA avec limitations par rapport à QMK pur
Conclusion
Compiler son propre firmware QMK pour le Moonlander est un projet ambitieux mais extrêmement gratifiant. Cette approche transforme complètement l’expérience de frappe et ouvre des possibilités infinies de personnalisation.
Retour sur Investissement
Les bénéfices obtenus justifient largement l’investissement en temps :
- Productivité accrue : Macros et raccourcis optimisés pour mon workflow
- Confort ergonomique : Réduction des tensions et fatigue
- Personnalisation totale : Chaque aspect adapté à mes besoins
- Évolutivité : Possibilité d’ajouter de nouvelles fonctionnalités
- Apprentissage : Compréhension approfondie de QMK et du hardware
Cette configuration continue d’évoluer avec mes besoins, prouvant que QMK offre une plateforme exceptionnelle pour créer l’outil de saisie parfait.