Miryoku Customisation Documentation

[manna-harbour]

This is a draft of the new Miryoku customisation documentation.

• For questions and suggestions on the documentation please comment here.
• For issues with the implementation, see Support additional customisation in custom_config.h #94.
• Personalisation by selection of included alternative layout and mapping options is covered by existing documentation.
• This document applies to Miryoku QMK, Miryoku ZMK, Miryoku KMonad, and Miryoku KMK, unless noted otherwise.
• If you'd like to share your customisations with the community see Miryoku Discussions and Support #8.
  • To share your custom_config.h:
    • Create a discussion in Show and Tell and include custom_config.h as part of the title.
    • Add links to your custom_config.h. Use live links, permalinks to the file, permalinks to lines or regions, or a gist.
    • Include the following summary template and check the boxes as appropriate:

## Summary
- Miryoku Implementations
  - [ ] Miryoku QMK
  - [ ] Miryoku ZMK
  - [ ] Miryoku KMonad
  - [ ] Miryoku KMK
- Features
  - Layers
    - [ ] Substitute Layer
    - [ ] Add Layer
    - [ ] Remove Layer
    - [ ] Change Layer Display Name
  - Change Mapping
    - [ ] All Layers
    - [ ] Per Layer

custom_config.h

custom_config.h can be used to substitute, add, and remove layers, and to substitute mappings for all layers or per layer, in a single file and without causing merge conflicts with updates.

For complete examples, see example custom_config.h shared by members of the community.

In Miryoku QMK, custom_config.h is https://github.com/manna-harbour/miryoku_qmk/blob/miryoku/users/manna-harbour_miryoku/custom_config.h. In Miryoku ZMK, custom_config.h is https://github.com/manna-harbour/miryoku_zmk/blob/master/miryoku/custom_config.h and is described at https://github.com/manna-harbour/miryoku_zmk#config-file. In Miryoku KMK, custom_config.h is https://github.com/manna-harbour/miryoku_kmk/blob/main/src/custom_config.h.

Layers

Layer data is defined in miryoku_babel/miryoku_layer_alternatives.h and selected in miryoku_babel/miryoku_layer_selection.h at build time depending on build options.

Substitute Layer

Copy the layer definition to be modified from miryoku_layer_alternatives.h into custom_config.h, change the macro name to match the name for the layer used in miryoku_layer_selection.h, and edit the definition as appropriate.

E.g. to replace apostrophe with semicolon on Base when using MIRYOKU_ALPHAS=QWERTY, copy the #define MIRYOKU_ALTERNATIVES_BASE_QWERTY block (5 lines) from miryoku_layer_alternatives.h into custom_config.h, and change MIRYOKU_ALTERNATIVES_BASE_QWERTY to MIRYOKU_LAYER_BASE. For Miryoku QMK replace KC_QUOT with KC_SCLN. For Miryoku ZMK replace SQT with SEMI. For Miryoku KMonad replace U_QUOT with ;. For Miryoku KMK replace KC.QUOT with KC.SCLN.

Add Layer

Define the layer data in custom_config.h in the same way as when substituting a layer, but use a new layer name in the macro name. Available layers are listed in miryoku_babel/miryoku_layer_list.h. Copy the #define MIRYOKU_LAYER_LIST block (11 lines) into custom_config.h and add an entry for the new layer. Note the layer names in this list (and in layer data macro names) do not have the U_ prefix. The name in quotes is for display. If not also changing the per layer mapping for this layer, add a default for MIRYOKU_LAYERMAPPING_ plus layer name to MIRYOKU_MAPPING. E.g. for a new layer GAME, add #define MIRYOKU_LAYERMAPPING_GAME MIRYOKU_MAPPING.

For Miryoku ZMK and Miryoku KMK, miryoku_layer_list.h also contains a #define for each layer. These lines must also be copied, a new entry added, and all entries renumbered.

Remove Layer

Copy the layer list in the same way as when adding a layer, then remove the entry for the layer to be removed.

Layers are referenced from other layers, so to avoid having to modify other layers, add a #define to remap the missing layer onto another layer. E.g. When removing the Fun layer, add #define U_FUN U_NUM to remap all references to the Num layer instead.

For Miryoku ZMK and Miryoku KMK, remove the #define for the removed layer and renumber all entries as when adding a layer, but keep the additional #define that remaps the layer.

Mapping

Miryoku QMK

To change the mapping for all layers, copy the mapping macro definition to custom_config.h, change LAYOUT_miryoku to MIRYOKU_MAPPING, and edit as appropriate.

E.g. to map the left hand top row outer pinkie column key on crkbd to Escape, copy the contents of layouts/community/split_3x6_3/manna-harbour_miryoku/config.h to custom_config.h, change LAYOUT_miryoku to MIRYOKU_MAPPING, and change the first XXX in the macro definition to KC_ESC.

To change the mapping per layer, do as above, but change LAYOUT_miryoku to MIRYOKU_LAYERMAPPING_ plus layer name. E.g. for Base, change to MIRYOKU_LAYERMAPPING_BASE.

As mappings need to be specific to the keyboard, everything should be wrapped in #if defined / #endif conditional on the automatically defined KEYBOARD_ plus keyboard name macro. E.g. to make the mapping specific to builds for crkbd use #if defined (KEYBOARD_crkbd) / #endif.

Miryoku ZMK

To change the mapping for all layers, copy the mapping macro definition (everything inside the #if defined / #endif conditional on the MIRYOKU_LAYOUTMAPPING_ plus layout name macro) to custom_config.h, and edit as appropriate.

E.g. to map the left hand top row outer pinkie column key on corne to Escape, copy everything inside the #if !defined (MIRYOKU_LAYOUTMAPPING_CORNE) / #endif block from miryoku/mapping/42/corne.h to custom_config.h, and change the first XXX in the macro definition to &kp ESC.

To change the mapping per layer, do as above, but change MIRYOKU_LAYOUTMAPPING_ plus layout name to MIRYOKU_LAYERMAPPING_ plus layer name. E.g. for corne and Base, change MIRYOKU_LAYOUTMAPPING_CORNE to MIRYOKU_LAYERMAPPING_BASE.

As per layer mappings need to be specific to the keyboard, they should be wrapped in #if defined / #endif conditional on the automatically defined MIRYOKU_KEYBOARD_ plus keyboard name macro. E.g. for corne use #if defined (MIRYOKU_KEYBOARD_CORNE) / #endif. Note that the automatic macro is only available for workflow builds and will need to be manually added to the top of custom_config.h for local builds, e.g. for corne use #define MIRYOKU_KEYBOARD_CORNE.

Miryoku KMonad

Edit the defsrc section. Also see #90.

Miryoku KMK

To change the mapping for all layers, copy the mapping macro definition (everything inside the #if defined / #endif conditional on the MIRYOKU_LAYOUTMAPPING_ plus layout name macro) to custom_config.h, and edit as appropriate.

E.g. to map the left hand top row outer pinkie column key on CRKBD to Escape, copy everything inside the #if !defined (MIRYOKU_LAYOUTMAPPING_CRKBD) / #endif block from miryoku/mapping/42/crkbd.h to custom_config.h, and change the first XXX in the macro definition to KC.ESC.

To change the mapping per layer, do as above, but change MIRYOKU_LAYOUTMAPPING_ plus layout name to MIRYOKU_LAYERMAPPING_ plus layer name. E.g. for CRKBD and Base, change MIRYOKU_LAYOUTMAPPING_CRKBD to MIRYOKU_LAYERMAPPING_BASE.

As per layer mappings need to be specific to the keyboard, they should be wrapped in #if defined / #endif conditional on the automatically defined KMK_KEYBOARD_ plus keyboard name macro. E.g. for CRKBD use #if defined (KMK_KEYBOARD_CRKBD) / #endif.

Miryoku Babel

Miryoku Babel can be used to modify, add, and remove layers for all implementations from a single source. To modify layers, edit the corresponding source tables. To add layers, add new source tables. To add or remove layers, edit the layers table, the layer-body source block, and the miryoku_layer_alternatives.h source blocks (other than the first few lines, the contents of the miryoku_layer_alternatives.h source blocks can be copied between implementations).

Custom Hardware Support

Only the hardware support enabled at the keyboard level is included by default.

Miryoku QMK

For hardware support or other custom code, add to rules.mk, config.h, and keymap.c in the keyboard's keymaps/manna-harbour_miryoku/ directory. For keyboards supported via community layouts, first change to a keyboard keymap, e.g. for ckrbd, create keyboards/crkbd/keymaps/manna-harbour_miryoku/ and copy config.h and keymap.c from layouts/community/split_3x6_3/manna-harbour_miryoku/ to keyboards/crkbd/keymaps/manna-harbour_miryoku/.

To copy from another keymap, copy the appropriate lines from rules.mk, config.h, and keymap.c into the corresponding files in the keyboard's keymaps/manna-harbour_miryoku/ directory. E.g. to copy RGB and OLED support from the default crkbd keymap, copy keyboards/crkbd/keymaps/default/rules.mk to keyboards/crkbd/keymaps/harbour_miryoku/rules.mk, append keyboards/crkbd/keymaps/default/config.h to keyboards/crkbd/keymaps/harbour_miryoku/config.h, and copy keyboards/crkbd/keymaps/default/keymap.c to keyboards/crkbd/keymaps/harbour_miryoku/keymap.c and remove the keymaps array (i.e. this block).

Miryoku ZMK

See Kconfig Configuration.

Miryoku KMK

See Installation.

[Hugin0]

When it says to redefine a layer (when removing it) to another layer, could I say define it to any valid keycode, i.e. replace the mouse layer with KC_LSFT?

[manna-harbour]

No, the layer name macro is used in a layer-tap, so it needs to expand to a layer number. If you'd like to use Shift for the hold action you'd substitute a custom Base layer as described here, and replace the Mouse layer tap with a Shift mod tap.

[hanifn]

For hardware support or other custom code, add to rules.mk, config.h, and keymap.c in the keyboard's keymaps/manna-harbour_miryoku/ directory.

So I've been doing it wrong here and all that code should live in keyboards/boardsource/lulu/keymaps/manna-harbour_miryoku/keymap.c?

[manna-harbour]

At some point there will be a custom_keymap.c or similar, and that will be the best place for custom code that you want to use with more than one keyboard / community layout. See #94.

If you have hardware specific code that only applies to one keyboard then the keyboard keymap.c would be best.

For now, what you have is good. You already have #ifdef OLED_ENABLE so it's fine on boards with no OLED. You might also want to add a conditional on display size if you want to support other displays. The main point of custom_config.h is to make customisation more manageable (avoid merge conflicts and keep changes together) but as your changes are all at the end of the file you should be pretty safe.