Miryoku is an ergonomic, minimal, orthogonal, and universal keyboard layout. Miryoku ZMK is the Miryoku implementation for ZMK.
This document describes Miryoku ZMK only. For Miryoku documentation, implementations, and discussions and support, see Miryoku.
See the Miryoku ZMK Quickstart Guide to have a personalised build running on your keyboard in a few minutes without installing any software or editing any files.
Building can be performed locally, or via GitHub Actions workflows without use of a local build environment. Many keyboards are supported, and building out-of-tree keyboards is automatically supported by the workflows.
Workflow builds can be customised by copying and editing one of the example workflows or by filling out a form, and specifying options. Local and workflow builds can be customised by editing a config file, and an example is included.
The keyboard keymaps are composed of the config file, a mapping for the physical layout, and the Miryoku keymap.
Additional and Experimental Features include caps word, customisation, key emulation combos, mouse keys, and 𝑥MK.
First set up the ZMK build environment and build and flash the default keymap for your keyboard.
Clone this repository and set ZMK_CONFIG to the absolute path of the config subdirectory. Use the config file to select alternative layout and mapping options.
Firmware can be built via GitHub Actions workflows without use of a local build environment.
First log in to GitHub, fork the Miryoku ZMK repository, and enable workflows.
To access a workflow, visit the Actions tab and select the workflow. To download the firmware from a workflow run, select the workflow, select the workflow run, select the desired Artifacts, and unzip the downloaded zip file.
See the Miryoku ZMK Quickstart Guide for step by step instructions.
Workflow files are in .github/workflows.
To enable Miryoku ZMK workflow debugging, set the following secret in the repository: MIRYOKU_DEBUG to MIRYOKU_DEBUG_TRUE. Optionally also enable step debugging.
Copy one of the included Build Example workflow files, edit the name value, edit and add options and values as desired, and push changes. Access the workflow, select Run workflow, select the Branch if desired, and activate Run workflow.
Options are specified in the with section and are of the following form.
option: '["value"]'
For multiple values per option use the following form, and a matrix build will be performed for each combination of values across all options.
option: '["value1","value2"]'
See Options below for a description of each option.
The Build Inputs workflow can be used without editing workflow files. Access the workflow, Select Run workflow, select the Branch and fill out the form as desired, and activate Run workflow.
Most options are specified by entering values directly in the corresponding field. Multiple comma separated values can be entered per option and a matrix build will be performed for each combination of values across all options.
Values for Miryoku alternative layout options are selected from a list. As multiple selection is not supported, matrix builds across multiple values are not possible for these options, and the Test Inputs or Build Example workflows should be used instead.
See Options below for a description of each option.
All workflow options are described below.
The board option is required and all others are optional.
See Supported Keyboards for details of supported keyboards.
Specifies the ZMK board.
For onboard controller keyboards (keyboards with an integrated controller), enter the keyboard name, e.g. ahokore, ble_chiffre, technikable, zaphod.
For split onboard controller keyboards (keyboards with an integrated controller on each side), enter the keyboard side name, e.g. corne-ish_zen_left, corne-ish_zen_right. To build both sides in the same run, enter both keyboard side names separated by a comma, e.g. corne-ish_zen_left,corne-ish_zen_right.
For composite keyboards (keyboards with a separate controller), enter the controller name, e.g. nice_nano, nice_nano_v2, seeeduino_xiao, seeeduino_xiao_ble. Also specify the shield.
Specifies the ZMK shield.
For onboard controller keyboards (keyboards with an integrated controller), leave as default.
For composite keyboards (keyboards with a separate controller), enter the keyboard name, e.g. absolem, chocv, eek, osprette.
For split composite keyboards (keyboards with a separate controller on each side), enter the keyboard side name, e.g. corne_left, corne_right, cradio_left, cradio_right. To build both sides in the same run, enter both keyboard side names separated by a comma, e.g. corne_left,corne_right, cradio_left,cradio_right.
Also use to specify optional non-keyboard shields, e.g. nice_view. To combine shields, separate with space, e.g. nice_view_adapter nice_view, corne_left nice_view_adapter nice_view. For multiple builds of combined shields in the same run, use both comma and space separators, e.g. corne_left nice_view_adapter nice_view,corne_right nice_view_adapter nice_view.
The alphas, nav, clipboard, and layers options correspond to the Miryoku alternative layout options. See the default layers and alternative layouts documentation for details. See the Test All Configs workflow file for a list of all supported values.
The mapping option corresponds to the alternative mapping options.
Alternative layout and mapping options are given in the documentation in the form MIRYOKU_OPTION=VALUE, e.g. MIRYOKU_ALPHAS=QWERTY. To use here, use the value with the corresponding option. Use default to represent the default value. Values for these five options are case-insensitive.
Select an alternative alphas layout, e.g. colemak, dvorak, halmak, qwerty. For Colemak Mod-DH, leave as default.
Select an alternative Nav layout, e.g. invertedt, vi. For home position line nav, leave as default.
Select an alternative clipboard type, e.g. mac, win. For CUA bindings, leave as default.
Select an alternative layers layout, e.g. flip. For right hand Nav, leave as default.
Select an alternative mapping, e.g. extended_thumbs, pinkie_stagger. For the default mapping, leave as default.
Appends to the config file, e.g. #define MIRYOKU_TAP_QWERTY. Join multiple lines with \n, e.g. #define MIRYOKU_TAP_QWERTY\n#define MIRYOKU_EXTRA_COLEMAKDH. For no additional config, leave as default.
Appends to Kconfig configuration. Join multiple lines with \n. For no additional config, leave as default.
Used to select an alternative ZMK branch for building, and to merge branches into ZMK at build time.
Branches are specified in the form <user>/<repo>/<branch>. E.g. the default ZMK branch would be specified as zmkfirmware/zmk/main.
Multiple space separated branches can be specified. The first branch specified is used as an alternative ZMK branch for building. Any additional branches will be merged.
For no changes, leave as default.
In-tree keyboards are maintained as part of ZMK. See the ZMK Supported Hardware documentation for details.
Supporting an in-tree keyboard in Miryoku ZMK requires only adding the keyboard keymap and mapping files.
Out-of-tree keyboards are not maintained as part of ZMK or Miryoku ZMK. Keyboard definitions for out-of-tree keyboards are located in separate repositories. Some keyboards also require a fork of ZMK. Keyboard definitions and ZMK forks are maintained by the maintainers of those repositories.
To build an out-of-tree keyboard the repositories need be checked out and used appropriately. For local builds these steps must be performed manually. For workflow builds the Miryoku ZMK build workflows perform these steps automatically at build time.
Supporting an out-of-tree keyboard in Miryoku ZMK requires adding the keymap and mapping files, and references to the repositories for use by workflow builds.
See the Test All Controllers, Boards, and Shields workflow files for lists of supported keyboards.
See .github/workflows/outboards for details of supported out-of-tree keyboards.
See manna-harbour/miryoku#81 for available and supported in-tree and out-of-tree keyboards and current maintenance status.
Notes are provided below for individual keyboards where required.
The default ZMK fork for corne-ish_zen is https://github.com/LOWPROKB/zmk/tree/Board-Corne-ish-Zen-dedicated-work-queue.
A custom branch is available at https://github.com/manna-harbour/zmk/tree/zen. The branch is based on https://github.com/caksoylar/zmk/tree/caksoylar/zen-on-main which adds compatibility with ZMK main.
Extra features have also been added which can be selected with the following Kconfig configuration options.
CONFIG_ZMK_DISPLAY_HIDE_MOMENTARY_LAYERS=ySuppress layer widget updates for momentary layer changes.CONFIG_CUSTOM_WIDGET_LOGO_IMAGE_ZEN=yCorne-ish Zen logo (default).CONFIG_CUSTOM_WIDGET_LOGO_IMAGE_ZMK=yZMK logo.CONFIG_CUSTOM_WIDGET_LOGO_IMAGE_LPKB=yLowproKB logo.CONFIG_CUSTOM_WIDGET_LOGO_IMAGE_MIRYOKU=yMiryoku logo.CONFIG_IL0323_INVERT=yInvert display.
For workflow builds using the Build Inputs workflow, use manna-harbour/zmk/zen with the branches option. For workflow builds using Build Example workflows, see the Build Example corne-ish_zen custom workflow.
For local builds, make the changes locally.
The config file is used to specify alternative layout and mapping options for local builds. Options are given in the documentation in the form MIRYOKU_OPTION=VALUE. Convert to the form #define MIRYOKU_OPTION_VALUE and add to the config file.
The config file can also be used to set default alternative layout and mapping options for workflow builds, as an alternative to using the corresponding alternative layout and mapping workflow options. In this case setting different values for the same option in the config file and in the workflow options may lead to undefined behaviour.
The config file can also be used to set other Miryoku ZMK configuration options for local and workflow builds.
Config file entries can also be specified in the custom_config option for workflow builds.
The file is miryoku/custom_config.h. See the example config file. The config file is included into the keyboard’s keymap file before the mapping with:
#include "../miryoku/custom_config.h"Below is an example config file with the following alternative layout and mapping options:
MIRYOKU_ALPHAS=QWERTYMIRYOKU_TAP=QWERTYMIRYOKU_EXTRA=COLEMAKDHMIRYOKU_NAV=INVERTEDTMIRYOKU_CLIPBOARD=WINMIRYOKU_LAYERS=FLIPMIRYOKU_MAPPING=EXTENDED_THUMBS
// Copyright 2022 Manna Harbour
// https://github.com/manna-harbour/miryoku
#define MIRYOKU_ALPHAS_QWERTY
#define MIRYOKU_TAP_QWERTY
#define MIRYOKU_EXTRA_COLEMAKDH
#define MIRYOKU_NAV_INVERTEDT
#define MIRYOKU_CLIPBOARD_WIN
#define MIRYOKU_LAYERS_FLIP
#define MIRYOKU_MAPPING_EXTENDED_THUMBSThe Miryoku keymap is a ZMK DT keymap file using C preprocessor macros for configuration options and to abstract the physical layout. The Miryoku keymap file is miryoku/miryoku.dtsi. The file is included into the keyboard’s keymap after the config file and mapping with:
#include "../miryoku/miryoku.dtsi"Macros are included from miryoku/miryoku.h. Layer data is generated by Miryoku Babel and is included from files in the miryoku/miryoku_babel directory.
The keymap is mapped onto keyboards with different physical layouts. The keymap is specified in terms of the MIRYOKU_MAPPING macro. The macro is defined in a C header file for each physical layout. Unused keys are mapped to &none. The files are below miryoku/mapping/. The mapping file is included into the keyboard keymap file before the Miryoku keymap with e.g.
#include "../miryoku/mapping/36/minidox.h"On each hand, only the main alpha block of 3 rows by 5 columns and the 3 most appropriate thumb keys are used.
Notes or diagrams are provided below where the selection of keys is not obvious or where alternatives are provided via mapping configuration options.
Bottom row combos and thumb combos are enabled.
Thumb combos are enabled.
MIRYOKU_MAPPING=PIM447RIGHT
For use with PIM447 installed in the right secondary thumb key position. The right tertiary thumb key is replaced with the secondary and thumb combos are enabled. Note that the right secondary thumb key is in the opposite position from usual, relative to the primary.
The thumbs keys, from left to right, are as follows: left secondary, left primary, right secondary, right primary, right tertiary. Thumb combos are enabled for the left thumbs. The left thumb keys are also duplicated on the left outer pinkie column, from top to bottom, as follows: primary, tertiary, secondary. Note that the left secondary thumb key is in the opposite position from usual, relative to the primary. For MIRYOKU_LAYERS=FLIP, substitute left and right above.
The middle 2 columns are unused.
Supports ortho and MIT configurations.
MIRYOKU_MAPPING=2X2U
Supports 2x2u configuration.
MIRYOKU_MAPPING=EXTENDED_THUMBS
The thumb keys are moved 1u to extend the thumbs. Supports ortho configuration.
MIRYOKU_MAPPING=EXTENDED_THUMBS
MIRYOKU_MAPPING=PINKIE_STAGGER
MIRYOKU_MAPPING=EXTENDED_THUMBS
An angled ortho split layout is mapped onto the row-staggered keyboard. The rows are moved up to better position the thumb keys, the hands are separated as much as possible, and the left hand column angle is reversed to reduce ulnar deviation of the wrists.
MIRYOKU_MAPPING=NOREVERSEANGLE
An alternative subset mapping is also provided without reverse column angle.
MIRYOKU_MAPPING=LITE
Another alternative subset mapping is provided mapping only the 3x10 alphas, plus spacebar for space / Nav, with the remainder being the default keymap with semicolon in place of quote.
The keyboard keymaps include the config file, a mapping for the physical layout, and the Miryoku keymap. Keyboard keymap files are in config.
Kconfig keyboard configuration options can be set in config/<keyboard>.conf for local and workflow builds.
Kconfig configuration can also be specified in the kconfig option for workflow builds.
Examples include CONFIG_ZMK_SLEEP=y, CONFIG_ZMK_DISPLAY=y, CONFIG_BT_CTLR_TX_PWR_PLUS_8=y. Additional documentation is available at https://deploy-preview-722–zmk.netlify.app/docs/config/index/. Also see the default <keyboard>.conf included in the keyboard definition, e.g. corne.conf.
Caps word is used in place of Caps Lock. Combine with Shift for Caps Lock.
Emulate a key with a combo of two other keys. Enabled automatically on keyboards with a missing key. Can be enabled on other keyboards for use with hard to reach keys, or for compatibility.
On the top row on each hand, combo the ring and middle finger keys to emulate the pinkie key, and combo the middle and index finger keys to emulate the inner index key.
Requires CONFIG_ZMK_COMBO_MAX_COMBOS_PER_KEY=16 Kconfig configuration.
On the bottom row on each hand, combo the ring and middle finger keys to emulate the pinkie key, and combo the middle and index finger keys to emulate the inner index key.
Requires CONFIG_ZMK_COMBO_MAX_COMBOS_PER_KEY=16 Kconfig configuration.
On each hand, combo the primary and secondary thumb keys to emulate the tertiary thumb key. Requires suitable keycaps to enable the thumb to press both keys simultaneously.
The Mouse and Button layers use mouse keys on the host. Scroll is not supported.
Support for zmkfirmware/zmk#778 is also included.
As the PR branch is not being maintained, use https://github.com/ftc/zmk/tree/mouse-ftc instead.
To build, add #define MIRYOKU_KLUDGE_MOUSEKEYSPR to the config file, add CONFIG_ZMK_MOUSE=y to the Kconfig configuration, and merge the mousekeys branch.
For workflow builds using the Build Inputs workflow, use #define MIRYOKU_KLUDGE_MOUSEKEYSPR with the custom_config option, CONFIG_ZMK_MOUSE=y with the kconfig option, and zmkfirmware/zmk/main ftc/zmk/mouse-ftc with the branches option. For workflow builds using Build Example workflows, see the Build Example mousekeyspr workflow.
For local builds, make the changes locally.
Support for zmkfirmware/zmk#1292 (comment) is included using https://github.com/manna-harbour/zmk/tree/suspend-test and https://github.com/manna-harbour/zephyr/tree/v3.0.0+zmk-fixes-suspend-test.
To suspend, hold shift and tap the boot key. For split keyboards, use the boot key on each side, and suspend the peripheral side first.
To build, add #define MIRYOKU_KLUDGE_SUSPEND to the config file and merge https://github.com/manna-harbour/zmk/tree/suspend-test.
For workflow builds using the Build Inputs workflow, use #define MIRYOKU_KLUDGE_SUSPEND with the custom_config option, and zmkfirmware/zmk/main manna-harbour/zmk/suspend-test with the branches option. For workflow builds using Build Example workflows, see the Build Example suspend workflow.
For local builds, make the changes locally.
Use Miryoku ZMK with any keyboard with 𝑥MK.
For local builds first merge zmkfirmware/zmk#1318. For the xmk shield, add https://github.com/manna-harbour/xmk/tree/main/zmk/boards/shields/xmk as config/boards/shields/xmk, and build with shield xmk and the appropriate board. For the native_posix_64 board, build with board native_posix_64.
For workflow builds for the xmk shield, use the Build Example 𝑥MK xmk workflow, or use the Build Inputs workflow with shield xmk, the appropriate board, and branches zmkfirmware/zmk/main petejohanson/zmk/shell/tap-command. For workflow builds for the native_posix_64 board, use the Build Example 𝑥MK native_posix_64 workflow, or use the Build Inputs workflow with board native_posix_64 and branches zmkfirmware/zmk/main petejohanson/zmk/shell/tap-command.
Also see Miryoku KMonad.
