Editing Layout

Each instance of MoErgo Layout Editor has a "space" to edit a layout.

You can go back to the layout being edited to continue editing, from anywhere in MoErgo Layout Editor by clicking on the Edit or Edit (Changes not saved) in the top menu bar.

Menu bar showing Edit

Menu bar showing Edit(Changes not saved)

You can browse other layouts without losing the changes made to this layout beign edited. This is very useful for getting inspiration, or even copy certain elements (such as Layers) from other layouts to the this layout being edited. For more information on this powerful functionality, please see Copying Select Layers To Editing Layout.

Layout sections

When you edit the layout, a screen like below will be shown.

Sections in the layout page

The layout is split into different sections. We will explain each section in greater details below.

Title

A human readable description of the layout.

Tags

Each layout has one or more tags. Tags are descriptive keywords that help yourself remember and to help other people find your layout. A good tag should describe a key distinguishing attribute of the key layout, perhaps describing the application, OS, game that the layout is designed for.

A tag must start with a lower case, and consists of only lower case, numbers and dashes.

Some good examples of tags include:

• OS: linux, mac, android
• Layout: azerty, colemak
• Language: japanese, german, swedish, norwegian, spanish
• Software or games: excel, vim, vscode, dota2

Locale

This changes the rendering of the legends on the keyboard to match the selected locale. This helps international users to design their keyboard layouts.

The default locale is en-US, which matches computers set to the United States English locale.

For more information please see International Keyboard Setup.

Layer selector

ZMK supports the concept of multiple layers. When you power on the keyboard, the base layer (layer #0) will be active. However, you can switch to different layers; thus, the same key can serve multiple purposes. This isn’t as confusing as it may sound, it’s similar to the Fn key on a laptop. There are two ways of switching layers: You can switch to another layer momentarily (while you hold down a trigger key, à la “Fn”) or indefinitely (until you switch layers again).

ZMK documentation for layers are at https://zmk.dev/docs/features/keymaps. Do note that an active higher-numbered layer has priority over the lower numbered layers.

On MoErgo Layout Editor, the layers are represented on the left side. The current layer shown on the layout is the layer highlighted.

When you hover over the circles, the full names of the layers appear and you can select a particular layer to show, or to perform action on a layer.

The available actions are:

• Reorder layer: Drag to move the layer to the desired layer priority
• Edit layer name: Change the layer name
• Duplicate layer: Create a new layer by duplicating the selected layer
• Delete layer: Delete the selected layer - do note that all reference to the layer will also be removed
• Add a new layer: Create a new layer from scratch

Notes

This optional section is for yourself and others to better understand the intention of the layout.

Macros

This section allows you to define macros.

A macro behavior defines a sequence of actions (e.g., pressing keys, holding modifiers) that are grouped together, which can be assigned to a key or a combo or other behaviors to automate complex tasks on your keyboard.

For more information please see Macros.

Hold-Taps

This section allows you to define hold-tap behaviors.

A hold-tap behavior allows a key to perform two different actions depending on how long you press it. If you tap the key briefly, it performs one action (e.g., typing a letter), and if you hold the key longer, it performs a different action (e.g., holding a modifier like Shift).

This allows you to maximize your keyboard’s functionality with the same key, depending on how you press it.

For more information please see Hold-Taps.

Combos

This section allows you to define combos.

Combos define rules which let you trigger a specific action when you press multiple keys at the same time. Instead of each key doing its usual function, the combo activates a new action only when the keys are pressed together within a short time interval.

For more information please see Combos.

Input Listeners

This section allows you to emulate mouse behaviors (such as mouse buttons, mouse movements and scroll).

For more information please see Mouse emulation.

Custom Defined Behavior

This optional section is for creating custom ZMK behaviors such as tap-dance by injecting your own code into the generated keymap DTSI file. This is advanced functionality; please use it with extreme caution.

For more information please see Advanced usage: Custom Defined Behaviors.

Custom Device-Tree

This optional section is for injecting your own code into the generated keymap DTSI file. This is advanced functionality; please use it with extreme caution.

For more information please see Advanced usage: Custom Device-Tree

Advanced Configuration

The Advanced Configuration section allows you to override the default ZMK firmware behaviors. For most users, it is not necessary to tune these advanced configuration settings.

Advanced Configuration

Some of the Advanced Configuration settings include:

• Enabling mouse support, for integrated pointing device or mouse emulation
• Enabling or disabling N-key rollover (NKRO)
• Enabling, disabling and configuring deep sleep
• Key debouncing characteristics to eliminate key chatter
• Debugging and troubleshooting settings

Note

Certain Advanced Configuration options, relating to HID descriptor such as NKRO, will not take effect until the HID descriptor is refreshed. Please see https://zmk.dev/docs/features/bluetooth#refreshing-the-hid-descriptor for details.

Key binding and key behaviors

Each key in each layer can be bound to a key behavior.

The upper left corner shows the behavior type.

The middle shows the keycode or the behavior parameter, depending on the type of behavior.

Behavior types

MoErgo Layout Editor currently supports the following ZMK behavior types directly.

• &kp: key press
• &bootloader: enter bootloader mode
• &bt: bluetooth
• &cap_word: capitalize words
• &key_repeat: repeat key
• &kt: key toggle
• &lt: layer tap
• &mo: momentary layer
• &mt: mod tap
• &none: do nothing
• &output: output selection
• &reset: reset keyboard
• &rgb_ug: RGB underglow control
• &sk: sticky key
• &sl: sticky layer
• &to: to layer
• &trans: transparent
• &mmv: mouse X/Y movement
• &mkp: press/release mouse buttons
• &msc: vertical and horizontal mouse scroll

For more information on the ZMK key behaviors, please see ZMK documentation at https://zmk.dev/docs

In additional to the above standard ZMK behaviors, MoErgo Layout Editor also supports the following pseudo behaviors:

• &bt_0: select bluetooth profile 0 with a single quick-tap, explicitly disconnect bluetooth profile 0 with a double quick-tap
• &bt_1: select bluetooth profile 1 with a single quick-tap, explicitly disconnect bluetooth profile 1 with a double quick-tap
• &bt_2: select bluetooth profile 2 with a single quick-tap, explicitly disconnect bluetooth profile 2 with a double quick-tap
• &bt_3: select bluetooth profile 3 with a single quick-tap, explicitly disconnect bluetooth profile 3 with a double quick-tap
• &magic: quick-tap to show RGB indicators. Press to momentarily switch to magic layer
• &lower: hold to momentarily switch to lower layer. Double tap to persistently switch to lower layer.
• &layer: hold to momentarily switch to the target layer. Double tap to persistently switch to the target layer. This is a generalization of &lower
• Custom: A special pseudo behavior to allow arbitrary key mapping, to be used with Custom Defined Behavior. For more information please see Custom Defined Behaviors.

Keypress behavior: modifier functions

The keypress (&kp) behavior in ZMK has a very powerful but not-well-known capability known as the modifier function. Modifier functions make it possible to add one or more modifiers to a keycode.

ZMK documentation for modifier functions are at https://zmk.dev/docs/codes/modifiers#modifier-functions

MoErgo Layout Editor has built-in support for modifier functions. For example if you type LA as the keycode for an &kp behavior, you have selected the Left Alt function. You can then add another key or modifier function.

For example, to define Hyper, you can use &kp LS(LC(LG(LALT))). To do so:

1. Select &kp as behavior
2. In the keycode slot, select LS as keycode
3. In the keycode slot for LS modifier function, select LC as keycode
4. In the keycode slot for LC modifier function, select LG as keycode
5. In the keycode slot for LG modifier function, select LALT as keycode

Modifier functions to define hyper

&magic pseudo behavior

This is a special MoErgo-defined pseudo behavior defined as a macro. For a key bound to this behavior,

• A quick tap will activate the LED indicators.

User guide for LED indicators

Glove80

Glove80 User Guide "Indicators"

• While holding the key, the keyboard will momentarily switch to the layer with the label Magic (note: case sensitive). After key release, the keyboard will automatically revert back to the current layer.

Mapping of Magic key on factory default layout

Glove80

On a standard Glove80 layout, LH C6R6 key is mapped to the &magic behavior in all layers.

&lower pseudo behavior

This is a special MoErgo-defined pseudo behavior defined as a macro. For a key bound to this behavior,

• While holding the key, the keyboard will momentarily switch to the layer with the label Lower (note: case sensitive). After key release, the keyboard will automatically revert back to the current layer
• If double tapped, the keyboard will permanently switch to layer with the label Lower.

Mapping of Layer key on factory default layout

Glove80

On a standard Glove80 layout, LH T3 key is mapped to the &lower behavior in the Base Layer (layer #0).

&layer pseudo behavior

This is a special MoErgo-defined pseudo behavior defined as a macro. It has a target layer as its parameter.

For a key bound to this behavior,

• While holding the key, the keyboard will momentarily switch to the target layer. After key release, the keyboard will automatically revert back to the current layer
• If double tapped, the keyboard will permanently switch to the target layer.

NOTE: This pseudo behavior cannot be used in a macro definition.

Bluetooth &bt_0 &bt_1 &bt_2 &bt_3 pseudo behaviors

These 4 pseudo behaviors provide the following functionality:

• On a single quick-tap, switch the keyboard to the respective designated bluetooth device, if the bluetooth device is currently connected
• On a double-tap, explicitly disconnect the respective designated bluetooth device, if the bluetooth device is currently connected and is not the current active BLE profile. This functionality is useful for tablets and phones that disable on-screen keyboard, even if the device is not the current selected output device.

Underneath the bonnet, these behaviors are each implemented as a tap-dance and a macro, The macro sets output to bluetooth, and then sets the bluetooth device to the designated bluetooth device.

As an example &bt_0 is defined as:

    behaviors {
        bt_0: bt_0 {
            compatible = "zmk,behavior-tap-dance";
            label = "BT_0";
            #binding-cells = <0>;
            tapping-term-ms = <200>;
            bindings = <&bt_select_0>, <&bt BT_DISC 0>;
        };
    }


    macros {
        bt_select_0: bt_profile_macro_0 {
            label = "BT_0";
            compatible = "zmk,behavior-macro";
            #binding-cells = <0>;
            bindings
                = <&out OUT_BLE>,
                  <&bt BT_SEL 0>;
        };
    };

Bluetooth clear all profiles &bt BT_CLR_ALL

The &bt behavior has been extended with an additional parameter BT_CLR_ALL

When bound to &bt BT_CLR_ALL, the key will initiate clearing all Bluetooth bindings (excluding the binding to the right hand).

Saving a Layout and building firmware

To save or build a layout, use the multi-button. The Save action is on the left, and the Save and Build action is on the right.

During the layout saving process, the MoErgo Layout Editor will perform a comprehensive correctness check on the layout being edited.

If there are any errors, a screen like the one below will be displayed.

Layout saving error

You must fix all issues before the layout can be saved.

Once the firmware is successfully built, the MoErgo Layout Editor will exit layout editing mode and redirect you to the layout viewing URL of the layout that was just built.

Exporting a Layout as keymap DTSI

Exporting as keymap DTSI

This is an advanced feature useful for:

• Compiling the firmware using a different method, such as local compilation

• Debugging complex Custom Defined Behaviors and Custom Device-Tree

If you are not using these advanced techniques, you probably won't need this feature

To export a layout as a DTSI fragment, click the Export button next to the Save and Build button. This will export the layout in ZMK DTSI format with a filename of <layout_name>.keymap.

JSON export and import

To activate the JSON export and import functionality, you must go to the Settings page and enable the Local Backup and Restore option.

Experimental Feature

As the Layout Editor evolves, the JSON format may change. There is no guarantee that a layout exported in JSON format can be imported in the future.

Exporting JSON

Once enabled, an option to export in JSON will appear in the Export button's dropdown menu. Exported JSON can be useful not only for backing up your layout locally, but also for performing automated tasks like replacing keycodes.

Importing JSON

With the setting enabled, you can import a JSON file back into the Layout Editor using the Import controls in the bottom left corner of the editor window.