diff --git a/docs/debugging.md b/docs/debugging.md new file mode 100644 index 0000000..6080074 --- /dev/null +++ b/docs/debugging.md @@ -0,0 +1,11 @@ +#Debugging +Debug will output most of the useful state to the console. This can be enable in your firmware +by setting this in your keymap. NOTE that it will be MUCH slower, so only enable this when you +need debugging. +```python +DEBUG_ENABLE = True +``` + +The output can be viewed by connecting to the serial port of the keybord. Please refer to [THIS](https://learn.adafruit.com/welcome-to-circuitpython/kattni-connecting-to-the-serial-console) for +more information when connecting to serial console. For Linux users, we recommend [picocom](https://github.com/npat-efault/picocom) or +[screen](https://www.gnu.org/software/screen/manual/screen.html) \ No newline at end of file diff --git a/docs/flashing.md b/docs/flashing.md new file mode 100644 index 0000000..53b7829 --- /dev/null +++ b/docs/flashing.md @@ -0,0 +1,18 @@ +# Flashing Instructions + +Flashing sequence: + +1. Press the `KC.RESET` keycode, or tap the RESET button. +2. Wait for the OS to detect the device +3. Flash a .hex file (May be done automatically) +4. Reset the device into application mode (May be done automatically) + +or: + + make flash- USER_KEYMAP=user_keymaps/... + +Example: + + make flash-feather-m4-express USER_KEYMAP=user_keymaps/kdb424/handwire_planck_featherm4.py + + diff --git a/docs/hardware.md b/docs/hardware.md new file mode 100644 index 0000000..d7e0c3c --- /dev/null +++ b/docs/hardware.md @@ -0,0 +1,48 @@ +## Supported Devices + +| Board | Chipset | Python Platform | Notes | +| ----- | ------- | --------------- | ----- | +| [Adafruit Feather M4 Express](https://www.adafruit.com/product/3857) | Atmel SAMD51 (Cortex M4F) | CircuitPython | An economical solution for basic USB keyboards | +| [Adafruit ItsyBitsy M4 Express](https://www.adafruit.com/product/3800) | Atmel SAMD51 (Cortex M4F) | CircuitPython | A smaller solution for basic USB keyboards | + +## Community Supported +| Board | Chipset | Python Platform | Maintainer | Notes | +| ----- | ------- | --------------- | ----- | ----- | +| [pyboard v1.1](https://www.adafruit.com/product/2390) | STM32F405RG (Cortex M4F) | MicroPython | kdb424 | Very large and expensive, and has ram limitations. | + +## Support Planned/WIP +| Board | Chipset | Python Platform | Notes | +| ----- | ------- | --------------- | ----- | +| [Seeed nRF52840 Micro Dev Kit](https://www.seeedstudio.com/nRF52840-Micro-Development-Kit-p-3079.html) | nRF52840 | [CircuitPython](https://github.com/KMKfw/circuitpython/tree/topic-nrf52840-mdk) | This is basically as bleeding edge as it gets. Will support BLE HID to PC as well as BLE split boards | +| [Planck rev6 Keyboard](https://olkb.com/planck) | STM32 of some sort | MicroPython | Requires porting MicroPython to STM32F3, this work has begun but I'm pretty terrible at it. | +| [Proton C Controller?](https://www.reddit.com/r/MechanicalKeyboards/comments/87cw36/render_of_the_qmk_proton_c_qmkpowered_pro_micro/) | ??? | ??? | Does not exist yet, the controller from a Planck rev6 in a Pro Micro pin-compat controller chip | + + +## Unsupported Devices + + +Here's a list of problematic, but possibly usable microcontrollers: + +| Board | Chipset | Python Platform | Notes | +| ----- | ------- | --------------- | ------------------ | +| [Adafruit Feather Huzzah](https://www.adafruit.com/product/2821) | ESP8266 | CircuitPython | Suuuuuper limited on GPIO lanes, Lack USB HID (HW) | +| [Adafruit HUZZAH32](https://www.adafruit.com/product/3405) | ESP32 | MicroPython | This may work as a BLE HID device, or with a GPIO-based USB breakout. Lacks USB HID (HW) | +| [Adafruit Feather nRF52 BLE Controller](https://www.adafruit.com/product/3406) | nRF52832 | CircuitPython | Lacks USB HID (HW), but could be fixed with GPIO USB breakout. BLE HID should be possible, but it's considered somewhat unstable. This chip is considered "mostly unsupported" in CircuitPython at the time of writing. | + +## Porting new devices +Pull requests are welcome and encouraged to add support for new +keyboards/microcontrollers. The base requirements for device support +- CircuitPython or MicroPython +- 256KB of flash storage +- HID over USB or Bluetooth. + +## Secondary Support + +In the future, secondary support for lesser contollers is planned. One of +these cases is the pro micro being used for a slave half of a split keyboard +while all actual work is being done by a supported board. This could also be +used to convert boards that use USB or i2c that run lesser chips to a KMK +board, with a supported board acting as a translation layer. Support for +a converter is planned with the inspiration coming from the [Hasu USB to +USB Controller Converter](https://www.1upkeyboards.com/shop/controllers/usb-to-usb-converter/) and would allow for conversion to KMK as +opposed to TMK or QMK with that board. \ No newline at end of file diff --git a/docs/keycodes.md b/docs/keycodes.md new file mode 100644 index 0000000..bfebe8d --- /dev/null +++ b/docs/keycodes.md @@ -0,0 +1,292 @@ +# Keycodes Overview + +## [Basic Keycodes] + +|Key |Aliases |Description | +|-----------------------|--------------------|-----------------------------------------------| +|`KC.NO` | |Ignore this key (NOOP) | +|`KC.TRANSPARENT` |`KC.TRNS` |Use the next lowest non-transparent key | +|`KC.A` | |`a` and `A` | +|`KC.B` | |`b` and `B` | +|`KC.C` | |`c` and `C` | +|`KC.D` | |`d` and `D` | +|`KC.E` | |`e` and `E` | +|`KC.F` | |`f` and `F` | +|`KC.G` | |`g` and `G` | +|`KC.H` | |`h` and `H` | +|`KC.I` | |`i` and `I` | +|`KC.J` | |`j` and `J` | +|`KC.K` | |`k` and `K` | +|`KC.L` | |`l` and `L` | +|`KC.M` | |`m` and `M` | +|`KC.N` | |`n` and `N` | +|`KC.O` | |`o` and `O` | +|`KC.P` | |`p` and `P` | +|`KC.Q` | |`q` and `Q` | +|`KC.R` | |`r` and `R` | +|`KC.S` | |`s` and `S` | +|`KC.T` | |`t` and `T` | +|`KC.U` | |`u` and `U` | +|`KC.V` | |`v` and `V` | +|`KC.W` | |`w` and `W` | +|`KC.X` | |`x` and `X` | +|`KC.Y` | |`y` and `Y` | +|`KC.Z` | |`z` and `Z` | +|`KC.N1` | |`1` and `!` | +|`KC.N2` | |`2` and `@` | +|`KC.N3` | |`3` and `#` | +|`KC.N4` | |`4` and `$` | +|`KC.N5` | |`5` and `%` | +|`KC.N6` | |`6` and `^` | +|`KC.N7` | |`7` and `&` | +|`KC.N8` | |`8` and `*` | +|`KC.N9` | |`9` and `(` | +|`KC.N0` | |`0` and `)` | +|`KC.ENTER` |`KC.ENT` |Return (Enter) | +|`KC.ESCAPE` |`KC.ESC` |Escape | +|`KC.BSPACE` |`KC.BSPC` |Delete (Backspace) | +|`KC.TAB` | |Tab | +|`KC.SPACE` |`KC.SPC` |Spacebar | +|`KC.MINUS` |`KC.MINS` |`-` and `_` | +|`KC.EQUAL` |`KC.EQL` |`=` and `+` | +|`KC.LBRACKET` |`KC.LBRC` |`[` and `{` | +|`KC.RBRACKET` |`KC.RBRC` |`]` and `}` | +|`KC.BSLASH` |`KC.BSLS` |`\` and | | +|`KC.NONUS_HASH` |`KC.NUHS` |Non-US `#` and `~` | +|`KC.SCOLON` |`KC.SCLN` |`;` and `:` | +|`KC.QUOTE` |`KC.QUOT` |`'` and `"` | +|`KC.GRAVE` |`KC.GRV`, `KC.ZKHK` |` and `~`, JIS Zenkaku/Hankaku| +|`KC.COMMA` |`KC.COMM` |`,` and `<` | +|`KC.DOT` | |`.` and `>` | +|`KC.SLASH` |`KC.SLSH` |`/` and `?` | +|`KC.CAPSLOCK` |`KC.CLCK`, `KC.CAPS`|Caps Lock | +|`KC.F1` | |F1 | +|`KC.F2` | |F2 | +|`KC.F3` | |F3 | +|`KC.F4` | |F4 | +|`KC.F5` | |F5 | +|`KC.F6` | |F6 | +|`KC.F7` | |F7 | +|`KC.F8` | |F8 | +|`KC.F9` | |F9 | +|`KC.F10` | |F10 | +|`KC.F11` | |F11 | +|`KC.F12` | |F12 | +|`KC.PSCREEN` |`KC.PSCR` |Print Screen | +|`KC.SCROLLLOCK` |`KC.SLCK` |Scroll Lock | +|`KC.PAUSE` |`KC.PAUS`, `KC.BRK` |Pause | +|`KC.INSERT` |`KC.INS` |Insert | +|`KC.HOME` | |Home | +|`KC.PGUP` | |Page Up | +|`KC.DELETE` |`KC.DEL` |Forward Delete | +|`KC.END` | |End | +|`KC.PGDOWN` |`KC.PGDN` |Page Down | +|`KC.RIGHT` |`KC.RGHT` |Right Arrow | +|`KC.LEFT` | |Left Arrow | +|`KC.DOWN` | |Down Arrow | +|`KC.UP` | |Up Arrow | +|`KC.NUMLOCK` |`KC.NLCK` |Keypad Num Lock and Clear | +|`KC.KP_SLASH` |`KC.PSLS` |Keypad `/` | +|`KC.KP_ASTERISK` |`KC.PAST` |Keypad `*` | +|`KC.KP_MINUS` |`KC.PMNS` |Keypad `-` | +|`KC.KP_PLUS` |`KC.PPLS` |Keypad `+` | +|`KC.KP_ENTER` |`KC.PENT` |Keypad Enter | +|`KC.KP_1` |`KC.P1` |Keypad `1` and End | +|`KC.KP_2` |`KC.P2` |Keypad `2` and Down Arrow | +|`KC.KP_3` |`KC.P3` |Keypad `3` and Page Down | +|`KC.KP_4` |`KC.P4` |Keypad `4` and Left Arrow | +|`KC.KP_5` |`KC.P5` |Keypad `5` | +|`KC.KP_6` |`KC.P6` |Keypad `6` and Right Arrow | +|`KC.KP_7` |`KC.P7` |Keypad `7` and Home | +|`KC.KP_8` |`KC.P8` |Keypad `8` and Up Arrow | +|`KC.KP_9` |`KC.P9` |Keypad `9` and Page Up | +|`KC.KP_0` |`KC.P0` |Keypad `0` and Insert | +|`KC.KP_DOT` |`KC.PDOT` |Keypad `.` and Delete | +|`KC.NONUS_BSLASH` |`KC.NUBS` |Non-US `\` and | | +|`KC.APPLICATION` |`KC.APP` |Application (Windows Menu Key) | +|`KC.POWER` | |System Power (macOS) | +|`KC.KP_EQUAL` |`KC.PEQL` |Keypad `=` | +|`KC.F13` | |F13 | +|`KC.F14` | |F14 | +|`KC.F15` | |F15 | +|`KC.F16` | |F16 | +|`KC.F17` | |F17 | +|`KC.F18` | |F18 | +|`KC.F19` | |F19 | +|`KC.F20` | |F20 | +|`KC.F21` | |F21 | +|`KC.F22` | |F22 | +|`KC.F23` | |F23 | +|`KC.F24` | |F24 | +|`KC.EXECUTE` |`KC.EXEC` |Execute | +|`KC.HELP` | |Help | +|`KC.MENU` | |Menu | +|`KC.SELECT` |`KC.SLCT` |Select | +|`KC.STOP` | |Stop | +|`KC.AGAIN` |`KC.AGIN` |Again | +|`KC.UNDO` | |Undo | +|`KC.CUT` | |Cut | +|`KC.COPY` | |Copy | +|`KC.PASTE` |`KC.PSTE` |Paste | +|`KC.FIND` | |Find | +|`KC._MUTE` | |Mute (macOS) | +|`KC._VOLUP` | |Volume Up (macOS) | +|`KC._VOLDOWN` | |Volume Down (macOS) | +|`KC.LOCKING_CAPS` |`KC.LCAP` |Locking Caps Lock | +|`KC.LOCKING_NUM` |`KC.LNUM` |Locking Num Lock | +|`KC.LOCKING_SCROLL` |`KC.LSCR` |Locking Scroll Lock | +|`KC.KP_COMMA` |`KC.PCMM` |Keypad `,` | +|`KC.KP_EQUAL_AS400` | |Keypad `=` on AS/400 keyboards | +|`KC.INT1` |`KC.RO` |JIS `\` and | | +|`KC.INT2` |`KC.KANA` |JIS Katakana/Hiragana | +|`KC.INT3` |`KC.JYEN` |JIS `¥` | +|`KC.INT4` |`KC.HENK` |JIS Henkan | +|`KC.INT5` |`KC.MHEN` |JIS Muhenkan | +|`KC.INT6` | |JIS Numpad `,` | +|`KC.INT7` | |International 7 | +|`KC.INT8` | |International 8 | +|`KC.INT9` | |International 9 | +|`KC.LANG1` |`KC.HAEN` |Hangul/English | +|`KC.LANG2` |`KC.HANJ` |Hanja | +|`KC.LANG3` | |JIS Katakana | +|`KC.LANG4` | |JIS Hiragana | +|`KC.LANG5` | |JIS Zenkaku/Hankaku | +|`KC.LANG6` | |Language 6 | +|`KC.LANG7` | |Language 7 | +|`KC.LANG8` | |Language 8 | +|`KC.LANG9` | |Language 9 | +|`KC.ALT_ERASE` |`KC.ERAS` |Alternate Erase | +|`KC.SYSREQ` | |SysReq/Attention | +|`KC.CANCEL` | |Cancel | +|`KC.CLEAR` |`KC.CLR` |Clear | +|`KC.PRIOR` | |Prior | +|`KC.RETURN` | |Return | +|`KC.SEPARATOR` | |Separator | +|`KC.OUT` | |Out | +|`KC.OPER` | |Oper | +|`KC.CLEAR_AGAIN` | |Clear/Again | +|`KC.CRSEL` | |CrSel/Props | +|`KC.EXSEL` | |ExSel | +|`KC.LCTRL` |`KC.LCTL` |Left Control | +|`KC.LSHIFT` |`KC.LSFT` |Left Shift | +|`KC.LALT` | |Left Alt | +|`KC.LGUI` |`KC.LCMD`, `KC.LWIN`|Left GUI (Windows/Command/Meta key) | +|`KC.RCTRL` |`KC.RCTL` |Right Control | +|`KC.RSHIFT` |`KC.RSFT` |Right Shift | +|`KC.RALT` | |Right Alt | +|`KC.RGUI` |`KC.RCMD`, `KC.RWIN`|Right GUI (Windows/Command/Meta key) | +|`KC.SYSTEM_POWER` |`KC.PWR` |System Power Down | +|`KC.SYSTEM_SLEEP` |`KC.SLEP` |System Sleep | +|`KC.SYSTEM_WAKE` |`KC.WAKE` |System Wake | +|`KC.AUDIO_MUTE` |`KC.MUTE` |Mute | +|`KC.AUDIO_VOL_UP` |`KC.VOLU` |Volume Up | +|`KC.AUDIO_VOL_DOWN` |`KC.VOLD` |Volume Down | +|`KC.MEDIA_NEXT_TRACK` |`KC.MNXT` |Next Track (Windows) | +|`KC.MEDIA_PREV_TRACK` |`KC.MPRV` |Previous Track (Windows) | +|`KC.MEDIA_STOP` |`KC.MSTP` |Stop Track (Windows) | +|`KC.MEDIA_PLAY_PAUSE` |`KC.MPLY` |Play/Pause Track | +|`KC.MEDIA_SELECT` |`KC.MSEL` |Launch Media Player (Windows) | +|`KC.MEDIA_EJECT` |`KC.EJCT` |Eject (macOS) | +|`KC.MAIL` | |Launch Mail (Windows) | +|`KC.CALCULATOR` |`KC.CALC` |Launch Calculator (Windows) | +|`KC.MY_COMPUTER` |`KC.MYCM` |Launch My Computer (Windows) | +|`KC.WWW_SEARCH` |`KC.WSCH` |Browser Search (Windows) | +|`KC.WWW_HOME` |`KC.WHOM` |Browser Home (Windows) | +|`KC.WWW_BACK` |`KC.WBAK` |Browser Back (Windows) | +|`KC.WWW_FORWARD` |`KC.WFWD` |Browser Forward (Windows) | +|`KC.WWW_STOP` |`KC.WSTP` |Browser Stop (Windows) | +|`KC.WWW_REFRESH` |`KC.WREF` |Browser Refresh (Windows) | +|`KC.WWW_FAVORITES` |`KC.WFAV` |Browser Favorites (Windows) | +|`KC.MEDIA_FAST_FORWARD`|`KC.MFFD` |Next Track (macOS) | +|`KC.MEDIA_REWIND` |`KC.MRWD` |Previous Track (macOS) | + + +## [US ANSI Shifted Symbols] + +|Key |Aliases |Description | +|------------------------|-------------------|-------------------| +|`KC.TILDE` |`KC.TILD` |`~` | +|`KC.EXCLAIM` |`KC.EXLM` |`!` | +|`KC.AT` | |`@` | +|`KC.HASH` | |`#` | +|`KC.DOLLAR` |`KC.DLR` |`$` | +|`KC.PERCENT` |`KC.PERC` |`%` | +|`KC.CIRCUMFLEX` |`KC.CIRC` |`^` | +|`KC.AMPERSAND` |`KC.AMPR` |`&` | +|`KC.ASTERISK` |`KC.ASTR` |`*` | +|`KC.LEFT_PAREN` |`KC.LPRN` |`(` | +|`KC.RIGHT_PAREN` |`KC.RPRN` |`)` | +|`KC.UNDERSCORE` |`KC.UNDS` |`_` | +|`KC.PLUS` | |`+` | +|`KC.LEFT_CURLY_BRACE` |`KC.LCBR` |`{` | +|`KC.RIGHT_CURLY_BRACE` |`KC.RCBR` |`}` | +|`KC.PIPE` | ||| +|`KC.COLON` |`KC.COLN` |`:` | +|`KC.DOUBLE_QUOTE` |`KC.DQUO`, `KC.DQT`|`"` | +|`KC.LEFT_ANGLE_BRACKET` |`KC.LABK`, `KC.LT` |`<` | +|`KC.RIGHT_ANGLE_BRACKET`|`KC.RABK`, `KC.GT` |`>` | +|`KC.QUESTION` |`KC.QUES` |`?` | + + +## [Internal Keycodes] + +|Key |Description | +|-----------------------|---------------------------------------------------------------------| +|`KC.RESET` |Put the keyboard into DFU mode for flashing | +|`KC.GESC` |Escape when tapped, ` when pressed with Shift or GUI| +|`KC.LEAD` |The [Leader key] | +|`KC.UC_MODE_NOOP` |Sets UnicodeMode to NOOP | +|`KC.UC_MODE_LINUX` |Sets UnicodeMode to Linux | +|`KC.UC_MODE_MACOS` |Sets UnicodeMode to MocOS | +|`KC.UC_MODE_WINC` |Sets UnicodeMode to WinCompose | +|`KC.MACRO_SLEEP_MS(ms)`|Sleeps in a macro. Check MACROS for more information. | + + +## [Layer Switching] + +|Key |Description | +|-----------------|------------------------------------------------------------------------| +|`KC.DF(layer)` |Switches the default layer | +|`KC.MO(layer)` |Momentarily activates layer, switches off when you let go | +|`KC.LM(layer, mod)` |As `MO(layer)` but with `mod` active | +|`KC.LT(layer, kc)` |Momentarily activates layer if held, sends kc if tapped | +|`KC.TG(layer)` |Toggles the layer (enables it if no active, and vise versa) | +|`KC.TO(layer)` |Activates layer and deactivates all other layers | +|`KC.TT(layer)` |Momentarily activates layer if held, toggles it if tapped repeatedly | + + +## [Modifiers] + +|Key |Description | +|-------------|----------------------------------------------------| +|`KC.HYPR` |Hold Left Control, Shift, Alt and GUI | +|`KC.MEH` |Hold Left Control, Shift and Alt | +|`KC.LCTL(kc)`|Hold Left Control and press `kc` | +|`KC.LSFT(kc)`|Hold Left Shift and press `kc` | +|`KC.LALT(kc)`|Hold Left Alt and press `kc` | +|`KC.LGUI(kc)`|Hold Left GUI and press `kc` | +|`KC.RCTL(kc)`|Hold Right Control and press `kc` | +|`KC.RSFT(kc)`|Hold Right Shift and press `kc` | +|`KC.RALT(kc)`|Hold Right Alt and press `kc` | +|`KC.RGUI(kc)`|Hold Right GUI and press `kc` | + + +## [Mod-Tap Keys] NOT IMPLEMENTED AT THIS TIME + +|Key |Aliases |Description | +|------------|---------------------------------------|-------------------------------------------------------| +|`LCTL_T(kc)`|`CTL_T(kc)` |Left Control when held, `kc` when tapped | +|`RCTL_T(kc)`| |Right Control when held, `kc` when tapped | +|`LSFT_T(kc)`|`SFT_T(kc)` |Left Shift when held, `kc` when tapped | +|`RSFT_T(kc)`| |Right Shift when held, `kc` when tapped | +|`LALT_T(kc)`|`ALT_T(kc)` |Left Alt when held, `kc` when tapped | +|`RALT_T(kc)`|`ALGR_T(kc)` |Right Alt when held, `kc` when tapped | +|`LGUI_T(kc)`|`LCMD_T(kc)`, `RWIN_T(kc)`, `GUI_T(kc)`|Left GUI when held, `kc` when tapped | +|`RGUI_T(kc)`|`RCMD_T(kc)`, `RWIN_T(kc)` |Right GUI when held, `kc` when tapped | +|`C_S_T(kc)` | |Left Control and Shift when held, `kc` when tapped | +|`MEH_T(kc)` | |Left Control, Shift and Alt when held, `kc` when tapped| +|`LCAG_T(kc)`| |Left Control, Alt and GUI when held, `kc` when tapped | +|`RCAG_T(kc)`| |Right Control, Alt and GUI when held, `kc` when tapped | +|`ALL_T(kc)` | |Left Control, Shift, Alt and GUI when held, `kc` when tapped - more info [here](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)| +|`SGUI_T(kc)`|`SCMD_T(kc)`, `SWIN_T(kc)` |Left Shift and GUI when held, `kc` when tapped | +|`LCA_T(kc)` | |Left Control and Alt when held, `kc` when tapped | \ No newline at end of file diff --git a/docs/keymap.md b/docs/keymap.md new file mode 100644 index 0000000..2ce2242 --- /dev/null +++ b/docs/keymap.md @@ -0,0 +1,51 @@ +# Keymap +The keymap is a very simple set of instruction for your keyboard. +An example keymap for a 4x3 macro pad +```python +keymap = [ + [ + [KC.GESC, KC.A, KC.B], + [KC.C, KC.D, KC.E], + [KC.F, KC.G, KC.H], + [KC.MO(1), KC.I, KC.J], + ], + [ + [KC.TRNS, KC.K, KC.RESET], + [KC.L, KC.M, KC.N], + [KC.O, KC.P, KC.Q], + [KC.TRNS, KC.R, KC.S], + ], +] +``` + +# Handwire +When hand wiring custom keyboards, you will have to set the board up so KMK +knows where things are. This is the basic SETUP. + +```python +from kmk.consts import DiodeOrientation +from kmk.keycodes import KC +from kmk.pins import Pin as P +from kmk.entrypoints.circuitpython_samd51 import main +from kmk.firmware import Firmware + +cols = (P.D11, P.D10, P.D9) +rows = (P.A2, P.A3, P.A4, P.A5) + +diode_orientation = DiodeOrientation.COLUMNS +``` + +The main things that need set up are: +1. Your microcontroller will need to be set here. +```python +from kmk.entrypoints.circuitpython_samd51 import main +``` +2. Set your row and column pins up +```python +cols = (P.D11, P.D10, P.D9) +rows = (P.A2, P.A3, P.A4, P.A5) +``` +3. Set your diode orientation +```python +diode_orientation = DiodeOrientation.COLUMNS +``` diff --git a/docs/leader.md b/docs/leader.md new file mode 100644 index 0000000..afca076 --- /dev/null +++ b/docs/leader.md @@ -0,0 +1,46 @@ +# Leader Key +The leader key acts as a prefix to a key sequence. These can be used to trigger macros quickly +without dedicated keys set to each function. For those of you who dislike key combos, such as +Ctrl+Shift+Esc, then this feature is for you. This is very much inspired from vim. + +Leader key sequences can be as long or short as you like. The action must be a macro, so it +can be things like unicode macros, or generic macros. The example below shows how you would +trigger task manager in Windows with a leader sequence. By default Leader Mode is ENTER, which +means that after your sequence you will hit ENTER to trigger the sequence completion, or ESC to +cancel the sequence. + +1. Assign a key to KC.LEAD +2. Above your keymap, include a LEADER_DICTIONARY. + +```python +from kmk.macros.simple import simple_key_sequence + +LEADER_DICTIONARY = { + (KC.T, KC.A, KC.S, KC.K): simple_key_sequence(Modifiers.KC_LCTRL(Modifiers.KC_LSHIFT(Common.KC_ESC))) +} + +keymap = [...KC.LEAD,...] +``` +# Modes +Modes avaliable (WARNING: LeaderMode.ENTER is currently the only one avaliable.) +1. LeaderMode.DEFAULT +2. LeaderMode.ENTER + +### DEFAULT #WARNING# NOT AVALIBLE YET +Will expire after a timer and trigger the sequence that matches if any. +This can be enabled with +```python +from kmk.consts.LederMode +leader_mode = LeaderMode.DEFAULT +``` +The timeout can be set like this +```python +leader_timeout = 2000 +``` +### ENTER +Has no timeout. To end sequence press the enter key, or cancel and do nothing, press escape. +This can be enabled with + + from kmk.consts.LederMode + leader_mode = LeaderMode.ENTER + diff --git a/docs/unicode.md b/docs/unicode.md new file mode 100644 index 0000000..ff7e7bc --- /dev/null +++ b/docs/unicode.md @@ -0,0 +1,70 @@ +# Macros And Unicode +Macros are used for sending multiple keystrokes in a single action. This is useful for +things like unicode input, sending strings of text, or other automation. + +## Basic Macros +The most basic macro is send_string(). It can be used to send any standard ASCII keycode, including the return and tab key. +```python +from kmk.macros.simple import send_string + +WOW = send_string("Wow, KMK is awesome!") + +keymap = [...WOW,...] +``` +# Unicode +Before using unicode mode, you will need to set your platform. This can be done either of these ways. +You can use both in cases where you want to use one operating system, but occasionally use another. +This allows you to change modes on the fly without having to change your keymap. + + unicode_mode = UnicodeModes.LINUX + Or + keymap = [...KC.UC_MODE_LINUX,...] + + +### Unicode Modes: +On Linux IBUS is required, and on Windows, requires [WinCompose](https://github.com/samhocevar/wincompose) +- Linux : UnicodeModes.LINUX or UnicodeModes.IBUS +- Mac: UnicodeModes.MACOS or UnicodeModes.OSX or UnicodeModes.RALT +- Windows: UnicodeModes.WINC + +A note for IBUS users on Linux. This mode is not enabled by default, and will need to be turned on for this to work. +This works on X11, though if you are on Wayland, or in some GTK apps, it MAY work, but is not supported. + + export IBUS_ENABLE_CTRL_SHIFT_U=1 + +### Unicode Examples + +To send a simple unicode symbol +```python +FLIP = unicode_string_sequence('(ノಠ痊ಠ)ノ彡┻━┻') +keymap = [...FLIP,...] +``` + +And for many single character unicode: + +```python +from kmk.types import AttrDic + +emoticons = AttrDict({ + 'BEER': r'🍺', + 'HAND_WAVE': r'👋', +}) + +for k, v in emoticons.items(): +emoticons[k] = unicode_string_sequence(v) + +keymap = [...emoticons.BEER, emoticons.HAND_WAVE...] +``` + +If you need to send a unicode hex string, use unicode_codepoint_sequence() + +```python +from kmk.macros.unicode import unicode_codepoint_sequence + +TABLE_FLIP = unicode_codepoint_sequence([ + "28", "30ce", "ca0", "75ca","ca0", "29", + "30ce", "5f61", "253b", "2501", "253b", +]) + +keymap = [...TABLE_FLIP,...] +```