mirror of
https://github.com/ClaytonWWilson/miryoku_zmk.git
synced 2025-12-13 17:58:47 +00:00
244 lines
11 KiB
Org Mode
244 lines
11 KiB
Org Mode
# 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]].
|
|
|
|
This document describes Miryoku ZMK only. For Miryoku documentation, implementations, and discussions and support, see [[https://github.com/manna-harbour/miryoku/][Miryoku]].
|
|
|
|
See the [[docs/quickstart][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.
|
|
|
|
** Overview
|
|
|
|
[[#building][Building]] can be performed [[#local-builds][locally]], or via GitHub Actions [[#workflow-builds][workflows]] without use of a local build environment. Many keyboards are [[#supported-keyboards][supported]], and building [[#out-of-tree-boards-and-shields][out of tree keyboards]] is automatically supported by the workflows.
|
|
|
|
Workflow builds can be customised by editing one of the [[#build-examples][examples]], or by filling out a [[#build-inputs][form]]. Local builds can be customised by editing a [[#config-file][config file]], and an [[#example-config-file][example]] is included.
|
|
|
|
The [[#keyboard-keymaps][keyboard keymap]] includes the config file, the [[#miryoku-keymap][Miryoku keymap]], and a [[#mapping][mapping]] for the physical layout.
|
|
|
|
|
|
** Building
|
|
|
|
|
|
*** Local Builds
|
|
|
|
First [[https://zmk.dev/docs/development/setup][set up the ZMK build environment]] and [[https://zmk.dev/docs/development/build-flash][build and flash the default keymap for your keyboard]].
|
|
|
|
Clone this repository and set [[https://zmk.dev/docs/development/build-flash#building-from-zmk-config-folder][ZMK_CONFIG]] to the absolute path of the [[config]] subdirectory. Use the [[#config-file][config file]] to select alternative layout and mapping options.
|
|
|
|
|
|
*** Workflow Builds
|
|
|
|
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.
|
|
|
|
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. Alternative layout and mapping options are given in the documentation in the form ~MIRYOKU_OPTION=VALUE~. To use here, convert to the form specified above. Use ~default~ to represent the default value. 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. Alternative layout and mapping options are given in the documentation in the form ~MIRYOKU_OPTION=VALUE~. To use here, enter the ~value~ in the corresponding ~Miryoku Option~ field. Use ~default~ to represent the default value. 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
|
|
|
|
|
|
*** 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]]. See the [[.github/workflows/test-all-boards.yml][Test All Boards workflow file]] for a list of all supported boards (including [[#out-of-tree-boards-and-shields][outboards]]).
|
|
|
|
|
|
*** 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]]. See the [[.github/workflows/test-all-shields.yml][Test All Shields workflow file]] for a list of all supported shields (including [[#out-of-tree-boards-and-shields][outboards]]).
|
|
|
|
|
|
*** Out of Tree Boards and Shields
|
|
|
|
Additionally, building some out of tree boards and shields is automatically supported by the included [[#workflow-builds][workflows]]. See [[.github/workflows/outboards]].
|
|
|
|
For local builds, copy the board or shield definition to the appropriate location under [[config]].
|
|
|
|
|
|
** Config File
|
|
|
|
The config file specifies [[https://github.com/manna-harbour/miryoku/tree/master/docs/reference#alternative-layouts][alternative layout]] and [[#mapping][mapping]] options for all [[#Local-Builds][local builds]]. The config file is not used in [[#workflow-builds][workflow 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 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 configuration options:
|
|
|
|
- ~MIRYOKU_ALPHAS=QWERTY~
|
|
- ~MIRYOKU_NAV=INVERTEDT~
|
|
- ~MIRYOKU_CLIPBOARD=WIN~
|
|
- ~MIRYOKU_LAYERS=FLIP~
|
|
- ~MIRYOKU_MAPPING=EXTENDED_THUMBS~
|
|
|
|
#+BEGIN_SRC C :tangle no
|
|
// Copyright 2021 Manna Harbour
|
|
// https://github.com/manna-harbour/miryoku
|
|
|
|
#define MIRYOKU_ALPHAS_QWERTY
|
|
#define MIRYOKU_NAV_INVERTEDT
|
|
#define MIRYOKU_CLIPBOARD_WIN
|
|
#define MIRYOKU_LAYERS_FLIP
|
|
#define MIRYOKU_MAPPING_EXTENDED_THUMBS
|
|
#+END_SRC
|
|
|
|
|
|
** Miryoku Keymap
|
|
|
|
The Miryoku keymap is a ZMK DT keymap file using C preprocessor macros for [[#config-file][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-keymaps][keyboard 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 provided below where the selection of keys is not obvious or where alternatives are provided via mapping configuration options.
|
|
|
|
|
|
**** 34-ferris
|
|
~MIRYOKU_COMBO_TPS=ENABLE~
|
|
|
|
Combos of primary and secondary thumb keys emulate the missing tertiary thumb key. This [[#config-file][configuration option]] is enabled automatically for this mapping and can be enabled on other mappings for compatibility.
|
|
|
|
|
|
**** 44-technikable
|
|
|
|
The middle 2 columns are unused.
|
|
|
|
|
|
***** Default
|
|
|
|
Supports ortho and MIT configurations.
|
|
|
|
|
|
***** 2x2u
|
|
~MIRYOKU_MAPPING=2X2U~
|
|
|
|
Supports 2x2u configuration.
|
|
|
|
|
|
***** Extended Thumbs
|
|
~MIRYOKU_MAPPING=EXTENDED_THUMBS~
|
|
|
|
The thumb keys are moved 1u to extend the thumbs. Supports ortho configuration.
|
|
|
|
|
|
**** 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 are provided in [[config]].
|
|
|
|
|
|
**
|
|
|
|
[[https://github.com/manna-harbour][https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/logos/manna-harbour-boa-32.png]]
|