docs/feature_terminal.md

   1 # Terminal
   2
   3 > This feature is currently *huge* at 4400 bytes, and should probably only be put on boards with a lot of memory, or for fun.
   4
   5 The terminal feature is a command-line-like interface designed to communicate through a text editor with keystrokes. It's beneficial to turn off auto-indent features in your editor.
   6
   7 To enable, stick this in your `rules.mk` or `Makefile`:
   8
   9     TERMINAL_ENABLE = yes
  10
  11 And use the `TERM_ON` and `TERM_OFF` keycodes to turn it on or off.
  12
  13 When enabled, a `> ` prompt will appear, where you'll be able to type, backspace (a bell will ding if you reach the beginning and audio is enabled), and hit enter to send the command. Arrow keys are currently disabled so it doesn't get confused. Moving your cursor around with the mouse is discouraged.
  14
  15 `#define TERMINAL_HELP` enables some other output helpers that aren't really needed with this page.
  16
  17 Pressing "up" and "down" will allow you to cycle through the past 5 commands entered.
  18
  19 ## Future Ideas
  20
  21 * Keyboard/user-extensible commands
  22 * Smaller footprint
  23 * Arrow key support
  24 * Command history - Done
  25 * SD card support
  26 * LCD support for buffer display
  27 * Keycode -> name string LUT
  28 * Layer status
  29 * *Analog/digital port read/write*
  30 * RGB mode stuff
  31 * Macro definitions
  32 * EEPROM read/write
  33 * Audio control
  34
  35 ## Current Commands
  36
  37 ### `about`
  38
  39 Prints out the current version of QMK with a build date:
  40
  41 ```
  42 > about
  43 QMK Firmware
  44   v0.5.115-7-g80ed73-dirty
  45   Built: 2017-08-29-20:24:44
  46 ```
  47
  48
  49 ### `print-buffer`
  50
  51 Outputs the last 5 commands entered
  52
  53 ```
  54 > print-buffer
  55 0. print-buffer
  56 1. help
  57 2. about
  58 3. keymap 0
  59 4. help
  60 5. flush-buffer
  61 ```
  62
  63 ### `flush-buffer`
  64
  65 Clears command buffer
  66 ```
  67 > flush-buffer
  68 Buffer cleared!
  69 ```
  70
  71
  72 ### `help`
  73
  74
  75 Prints out the available commands:
  76
  77 ```
  78 > help
  79 commands available:
  80   about help keycode keymap exit print-buffer flush-buffer
  81 ```
  82
  83 ### `keycode <layer> <row> <col>`
  84
  85 Prints out the keycode value of a certain layer, row, and column:
  86
  87 ```
  88 > keycode 0 1 0
  89 0x29 (41)
  90 ```
  91
  92 ### `keymap <layer>`
  93
  94 Prints out the entire keymap for a certain layer
  95
  96 ```
  97 > keymap 0
  98 0x002b, 0x0014, 0x001a, 0x0008, 0x0015, 0x0017, 0x001c, 0x0018, 0x000c, 0x0012, 0x0013, 0x002a,
  99 0x0029, 0x0004, 0x0016, 0x0007, 0x0009, 0x000a, 0x000b, 0x000d, 0x000e, 0x000f, 0x0033, 0x0034,
 100 0x00e1, 0x001d, 0x001b, 0x0006, 0x0019, 0x0005, 0x0011, 0x0010, 0x0036, 0x0037, 0x0038, 0x0028,
 101 0x5cd6, 0x00e0, 0x00e2, 0x00e3, 0x5cd4, 0x002c, 0x002c, 0x5cd5, 0x0050, 0x0051, 0x0052, 0x004f,
 102 >
 103 ```
 104
 105 ### `exit`
 106
 107 Exits the terminal - same as `TERM_OFF`.