Editing Layout

The MoErgo Layout Editor provides a workspace for you to create and modify your layouts.

You can always return to this workspace from anywhere in the editor by clicking Edit or Edit (Changes not saved) in the top menu bar.

Menu bar showing Edit

Menu bar showing Edit(Changes not saved)

Never Lose Your Work

While you are in the editing workspace, your progress is safe. You can freely browse other layouts to get inspiration or even copy parts of them, like layers or macros, without losing any of the changes you've made to your current layout.

For more details, see Copying Select Layers To Editing Layout.

Protecting Your Saved Layouts

In the MoErgo Layout Editor, any saved layout is protected from being changed directly. This is a key feature designed to safeguard your work and ensure that any layout you share or back up remains consistent forever.

If you want to make changes to a saved layout, you simply clone it. This creates a new, editable copy in your workspace while preserving the original version. This approach guarantees that any shared links to a layout will always point to the exact version you intended, without any risk of future edits breaking the link or causing confusion.

Understanding the Layout Editor

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

Sections in the layout page

The editor is organized into the following sections, each handling a different aspect of your layout:

Title

Give your layout a descriptive and easy-to-remember name.

Tags

Tags are keywords that help you organize and find layouts. A good tag describes a key feature of the layout, such as the OS, application, or language it's designed for.

Tags must start with a lowercase letter and can only contain lowercase letters, 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.