sporq/kmk_firmware
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Basic Docs

Browse Source 
Updated

Final cleanup
This commit is contained in:
Kyle Brown 2018-10-11 19:06:10 -07:00
parent 5313e5f5b5
commit 4c12e3a08d
7 changed files with 536 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
docs/debugging.md Normal file
View File

@ -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)

18
docs/flashing.md Normal file
View File

@ -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-<board> USER_KEYMAP=user_keymaps/...
Example:
make flash-feather-m4-express USER_KEYMAP=user_keymaps/kdb424/handwire_planck_featherm4.py

48
docs/hardware.md Normal file
View File

@ -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.

292
docs/keycodes.md Normal file
View File

@ -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 <code>&#124;</code> |
|`KC.NONUS_HASH` |`KC.NUHS` |Non-US `#` and `~` |
|`KC.SCOLON` |`KC.SCLN` |`;` and `:` |
|`KC.QUOTE` |`KC.QUOT` |`'` and `"` |
|`KC.GRAVE` |`KC.GRV`, `KC.ZKHK` |<code>&#96;</code> 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 <code>&#124;</code> |
|`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 <code>&#124;</code> |
|`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` | |<code>&#124;</code>|
|`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, <code>&#96;</code> 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 |

51
docs/keymap.md Normal file
View File

@ -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
```

46
docs/leader.md Normal file
View File

@ -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

70
docs/unicode.md Normal file
View File

@ -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,...]
```