miryoku_zmk/readme.org

# Copyright 2021 Manna Harbour
# https://github.com/manna-harbour/miryoku

* Miryoku ZMK [[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/logos/miryoku-roa-32.png]]

[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/cover/miryoku-kle-cover.png]]

[[https://github.com/manna-harbour/miryoku/][Miryoku]] is an ergonomic, minimal, orthogonal, and universal keyboard layout.  [[https://github.com/manna-harbour/miryoku_zmk][Miryoku ZMK]] is the Miryoku implementation for [[https://zmkfirmware.dev/][ZMK]].


** Building


*** Local Builds

Clone this repository and use for [[https://zmk.dev/docs/development/build-flash#building-from-zmk-config-folder][ZMK_CONFIG]].


*** GitHub Actions Workflows

First log in to GitHub and fork the Miryoku ZMK repository.

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.

Workflow files are in [[.github/workflows]].


**** Build Examples

Copy one of the included Build Example workflow files, edit the ~name~ value, and edit and add options and values as desired.  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"]'

The ~board~ option specifies the ZMK ~board~ and is required.  All other options are optional.  The ~shield~ option specifies the ZMK ~shield~.

The ~alphas~, ~nav~, ~clipboard~, and ~layers~ options correspond to the [[https://github.com/manna-harbour/miryoku/tree/master/docs/reference#alternative-layouts][alternative layout]] options.   The ~mapping~ option corresponds to the alternative [[#mapping][mapping]] options.  Values for these five options are case-insensitive.

The ~kconfig~ option can be used to generate a ~keyboard.conf~.  Join multiple lines with ~\n~.

See the Test All workflow files for all supported values for each option.


**** Build Inputs

The Build Inputs workflow can be used without editing workflow files.  Select Run workflow, select the Branch and fill out the form as desired, and activate Run workflow.

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.

The ~Board~ option specifies the ZMK ~board~ and is required.  All other options are optional.  The ~Shield~ option specifies the ZMK ~shield~.

The ~Miryoku Alphas~, ~Miryoku Nav~, ~Miryoku Clipboard~, and ~Miryoku Layers~ options correspond to the [[https://github.com/manna-harbour/miryoku/tree/master/docs/reference#alternative-layouts][alternative layout]] options.  The ~Miryoku Mapping~ option corresponds to the alternative [[#mapping][mapping]] options.  Values for these five options are case-insensitive.

The ~Kconfig~ option can be used to generate a ~keyboard.conf~.  Join multiple lines with ~\n~.


** Supported Keyboards

See the Test All [[#github-actions-workflows][workflow]] files for lists of supported keyboards.


*** Board Only

Any [[https://github.com/zmkfirmware/zmk/tree/main/app/boards/arm][board supported by ZMK]] with a [[#keyboard-keymaps][keymap in Miryoku ZMK]].


*** Board / Shield Combination

Any compatible combination of [[https://github.com/zmkfirmware/zmk/tree/main/app/boards/arm][board supported by ZMK]] and [[https://github.com/zmkfirmware/zmk/tree/main/app/boards/shields][shield supported by ZMK]] with a [[#keyboard-keymaps][keymap in Miryoku ZMK]].


*** Out of Tree Boards and Shields

Additionally, some out of tree boards and shields are automatically supported by the included [[#github-actions-workflows][workflows]].  See [[.github/workflows/outboards]].



** Configuration Options

[[https://github.com/manna-harbour/miryoku/tree/master/docs/reference#alternative-layouts][Keymap configuration options]] and [[#mapping][mapping]] configuration options are given in the documentation in the form ~option=value~.


*** Use in Local Builds

Convert to the form ~#define option_value~ and add to the [[#config-file][config file]].


*** Use in Workflow Builds

Convert to the form ~value~ (uppercase or lowercase) and use with the corresponding ~option~.  Use ~default~ to represent the default value.


** Config File

The config file can be used to provide [[#configuration-options][configuration options]] for all [[#Local-Builds][local builds]].  The file is [[miryoku/config.h]].  See the [[#example-config-file][example config file]].  The config file is included into the keyboard's keymap file before the mapping with:

#+BEGIN_SRC C :tangle no
#include "../miryoku/config.h"
#+END_SRC


*** Example Config File

Below is an example [[#config-file][config file]] with the following keymap [[#configuration-options][configuration options]]:

- ~MIRYOKU_ALPHAS=QWERTY~
- ~MIRYOKU_NAV=VI~
- ~MIRYOKU_CLIPBOARD=WIN~

#+BEGIN_SRC C :tangle no
// Copyright 2021 Manna Harbour
// https://github.com/manna-harbour/miryoku

#define MIRYOKU_ALPHAS_QWERTY
#define MIRYOKU_NAV_VI
#define MIRYOKU_CLIPBOARD_WIN
#+END_SRC


** Miryoku Keymap

The Miryoku keymap is a ZMK DT keymap file using C preprocessor macros for [[#configuration-options][configuration options]] and to abstract the physical layout.  The Miryoku keymap file is [[miryoku/miryoku.dtsi]].  The file is included into the [[#keyboard-keymaps][keyboard's keymap]] after the config file and mapping with:

#+BEGIN_SRC C :tangle no
#include "../miryoku/miryoku.dtsi"
#+END_SRC

Macros are included from [[miryoku/miryoku.h]].  Layer data is generated by [[https://github.com/manna-harbour/miryoku_babel][Miryoku Babel]] and is included from files in the [[miryoku/miryoku_babel]] directory.


** Mapping

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 in [[miryoku/mapping/]].  The mapping file is included into the keyboard's keymap file before the Miryoku keymap with e.g.

#+BEGIN_SRC C :tangle no
#include "../miryoku/mapping/36-minidox.h"
#+END_SRC

On each hand, only the main alpha block of 3 rows by 5 columns and the 3 most appropriate thumb keys are used.


*** Notes

Notes or diagrams are included where the selection of keys is not obvious or where alternatives are provided via mapping [[#configuration-options][configuration options]].


**** 34-ferris
~MIRYOKU_COMBO_TPS=ENABLE~

Combos of primary and secondary thumb keys emulate the missing tertiary thumb key.  This [[#configuration-options][configuration option]] is enabled automatically for this mapping and can be enabled on other mappings for compatibility.


**** 48-planck


***** Default

[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/mapping/miryoku-kle-mapping-ortho_4x12.png]]


***** Extended Thumbs
~MIRYOKU_MAPPING=EXTENDED_THUMBS~

[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/mapping/miryoku-kle-mapping-ortho_4x12-extended_thumbs.png]]


**** 48-lets_split


***** Default

[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/mapping/miryoku-kle-mapping-ortho_4x12-extended_thumbs.png]]


***** Pinkie Stagger
~MIRYOKU_MAPPING=PINKIE_STAGGER~

[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/mapping/miryoku-kle-mapping-ortho_4x12-split.png]]


**** 50-kyria


***** Default

[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/mapping/miryoku-kle-mapping-kyria.png]]


***** Extend Thumbs
~MIRYOKU_MAPPING=EXTENDED_THUMBS~

[[https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/mapping/miryoku-kle-mapping-kyria-extended_thumbs.png]]


** Keyboard Keymaps

Keymap files for many keyboards included in ZMK are provided in [[config/]].



** 

[[https://github.com/manna-harbour][https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/logos/manna-harbour-boa-32.png]]