ClaytonWWilson/miryoku_zmk
1
0
Fork 0
mirror of https://github.com/ClaytonWWilson/miryoku_zmk.git synced 2025-12-13 17:58:47 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
2cb87d07bc
miryoku_zmk/readme.org
Manna Harbour b9da68cb15 Add hummingbird
2022-06-02 16:03:51 +10:00

294 lines
13 KiB
Org Mode
Raw Blame History

# Copyright 2022 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.
[[#additional-and-experimental-features][Additional and Experimental Features]] include [[#mouse-keys][mouse keys on the host]] and [[#key-emulation-combos][key emulation combos]].
** 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 for [[#kconfig-configuration][Kconfig configuration]]. 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 for [[#kconfig-configuration][Kconfig configuration]]. 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.
**** 32-hummingbird
[[#bottom-row-combos][Bottom row combos]] and [[#thumb-combos][thumb combos]] are enabled.
**** 34-ferris
[[#thumb-combos][Thumb combos]] are enabled.
**** 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]].
** Kconfig Configuration
Kconfig configuration can be set in ~config/<keyboard>.conf~ for [[#local-builds][local]] and [[#workflow-builds][workflow]] builds, or in the ~kconfig~ / ~Kconfig~ option for workflow builds.
Additional Kconfig documentation is available at [[https://deploy-preview-722--zmk.netlify.app/docs/config/index/]].
** Additional and Experimental Features
*** Mouse Keys
The Mouse and Button layers use [[https://en.wikipedia.org/wiki/Mouse_keys][mouse keys on the host]]. Middle button, right button, and scroll are not supported.
- [[https://linuxreviews.org/HOWTO_use_the_numeric_keyboard_keys_as_mouse_in_XOrg][X11]]
- [[https://support.apple.com/en-au/guide/mac-help/mh27469/mac][Mac]]
- [[https://support.microsoft.com/en-us/windows/use-mouse-keys-to-move-the-mouse-pointer-9e0c72c8-b882-7918-8e7b-391fd62adf33][Windows]]
*** Key Emulation Combos
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.
See https://github.com/manna-harbour/miryoku/issues/56.
**** Top Row Combos
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][Kconfig configuration]].
**** Bottom Row Combos
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][Kconfig configuration]].
**** Thumb Combos
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.
**
[[https://github.com/manna-harbour][https://raw.githubusercontent.com/manna-harbour/miryoku/master/data/logos/manna-harbour-boa-32.png]]
Reference in New Issue View Git Blame Copy Permalink