zzkt/charybdis

🔀 An emacs centric keymap for the Charybdis keyboard

QMK config for Charybdis

Charybdis is an ergonomic keyboard using a split 4x6 layout (or 3x5) with 5+3 thumb keys and integrated trackball.

The keyboard can be programmed using QMK firmware for the charybdis (which currently requires the CNano branch of QMK) With the help of mugur (and org-mode) this file can be used as a literate config to generate a keymap and the relevant build files for the QMK firmware…

For reference, comparison and reading the Crkbd Keymap by Manna Harbour and drashna provide good examples of detailed configs, and the QMK tree has further specifics with a wide range of examples.

see also KLE layers (pt.1) and KLE layers (pt.2) etc.

general principles

This config uses a mulit-layer qwerty layout which has emerged from a combination of writing and programming using emacs (and emacs style keybindings) on macos and linux. The numeric layer has numbers on the home row and shifted symbols on the row above, with commonly used brackets on the lowest row symmetrically between sides. The emacs layer(s) provide both command and prefix keys. The movement layer provides arrows (as WASD and HJKL) and jump keys on the left. When the mouse layer is active the keys above the trackball can be used as mouse buttons. There is a QMK reset key on each half of the keyboard.

specific mappings

Details of keyboard layout, layers, macros and general confusion can be found in the QMK docs

Layers

• qwerty and modifiers
• numbers, symbols & brackets
• movement. arrows & jump
• emacs layers
• mouse layer

Trackball

• mounted on the right half
• uses keys above the trackball as mouse buttons (i.e. M, comma, and dot with qwerty layout)
• sniping, drag_scroll, etc

Modifiers

• Left thumb (base layer) Alt/Meta, space and GUI (held) or space (tap) on top row, with Emacs layer and KC_LAPO below
• Right thumb (base layer) Tap toggle numeric layer, Enter (tap) or Right GUI (held) on top row and KC_RAPC below

The KC_LAPO key is Left Alt when held and ( when tapped, it can be used as Meta. The KC_RAPC key is Right Alt when held and ) when tapped, it can be used for accents and non-ascii characters with the international macOS input sources.

The emacs layer is activated with Left-thumb (k45) and the hypm layer can be activated with (k80) and can be used to provide the H- prefix bindings defined in .emacs The hyper key seen by emacs can be mapped to KC_RGUI rather than the KC_HYPR modifier combination (see also the “the infamous Apple Fn key” for compatibility)

QMK Reset

• Left. k45 & k30
• Right. k70 & k80

To create a new layer, start with a blank layer.

("blank"
 --- --- --- --- --- ---    --- --- --- --- --- ---
 --- --- --- --- --- ---    --- --- --- --- --- ---
 --- --- --- --- --- ---    --- --- --- --- --- ---
 --- --- --- --- --- ---    --- --- --- --- --- ---
              --- --- ---  --- --- -x-
                  --- ---  --- -x-)

Details of the mugur keycode naming can be found in the documentation of mugur--symbol

(find-function 'mugur--symbol)

A complete keymap can be defined within mugur-mugur which will generate the required files to build the firmware.

(require 'mugur)

(let ((mugur-qmk-path       "~/code/keyboards/Charybdis/qmk")
      (mugur-keyboard-name  "bastardkb/charybdis/4x6")
      (mugur-layout-name    "LAYOUT_split_4x6_5")
      (mugur-keymap-name    "zzkt")
      (mugur-tapping-term    175))

 (mugur-mugur
  '(("base"
        esc          1   2   3   4   5          6   7   8    9    0               bspace
        tab          q   w   e   r   t          y   u   i    o    p               -
         C           a   s   d   f   g          h   j   k    l  scolon           (LT move ?\')
    (S up) (LT mouse z)  x   c   v   b          n   m comma dot (LT mouse slash) (LT hypm down)
                      M  space  (G spc)       (TT numeric)  (G ent)  -x-
                        (MO emacs) lapo       rapc  -x-)

     ("numeric"
       "~"       ?\!   ?\@   ?\#  ?\$  ?\%     ?\^  ?\&  ?\*   _   +  bspace
       tab       ?\!   ?\@   ?\#  ?\$  ?\%     ?\^  ?\&  ?\*   -   =  ---
        0         1     2     3    4    5       6    7    8    9   0  (LT move ent)
       (S left)  "`"   ?\\   ?\\  ?\{  ?\[     ?\]  ?\} comma dot  |  (S right)
                                --- --- ---   --- enter -x-
                            (TG mouse) lapo   rapc  -x-)

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

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

     ("hypm"
         x  --- --- --- --- ( C-a "* " )    ---     ---    ---      ---     ---   ---
         x  --- --- --- ---  "  - [ ] "     ---     ---     H-i   (H-i o) (H-i l) ---
        --- --- --- H-d ---  "  - "         ---     ---     ---     ---     ---   reset
        --- --- --- --- ---    ---          (H-m n) (H-m m) (H-m s) ---     ---   ---
                       --- --- ---      ---  --- -x-
                          ---  ---      ---  -x-)

     ("mouse"
       --- --- --- --- --- ---                         --- --- --- --- --- ---
       --- "SNIPER_CONFIG" --- --- --- ---             --- --- --- --- --- ---
       --- "DPI_CONFIG" "DRAG_SCROLL" --- --- ---      --- --- "DRAG_SCROLL" --- --- ---
       --- --- --- --- --- ---                         --- btn1 btn2 btn3 --- ---
                                    btn2 btn1 G     --- --- -x-
                                            C S     --- -x-)
     )))

an optional base config for Colemak

("colemak"
        esc    1   2   3   4   5      6   7   8    9     0      bspace
        tab    q   w   f   p   g      j   l   u    y   scolon     -
         C     a   r   s   t   d      h   n   e    i     o    (LT move ?\')
     (LT S up) z   x   c   v   b      k   m comma dot  slash  (LT hypm down)
         (MO emacs) lapo (G space)  ent rapc (TT numeric))

keymap.c

This will generate a keymap.c file with org-babel-tangle and should be run before the elisp code block for the keymap described above.

#include QMK_KEYBOARD_H
#include "version.h"
#include "split_util.h"

mugur will write the keymap and only overwrite the region between these comments.

// START-MUGUR-REGION
// END-MUGUR-REGION

turn on (or off) debug info (check that CONSOLE_ENABLE is set accordingly in rules.mk )

void keyboard_post_init_user(void) {
  // debug_enable=true;
  // debug_matrix=true;
  // debug_keyboard=true;
  // debug_mouse=true;
}

rules.mk

this will create a rules.mk file with some specifics for the Charybdis

# START-MUGUR-REGION
# END-MUGUR-REGION

# MCU name
MCU = atmega32u4

# Bootloader selection
BOOTLOADER         = atmel-dfu

SPLIT_KEYBOARD     = yes

# uncode
UNICODE_ENABLE     = yes

# Build Options
BOOTMAGIC_ENABLE   = no    # Bootmagic Lite
EXTRAKEY_ENABLE    = yes   # Audio control and System control
CONSOLE_ENABLE     = yes   # Console for debug
COMMAND_ENABLE     = no    # Commands for debug and configuration
NKRO_ENABLE        = no    # USB Nkey Rollover

# trackball & mousekeys
MOUSEKEY_ENABLE        = yes
POINTING_DEVICE_ENABLE = yes
MOUSE_SHARED_EP        = no

#  enable configuraiton with VIA
VIA_ENABLE             = no

# No lighting or audio
SLEEP_LED_ENABLE  = no    # Breathing sleep LED during USB suspend
BACKLIGHT_ENABLE  = no    # Enable keyboard backlight functionality
RGBLIGHT_ENABLE   = no    # Enable keyboard RGB underglow
AUDIO_ENABLE      = no    # Audio output
RGB_MATRIX_ENABLE = no

# trackpad driver
SRC += drivers/sensors/pmw3360.c
QUANTUM_LIB_SRC += spi_master.c

# enable Link Time Optimization to reduce firmware size
# see also https://thomasbaart.nl/2018/12/01/reducing-firmware-size-in-qmk/
EXTRAFLAGS += -flto

config.h

This will generate a config.h file

// START-MUGUR-REGION
// END-MUGUR-REGION

#define EE_HANDS

…and some layers

#define DYNAMIC_KEYMAP_LAYER_COUNT 6

taping timing and tap/hold (as seen in the QMK docs)

#define TAPPING_TERM 175
#define COMBO_TERM 300
#define PERMISSIVE_HOLD

Unicode input method (tangle as required)

#define UNICODE_SELECTED_MODES UC_MAC

#define UNICODE_SELECTED_MODES UC_LNX, UC_MAC

The mouse layer can activate auotosniping

#undef CHARYBDIS_AUTO_SNIPER_LAYER
#define CHARYBDIS_AUTO_SNIPER_LAYER 5

for VIA compatibility (if needed)

VENDOR_ID  0x43256
PRODUCT_ID 0x6195

build (generate, compile and flash cycle)

first tangle this file

(org-babel-tangle)

then write the keymap as defined above

<<keymap()>>

then compile and/or write to the keyboard

qmk compile -kb bastardkb/charybdis/4x6 -km zzkt

flash the firmware one side at a time. if EE_HANDS is enabled, the same command can be used for both sides.

qmk flash -kb bastardkb/charybdis/4x6 -km zzkt -bl dfu

without EE_HANDS or to set handedness the first time…

qmk flash -km zzkt -bl dfu-split-left

qmk flash -km zzkt -bl dfu-split-right

further

• Charybdis kits, code, stl files and docs from Bastard Keyboards
• Build log - Quentin LEBASTARD
• Keyboard Layouts (wikipedia)