How devpruthvi/miryoku_zmk works
Project Type and Purpose
• The repository implements “Miryoku” – an ergonomic, minimal, orthogonal, and universal keyboard layout – as integrated into ZMK firmware.
• Its purpose is to enable users to build custom keyboard firmware with alternative layout options, mapping macros, and support for a variety of in-tree and out-of-tree keyboards.
• The README describes local and workflow builds (via GitHub Actions), custom configuration (in config files and miryoku/custom_config.h), and options for specifying alternative keyboard arrangements (e.g., alphas, nav, mapping).
Key Components in the File Tree
• .github/workflows – Contains a dozen+ YAML scripts (and subdirectories) that define CI/CD pipelines for building firmware for different keyboard configurations, boards, and shields. Also includes outboard definitions (metadata files for external keyboards/shields).
• config – Contains keymap configuration files for numerous supported boards. This directory is where custom layout options are defined for each target keyboard.
• docs – Holds the quickstart guide and images that explain how to build and use the firmware.
• miryoku – Contains the core code – mapping macros (mirroring physical layouts), keymap definitions (miryoku.dtsi), Babel files for generating key layout layers, and configuration header files. This is the “heart” of the Miryoku keymap system.
• Additional files such as readme.org offer guidance on build customization, alternative layout and mapping options, and other advanced features (e.g., double tap boot, soft off).
a. Core Build/Configuration Pipeline:
– “User / Developer Inputs”:
• Config Files (in “config” and miryoku/custom_config.h)
• Alternative layout options (e.g., MIRYOKU_ALPHAS, MIRYOKU_NAV, etc.)
– “Mapping Macros & Keymap Definitions”:
• miryoku/mapping/… (files for different physical layouts)
• miryoku/miryoku.dtsi (the master keymap file)
• miryoku/miryoku_babel (layer generation)
– “Firmware Integration”:
• Integration with ZMK firmware (via inclusion of the config file and mapping macros)
– “Build System”:
• GitHub Actions workflows (.github/workflows) that trigger builds
• Outboard definitions (in .github/workflows/outboards) for out-of-tree boards and shields, showing external repository sync and symlink creation.
– “Output Artifacts”:
• Firmware binaries (generated from either local builds or through the workflow build matrix)
b. Relationships and Data Flow:
– Those in turn feed into the “Keymap Assembly” process (i.e., inclusion of custom config, keymap generation, and integration with ZMK).
– The build workflows (in .github/workflows) pick up these assembled keymaps/configurations and then trigger “Local Builds vs. Workflow Builds.”
– From the “Workflow Builds” you then have conditional logic to clone out-board definitions from external repositories (for out-of-tree keyboards and shields) that merge with the primary configuration before building.
– Finally, the built firmware binaries are deployed as Artifacts.
c. Architectural Patterns/Principles:
– Modularity: Separate directories for configuration, mapping logic, and CI workflows allow easier maintenance and scalability.
– Extensibility: Outboard files that define external repositories, branches, and modules indicate plug‐in points for adding new hardware (boards/shields) without altering the core engine.
– Automated Build Pipeline: The separation between local builds and GitHub Actions builds shows a CI/CD design with a matrix of build options that automates firmware generation.
d. Relevant Technologies & Frameworks:
– ZMK firmware: The base firmware that this keymap overlays.
– GitHub Actions: The CI/CD pipeline (various workflow YAML files).
– C Preprocessor and C header files: Used for including configuration and mapping macros.
– Shell scripting (via outboard files): For setting board/shield metadata.