Mugur

Mugur is a keyboard configurator for QMK compatible keyboards. mugur-mugur takes a list of all the layers and keys and generates the equivalent QMK C code, ready to be flashed on the keyboard.

Supported features: all the basic QMK keycodes, mod-tap, modifiers, one-shot keys, layer toggle, macros, tap dance, leader key and combos. If an Emacs function has a keybinding, it can be specified as a key.

Table of Contents

• Mugur
• How it works
• Features and keycodes
  • Basic Keycodes
  • Mod-tap
  • Modifiers
  • One Shot Keys
  • Layer Toggle
  • Macros
  • Tap Dance
  • Leader Key
  • Combos
  • Emacs keybound functions
  • User Defined Keys
  • Insert raw C code (advanced users)
• Configuration
  • Paths and names
  • Configs (config.h)
  • Special Keys
• Supported Keyboards
• Other points
• Full Examples
  • Ergodox
  • Corne

(Table of contents generated with markdown-toc)

How it works

Given a list of all the layers and keys, mugur-mugur generates the equivalent C code for the qmk_firmware, ready to be built and flashed on the keyboard.

(mugur-mugur
 '(("base"    a b c (LT numbers d))
   ("numbers" 1 2 3 "one two three")))

This is a two-layers layout for a keyboard with four keys. The "base" layer has the letters 'a', 'b' and 'c' and a layer-toggle key that activates the "numbers" layer when held and sends the letter 'd' when tapped. On the "numbers" layer there are the 1, 2 and 3 digits, as expected, and then a macro key that sends "one two three" when pressed.

There are other possibilities, qmk features and configurations to try, but that is the basics of it. See the examples section for more rich mugur layouts.

Features and keycodes

mugur-key is just a term I've invented for any of the symbols, characters, strings or lists that can appear in a mugur-keymap. In the above example, both 'a' and "one two three" are valid mugur-keys.

Basic Keycodes

Mugur supports all the basic qmk keycodes. Their mugur-key equivalent is either a symbol, a digit, a character or a string.

The mugur-keys are case sensitive, c and C being different mugur-keys, one for the letter 'c', the other for the Ctrl modifier. Below is the list of all modifiers plus some additional examples.

For every mugur-key there is either a direct correspondence with a qmk-keycode or with a qmk functionality (like a macro, for example). For a list of all these basic codes that one can use in the layout, consult the mugur-symbol function as defined in mugur.el. For the special keys, like macros, one-shot and the rest, see below.

Mod-tap

When pressed, the modifier is active, when tapped the key is sent.

Modifiers

Allows key combinations like the familiar emacs's M-x, that is, hold down the Meta modifier and press x.

One Shot Keys

One shot keys are keys that remain active until the next key is pressed, and then are released (qmk documentation)

Layer Toggle

Switching and toggling layers.

Macros

Send any key combination that does not qualify as anything else.

Tap Dance

Hit a key once, send a key. Hit it twice in quick succession, send a different one. The tap dance functionality is only valid for two basic mugur-keycodes (letter, digits, punctuation, commands, etc), and not for layers nor macros. mugur-tapdance-enable must be set to "yes" for this to work, otherwise look out for error: implicit declaration of function ‘ACTION_TAP_DANCE_DOUBLE’ when building.

Leader Key

Tap the Leader Key and then up to five keys in quick succession, before the LEADER_TIMEOUT expires, and send whatever macro you like. Use the mugur-leader-keys to setup what keys do what,

(setf mugur-leader-keys
      '(((s d f) "s, d and then f")
        ((z)     (M-x "kill"))))

In the above example, tapping the Leader Key, followed by s, d and then f will send the given string. The mugur-key after the first list, must be a valid macro. The Leader Key is the mugur-key named lead and can appear anywhere on your keymap.

Combos

Hit two keys at once and send a different key. Set mugur-combo-keys to setup what key combinations do what,

(setf mugur-combo-keys
      '(((a b) x)
        ((1 2) ?\.)))

In this example, pressing both a and b at the same time would send x. Pressing 1 and 2 would send the symbol .. Adjust the mugur-combo-term delay for the perfect experience.

Emacs keybound functions

For Emacs functions that have a keybinding, the function name can be directly specified as a mugur-key.

User Defined Keys

For long or often-used mugur-key sequences, or simply as a mnemonic, the mugur-user-defined-keys contains a list of items, where the car of the item is the mnemonic and the cadr is any valid mugur-key.

(setf mugur-user-define-keys
      '((uname        "my_badass_username")
        (weird_key    (C-c a "right?" ENT))))

Insert raw C code (advanced users)

All code generated by mugur is found between START-MUGUR-REGION and END-MUGUR-REGION comment. For keyboard-specific code, for exploring different configurations by hand or for features not yet or ever to be provided by mugur, you can write your own C code or makefile options outside these mugur regions,

this is my own code

// START-MUGUR-REGION

This is code generated by mugur, in keymap.c, rules.mk or config.h files.
The code between these regions is replaced on subsequent mugur-mugur calls.

// END-MUGUR-REGION

I can do whatever I want in my own region of code,
and mugur won't touch it

Configuration

Paths and names

mugur-qmk-path nil

Path to the qmk firmware source code (root folder).

mugur-keyboard-name nil

The name of your qmk keyboard."

mugur-layout-name nil

The keymap name used in the keymaps matrix.
Check the 'uint16_t keymaps' matrix in the default keymap.c of
your keyboard.  Some have just "LAYOUT", others
"LAYOUT_ergodox", etc. Adapt accordingly.

mugur-keymap-name nil

The name of qmk keymap generated by mugur.

Configs (config.h)

mugur-tapping-term 180

Tapping term, in ms.
This is the maximum time allowed between taps of your Tap Dance
mugur-key.

mugur-combo-term 300

Combo term, in ms.
This is the maximum time allowed between two keypresses in which
they might be considered as Combos.

mugur-leader-timeout 300

Timeout for the Leader Key, in ms.
This is the time to wait to complete the Leader Key sequence
after you press the Leader Key key.

mugur-leader-per-key-timing nil

Enable or disable LEADER_PER_KEY_TIMING option.
If enabled, the Leader Key timeout is reset after each key is
tapped.

Special Keys

mugur-leader-keys nil

List of Leader Keys and their expansion.
The items are lists, where the car is a list of valid mugur-keys
and the cadr is a valid mugur-macro.

mugur-combo-keys nil

List of Combo Keys and their expansion.
The items are lists, where the car is a list of two valid
mugur-keys and the cadr is a valid mugur-key.

mugur-user-defined-keys nil

User defined keys for long or often used combinations.
A list of lists, where the car of each entry is a symbol (a name
for the new key) and the cadr is any valid mugur-key.

mugur-ignore-key '-x-

The symbol used in the mugur-keymap for an ignored key.
This is transformed into the qmk-keycode KC_NO.

mugur-transparent-key '---

The symbol used in the mugur keymap for a transparent key.
This is transformed into the qmk-keycode KC_TRANSPARENT.

Supported Keyboards

Any keyboard that uses the QMK firmware. Users have reported success using mugur for the following keyboards,

Send me an email if you've used mugur for other keyboards successfully. If you have problems with a particular keyboard, open an issue with the keyboard name and the particular problem you're facing.

Other points

• Not all qmk features are supported, nor there is a plan to support them all.
• The layout structure that mugur accepts is the layout that qmk keymap.c is using for your particular keyboard (check the qmk_firmware sourcecode). There is a one-to-one correspondence to what is defined in a mugur-layout and what you see in the qmk-layout. In short, no vertical or horizontal reordering of the keys is supported nor planned to.
• There is no support to define which LEDs to turn on/off for which mugur-layer, nor there is a plan to support such a feature.
• The mugur package generates the qmk-layout, but does not build nor flashes it on your keyboard. The layout name and location is based on the values of the custom variables given by the user (see the configuration section). Consult the qmk documentation and your keyboard README for how to build and flash your keyboard.

Full Examples

Ergodox

This is a full example for a mugur configuration of an Ergodox keyboard.

(let ((mugur-qmk-path        "/home/mihai/projects/qmk_firmware")
      (mugur-keyboard-name   "ergodox_ez")
      (mugur-layout-name     "LAYOUT_ergodox")
      (mugur-keymap-name     "mugur_test")
      (mugur-tapping-term    175)
      (mugur-user-defined-keys '((email  "[email protected]")
                                 (replay (C-x e)))))
                                 
  (mugur-mugur
   '(("base" 
      C-f1    vol-down  vol-up   -x-   -x-  -x- reset
       -x-     (C-x k)     w      e     r    t  replay
       -x-        a      (G s)  (M d) (C f)  g 
     (OSM S)      z        x      c     v    b  email
       -x-       -x-      -x-    -x-   tab
     
                                           tab   -x-
                                                 -x-
                                   bspace space  -x-
       
       -x- -x-  -x-     -x-      -x-  -x-    -x-
       -x-  y    u   (LT NUM i)   o   -x-    -x-
            h  (C j)   (M k)    (G l)  p     -x-
       -x-  n    m     comma     dot   q   (OSM S)
                -x-      up     down  left  right
     
       -x-               -x-
       (C-x b)
       (LT media escape) (LT movement ent) (LT symbols pscreen))

     ("num"
      --- --- --- --- --- --- ---
      --- ---  1   2   3  --- --- 
      ---  0   4   5   6  --- 
      ---  0   7   8   9  --- --- 
      --- --- --- --- --- 
                          --- --- 
                              ---
                      --- --- ---

      --- --- --- --- --- --- ---
      --- --- --- --- --- --- ---
          --- --- --- --- --- ---
      --- --- --- --- --- --- ---
              --- --- --- --- ---
      --- ---
      ---
      --- --- ---)

     ("movement"
      ---  ---       ---      ---     ---    --- --- 
      ---  ---  (C-u C-space)  up   S-insert M-< --- 
      ---  C-a      left      down   right   C-e 
      ---  undo      ---      ---     ---    M-> ---
      ---  ---       ---      ---     --- 
      ---  --- 
      ---
      delete C-tab ---
    
      --- ---      ---                ---                 ---       --- ---
      --- ---      ---          sp-backward-up-sexp       ---       --- ---
          --- sp-backward-sexp        ---           sp-forward-sexp --- ---
      --- ---      ---                ---                 ---       --- ---
                   ---                ---                 ---       --- ---
      --- ---
      ---
      --- --- ---)

     ("symbols"
      ---  ---  ?\[  ?\]  ?\{  ?\}  ---
      ---  ?\~  ---  ?\'  ?\"  ?\`  ---
      ---  ?\;  ?\:  ?\-  ?\(  ?\) 
      ---  ?\/  ?\\  ?\=  ?\+  ?\_  ---
      ---  ---  ?\|  ?\<  ?\> 
      ---  ---
      ---
      ?\! ?\? ---
    
      --- --- --- --- --- --- ---
      --- --- --- --- --- --- ---
          --- --- --- --- --- ---
      --- --- --- --- --- --- ---
      --- --- --- --- ---
      --- ---
      ---
      --- --- ---)

     ("media"
      ---       ---        ---     ---        ---     --- --- 
      rgb_sad  rgb_sai     ---    ms_up    ms_wh_up   --- ---
      rgb_vad  rgb_vai  ms_left  ms_down   ms_right   --- 
      rgb_hud  rgb_hui     ---     ---    ms_wh_down  --- ---
      rgb_tog    ---       ---     ---        --- 
      --- ---
      --- 
      ms_btn2  ms_btn1  ms_btn3
    
      --- --- --- --- --- --- ---
      --- --- --- --- --- --- ---
          --- --- --- --- --- ---
      --- --- --- --- --- --- ---
              --- --- --- --- ---
      --- ---
      ---
      --- --- ---))))

Corne

Full example for a mugur configuration of a corne keyboard kindly provided by Nik Gaffney. See details on his crbkd github page.

(let ((mugur-qmk-path       "~/qmk_firmware")
      (mugur-keyboard-name   "crkbd")
      (mugur-layout-name     "LAYOUT_split_3x6_3")
      (mugur-keymap-name     "zzkt4")
      (mugur-tapping-term    175))

 (mugur-mugur
  '(("base"
      tab  q   w   e   r   t      y   u   i   o    p   bspace
      C    a   s   d   f   g      h   j   k   l   ?\;  (LT move ?\')
      S    z   x   c   v   b      n   m  ?\, dot  ?\?  (MO qmik)
     (MO emacs) lapo (G space)   ent rapc (TG numeric))

     ("numeric"
       ~  ?\!  ?\@  ?\# ?\$ ?\%     ?\^  ?\&  ?\*   -   =  bspace
       0   1    2    3   4    5      6    7    8    9   0  (LT move ent)
       S  --- ?\< ?\{  ?\[  ?\(     ?\)  ?\]  ?\}  ?\>  |  (MO emacs)
               (TG qmik) C-M ---   --- S (TG numeric))

     ("move"
       --- M-v   up   ---  --- ---    --- --- --- --- --- ---
       C-a left down right C-e ---    --- --- --- --- --- ---
       --- M-<  C-v   M->  --- ---    --- --- --- --- --- ---
                        --- --- ---  ---  --- --- )

     ("emacs"
       esc  --- --- (C-x 0) (C-x 2) (C-x 3)   (C-x 4 t)  --- --- --- --- ---
       ---  --- M-% --- --- (M-x "gtd" ent)   (C-x b)    --- --- "λ" --- ---
      reset --- M-x C-c ---  ?\(               ?\)  (M-x "magit" ent) --- --- --- ---
                     --- ---  (H-i e)             (C-x 8) --- (MO hypm))

     ("hypm"
        --- --- --- --- --- ---    --- --- H-i  (H-i o) (H-i l) ---
        --- --- --- H-d --- ---    --- --- ---  --- --- ---
        --- --- --- --- --- ---    --- H-m (H-m s) --- --- ---
                     --- --- ---  ---  --- --- )

     ("qmik"
       ---    rgb_tog rgb_mod --- --- ---    --- --- --- --- --- reset
      rgb_sad rgb_vad rgb_hud --- --- ---    --- --- --- --- --- ---
      rgb_sai rgb_vai rgb_hui --- --- ---    --- --- --- ---  S  ---
                               --- --- ---  ---  --- --- )
     )))