diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_summary.md | 1 | ||||
| -rw-r--r-- | docs/config_options.md | 4 | ||||
| -rw-r--r-- | docs/eeprom_driver.md | 5 | ||||
| -rw-r--r-- | docs/feature_mouse_keys.md | 6 | ||||
| -rw-r--r-- | docs/feature_pointing_device.md | 44 | ||||
| -rw-r--r-- | docs/feature_rgb_matrix.md | 20 | ||||
| -rw-r--r-- | docs/feature_split_keyboard.md | 3 | ||||
| -rw-r--r-- | docs/feature_stenography.md | 123 | ||||
| -rw-r--r-- | docs/feature_tap_dance.md | 143 | ||||
| -rw-r--r-- | docs/feature_terminal.md | 107 | ||||
| -rw-r--r-- | docs/flashing.md | 4 | ||||
| -rw-r--r-- | docs/ja/_summary.md | 1 | ||||
| -rw-r--r-- | docs/ja/config_options.md | 2 | ||||
| -rw-r--r-- | docs/ja/feature_tap_dance.md | 1 | ||||
| -rw-r--r-- | docs/ja/feature_terminal.md | 112 | ||||
| -rw-r--r-- | docs/ja/understanding_qmk.md | 1 | ||||
| -rw-r--r-- | docs/platformdev_chibios_earlyinit.md | 2 | ||||
| -rw-r--r-- | docs/reference_info_json.md | 36 | ||||
| -rw-r--r-- | docs/serial_driver.md | 299 | ||||
| -rw-r--r-- | docs/understanding_qmk.md | 1 | ||||
| -rw-r--r-- | docs/zh-cn/_summary.md | 1 | ||||
| -rw-r--r-- | docs/zh-cn/custom_quantum_functions.md | 7 |
22 files changed, 514 insertions, 409 deletions
diff --git a/docs/_summary.md b/docs/_summary.md index 11f5e1dd51..78d7f30ea4 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -88,7 +88,6 @@ * [Swap Hands](feature_swap_hands.md) * [Tap Dance](feature_tap_dance.md) * [Tap-Hold Configuration](tap_hold.md) - * [Terminal](feature_terminal.md) * [Unicode](feature_unicode.md) * [Userspace](feature_userspace.md) * [WPM Calculation](feature_wpm.md) diff --git a/docs/config_options.md b/docs/config_options.md index 8227a0e074..c35227a407 100644 --- a/docs/config_options.md +++ b/docs/config_options.md @@ -141,7 +141,7 @@ If you define these options you will enable the associated feature, which may in ## Behaviors That Can Be Configured * `#define TAPPING_TERM 200` - * how long before a tap becomes a hold, if set above 500, a key tapped during the tapping term will turn it into a hold too + * how long before a key press becomes a hold * `#define TAPPING_TERM_PER_KEY` * enables handling for per key `TAPPING_TERM` settings * `#define RETRO_TAPPING` @@ -174,6 +174,8 @@ If you define these options you will enable the associated feature, which may in * sets the timer for leader key chords to run on each key press rather than overall * `#define LEADER_KEY_STRICT_KEY_PROCESSING` * Disables keycode filtering for Mod-Tap and Layer-Tap keycodes. Eg, if you enable this, you would need to specify `MT(MOD_CTL, KC_A)` if you want to use `KC_A`. +* `#define MOUSE_EXTENDED_REPORT` + * Enables support for extended reports (-32767 to 32767, instead of -127 to 127), which may allow for smoother reporting, and prevent maxing out of the reports. Applies to both Pointing Device and Mousekeys. * `#define ONESHOT_TIMEOUT 300` * how long before oneshot times out * `#define ONESHOT_TAP_TOGGLE 2` diff --git a/docs/eeprom_driver.md b/docs/eeprom_driver.md index 6dcf10c04d..306ebacb3f 100644 --- a/docs/eeprom_driver.md +++ b/docs/eeprom_driver.md @@ -43,8 +43,9 @@ Module | Equivalent `#define` | Source -----------------|---------------------------------|------------------------------------------ CAT24C512 EEPROM | `#define EEPROM_I2C_CAT24C512` | <https://www.sparkfun.com/products/14764> RM24C512C EEPROM | `#define EEPROM_I2C_RM24C512C` | <https://www.sparkfun.com/products/14764> -24LC64 EEPROM | `#define EEPROM_I2C_24LC64` | <https://www.microchip.com/wwwproducts/en/24LC64> -24LC128 EEPROM | `#define EEPROM_I2C_24LC128` | <https://www.microchip.com/wwwproducts/en/24LC128> +24LC32A EEPROM | `#define EEPROM_I2C_24LC32A` | <https://www.microchip.com/en-us/product/24LC32A> +24LC64 EEPROM | `#define EEPROM_I2C_24LC64` | <https://www.microchip.com/en-us/product/24LC64> +24LC128 EEPROM | `#define EEPROM_I2C_24LC128` | <https://www.microchip.com/en-us/product/24LC128> 24LC256 EEPROM | `#define EEPROM_I2C_24LC256` | <https://www.sparkfun.com/products/525> MB85RC256V FRAM | `#define EEPROM_I2C_MB85RC256V` | <https://www.adafruit.com/product/1895> diff --git a/docs/feature_mouse_keys.md b/docs/feature_mouse_keys.md index 905da36e43..8e474c4245 100644 --- a/docs/feature_mouse_keys.md +++ b/docs/feature_mouse_keys.md @@ -87,9 +87,9 @@ This is an extension of the accelerated mode. The kinetic mode uses a quadratic |`MK_KINETIC_SPEED` |undefined|Enable kinetic mode | |`MOUSEKEY_DELAY` |5 |Delay between pressing a movement key and cursor movement | |`MOUSEKEY_INTERVAL` |10 |Time between cursor movements in milliseconds | -|`MOUSEKEY_MOVE_DELTA` |5 |Step size for accelerating from initial to base speed | +|`MOUSEKEY_MOVE_DELTA` |16 |Step size for accelerating from initial to base speed | |`MOUSEKEY_INITIAL_SPEED` |100 |Initial speed of the cursor in pixel per second | -|`MOUSEKEY_BASE_SPEED` |1000 |Maximum cursor speed at which acceleration stops | +|`MOUSEKEY_BASE_SPEED` |5000 |Maximum cursor speed at which acceleration stops | |`MOUSEKEY_DECELERATED_SPEED` |400 |Decelerated cursor speed | |`MOUSEKEY_ACCELERATED_SPEED` |3000 |Accelerated cursor speed | |`MOUSEKEY_WHEEL_INITIAL_MOVEMENTS` |16 |Initial number of movements of the mouse wheel | @@ -100,7 +100,7 @@ This is an extension of the accelerated mode. The kinetic mode uses a quadratic Tips: * The smoothness of the cursor movement depends on the `MOUSEKEY_INTERVAL` setting. The shorter the interval is set the smoother the movement will be. Setting the value too low makes the cursor unresponsive. Lower settings are possible if the micro processor is fast enough. For example: At an interval of `8` milliseconds, `125` movements per second will be initiated. With a base speed of `1000` each movement will move the cursor by `8` pixels. -* Mouse wheel movements are implemented differently from cursor movements. While it's okay for the cursor to move multiple pixels at once for the mouse wheel this would lead to jerky movements. Instead, the mouse wheel operates at step size `1`. Setting mouse wheel speed is done by adjusting the number of wheel movements per second. +* Mouse wheel movements are implemented differently from cursor movements. While it's okay for the cursor to move multiple pixels at once for the mouse wheel this would lead to jerky movements. Instead, the mouse wheel operates at step size `2`. Setting mouse wheel speed is done by adjusting the number of wheel movements per second. ### Constant mode diff --git a/docs/feature_pointing_device.md b/docs/feature_pointing_device.md index 02c1e64a31..264362ea77 100644 --- a/docs/feature_pointing_device.md +++ b/docs/feature_pointing_device.md @@ -72,7 +72,6 @@ The Analog Joystick is an analog (ADC) driven sensor. There are a variety of jo |`ANALOG_JOYSTICK_SPEED_MAX` | (Optional) The maximum value used for motion. | `2` | |`ANALOG_JOYSTICK_CLICK_PIN` | (Optional) The pin wired up to the press switch of the analog stick. | _not defined_ | - ### Cirque Trackpad To use the Cirque Trackpad sensor, add this to your `rules.mk`: @@ -90,30 +89,42 @@ POINTING_DEVICE_DRIVER = cirque_pinnacle_spi This supports the Cirque Pinnacle 1CA027 Touch Controller, which is used in the TM040040, TM035035 and the TM023023 trackpads. These are I2C or SPI compatible, and both configurations are supported. -| Setting | Description | Default | -|---------------------------------|---------------------------------------------------------------------------------|-----------------------| -|`CIRQUE_PINNACLE_X_LOWER` | (Optional) The minimum reachable X value on the sensor. | `127` | -|`CIRQUE_PINNACLE_X_UPPER` | (Optional) The maximum reachable X value on the sensor. | `1919` | -|`CIRQUE_PINNACLE_Y_LOWER` | (Optional) The minimum reachable Y value on the sensor. | `63` | -|`CIRQUE_PINNACLE_Y_UPPER` | (Optional) The maximum reachable Y value on the sensor. | `1471` | -|`CIRQUE_PINNACLE_TAPPING_TERM` | (Optional) Length of time that a touch can be to be considered a tap. | `TAPPING_TERM`/`200` | -|`CIRQUE_PINNACLE_TOUCH_DEBOUNCE` | (Optional) Length of time that a touch can be to be considered a tap. | `TAPPING_TERM`/`200` | +| Setting | Description | Default | +|-------------------------------- |-----------------------------------------------------------------------|--------------------- | +|`CIRQUE_PINNACLE_X_LOWER` | (Optional) The minimum reachable X value on the sensor. | `127` | +|`CIRQUE_PINNACLE_X_UPPER` | (Optional) The maximum reachable X value on the sensor. | `1919` | +|`CIRQUE_PINNACLE_Y_LOWER` | (Optional) The minimum reachable Y value on the sensor. | `63` | +|`CIRQUE_PINNACLE_Y_UPPER` | (Optional) The maximum reachable Y value on the sensor. | `1471` | +|`CIRQUE_PINNACLE_ATTENUATION` | (Optional) Sets the attenuation of the sensor data. | `ADC_ATTENUATE_4X` | +|`CIRQUE_PINNACLE_TAPPING_TERM` | (Optional) Length of time that a touch can be to be considered a tap. | `TAPPING_TERM`/`200` | +|`CIRQUE_PINNACLE_TOUCH_DEBOUNCE` | (Optional) Length of time that a touch can be to be considered a tap. | `TAPPING_TERM`/`200` | + +**`CIRQUE_PINNACLE_ATTENUATION`** is a measure of how much data is suppressed in regards to sensitivity. The higher the attenuation, the less sensitive the touchpad will be. + +Default attenuation is set to 4X, although if you are using a thicker overlay (such as the curved overlay) you will want a lower attenuation such as 2X. The possible values are: +* `ADC_ATTENUATE_4X`: Least sensitive +* `ADC_ATTENUATE_3X` +* `ADC_ATTENUATE_2X` +* `ADC_ATTENUATE_1X`: Most sensitive | I2C Setting | Description | Default | |--------------------------|---------------------------------------------------------------------------------|---------| |`CIRQUE_PINNACLE_ADDR` | (Required) Sets the I2C Address for the Cirque Trackpad | `0x2A` | |`CIRQUE_PINNACLE_TIMEOUT` | (Optional) The timeout for i2c communication with the trackpad in milliseconds. | `20` | -| SPI Setting | Description | Default | -|-------------------------------|------------------------------------------------------------------------|---------------| -|`CIRQUE_PINNACLE_CLOCK_SPEED` | (Optional) Sets the clock speed that the sensor runs at. | `1000000` | -|`CIRQUE_PINNACLE_SPI_LSBFIRST` | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false` | -|`CIRQUE_PINNACLE_SPI_MODE` | (Optional) Sets the SPI Mode for the sensor. | `1` | -|`CIRQUE_PINNACLE_SPI_DIVISOR` | (Optional) Sets the SPI Divisor used for SPI communication. | _varies_ | -|`CIRQUE_PINNACLE_SPI_CS_PIN` | (Required) Sets the Cable Select pin connected to the sensor. | _not defined_ | +| SPI Setting | Description | Default | +|-------------------------------|------------------------------------------------------------------------|----------------| +|`CIRQUE_PINNACLE_CLOCK_SPEED` | (Optional) Sets the clock speed that the sensor runs at. | `1000000` | +|`CIRQUE_PINNACLE_SPI_LSBFIRST` | (Optional) Sets the Least/Most Significant Byte First setting for SPI. | `false` | +|`CIRQUE_PINNACLE_SPI_MODE` | (Optional) Sets the SPI Mode for the sensor. | `1` | +|`CIRQUE_PINNACLE_SPI_DIVISOR` | (Optional) Sets the SPI Divisor used for SPI communication. | _varies_ | +|`CIRQUE_PINNACLE_SPI_CS_PIN` | (Required) Sets the Cable Select pin connected to the sensor. | _not defined_ | Default Scaling/CPI is 1024. +Also see the `POINTING_DEVICE_TASK_THROTTLE_MS`, which defaults to 10ms when using Cirque Pinnacle, which matches the internal update rate of the position registers (in standard configuration). Advanced configuration for pen/stylus usage might require lower values. + + ### Pimoroni Trackball To use the Pimoroni Trackball module, add this to your `rules.mk`: @@ -259,6 +270,7 @@ The following configuration options are only available when using `SPLIT_POINTIN |`POINTING_DEVICE_ROTATION_270_RIGHT` | (Optional) Rotates the X and Y data by 270 degrees. | _not defined_ | |`POINTING_DEVICE_INVERT_X_RIGHT` | (Optional) Inverts the X axis report. | _not defined_ | |`POINTING_DEVICE_INVERT_Y_RIGHT` | (Optional) Inverts the Y axis report. | _not defined_ | +|`MOUSE_EXTENDED_REPORT` | (Optional) Enables support for extended mouse reports. (-32767 to 32767, instead of just -127 to 127) | !> If there is a `_RIGHT` configuration option or callback, the [common configuration](feature_pointing_device.md?id=common-configuration) option will work for the left. For correct left/right detection you should setup a [handedness option](feature_split_keyboard?id=setting-handedness), `EE_HANDS` is usually a good option for an existing board that doesn't do handedness by hardware. diff --git a/docs/feature_rgb_matrix.md b/docs/feature_rgb_matrix.md index 295e610fc4..247b77bcb1 100644 --- a/docs/feature_rgb_matrix.md +++ b/docs/feature_rgb_matrix.md @@ -86,6 +86,7 @@ You can use between 1 and 4 IS31FL3733 IC's. Do not specify `DRIVER_ADDR_<N>` de | `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | | `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | | `ISSI_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3733B only | 0 | +| `ISSI_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | | `ISSI_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | | `ISSI_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | | `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | @@ -172,6 +173,7 @@ Configure the hardware via your `config.h`: | `ISSI_TIMEOUT` | (Optional) How long to wait for i2c messages, in milliseconds | 100 | | `ISSI_PERSISTENCE` | (Optional) Retry failed messages this many times | 0 | | `ISSI_PWM_FREQUENCY` | (Optional) PWM Frequency Setting - IS31FL3737B only | 0 | +| `ISSI_GLOBALCURRENT` | (Optional) Configuration for the Global Current Register | 0xFF | | `ISSI_SWPULLUP` | (Optional) Set the value of the SWx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | | `ISSI_CSPULLUP` | (Optional) Set the value of the CSx lines on-chip de-ghosting resistors | PUR_0R (Disabled) | | `DRIVER_COUNT` | (Required) How many RGB driver IC's are present | | @@ -409,6 +411,7 @@ You can use up to 2 AW20216 IC's. Do not specify `DRIVER_<N>_xxx` defines for IC | `DRIVER_LED_TOTAL` | (Required) How many RGB lights are present across all drivers | | | `AW_SCALING_MAX` | (Optional) LED current scaling value (0-255, higher values mean LED is brighter at full PWM) | 150 | | `AW_GLOBAL_CURRENT_MAX` | (Optional) Driver global current limit (0-255, higher values means the driver may consume more power) | 150 | +| `AW_SPI_MODE` | (Optional) Mode for SPI communication (0-3, defines polarity and phase of the clock) | 3 | | `AW_SPI_DIVISOR` | (Optional) Clock divisor for SPI communication (powers of 2, smaller numbers means faster communication, should not be less than 4) | 4 | Here is an example using 2 drivers. @@ -665,7 +668,22 @@ In order to change the delay of temperature decrease define `RGB_MATRIX_TYPING_H #define RGB_MATRIX_TYPING_HEATMAP_DECREASE_DELAY_MS 50 ``` -Heatmap effect may not light up the correct adjacent LEDs for certain key matrix layout such as split keyboards. The following define will limit the effect to pressed keys only: +As heatmap uses the physical position of the leds set in the g_led_config, you may need to tweak the following options to get the best effect for your keyboard. Note the size of this grid is `224x64`. + +Limit the distance the effect spreads to surrounding keys. + +```c +#define RGB_MATRIX_TYPING_HEATMAP_SPREAD 40 +``` + +Limit how hot surrounding keys get from each press. + +```c +#define RGB_MATRIX_TYPING_HEATMAP_AREA_LIMIT 16 +``` + +Remove the spread effect entirely. + ```c #define RGB_MATRIX_TYPING_HEATMAP_SLIM ``` diff --git a/docs/feature_split_keyboard.md b/docs/feature_split_keyboard.md index eefafdbf75..4cd0768377 100644 --- a/docs/feature_split_keyboard.md +++ b/docs/feature_split_keyboard.md @@ -143,6 +143,9 @@ Next, you will have to flash the EEPROM files once for the correct hand to the c * ARM controllers with a DFU compatible bootloader (e.g. Proton-C): * `:dfu-util-split-left` * `:dfu-util-split-right` +* ARM controllers with a UF2 compatible bootloader: + * `:uf2-split-left` + * `:uf2-split-right` Example: diff --git a/docs/feature_stenography.md b/docs/feature_stenography.md index 2b52bb17a6..e13fe845c5 100644 --- a/docs/feature_stenography.md +++ b/docs/feature_stenography.md @@ -8,46 +8,107 @@ The [Open Steno Project](https://www.openstenoproject.org/) has built an open-so Plover can work with any standard QWERTY keyboard, although it is more efficient if the keyboard supports NKRO (n-key rollover) to allow Plover to see all the pressed keys at once. An example keymap for Plover can be found in `planck/keymaps/default`. Switching to the `PLOVER` layer adjusts the position of the keyboard to support the number bar. -To use Plover with QMK just enable NKRO and optionally adjust your layout if you have anything other than a standard layout. You may also want to purchase some steno-friendly keycaps to make it easier to hit multiple keys. +To enable NKRO, add `NKRO_ENABLE = yes` in your `rules.mk` and make sure to press `NK_ON` to turn it on because `NKRO_ENABLE = yes` merely adds the possibility of switching to NKRO mode but it doesn't automatically switch to it. If you want to automatically switch, add `#define FORCE_NKRO` in your `config.h`. + +You may also need to adjust your layout, either in QMK or in Plover, if you have anything other than a standard layout. You may also want to purchase some steno-friendly keycaps to make it easier to hit multiple keys. ## Plover with Steno Protocol :id=plover-with-steno-protocol -Plover also understands the language of several steno machines. QMK can speak a couple of these languages, TX Bolt and GeminiPR. An example layout can be found in `planck/keymaps/steno`. +Plover also understands the language of several steno machines. QMK can speak a couple of these languages: TX Bolt and GeminiPR. An example layout can be found in `planck/keymaps/steno`. + +When QMK speaks to Plover over a steno protocol, Plover will not use the keyboard as input. This means that you can switch back and forth between a standard keyboard and your steno keyboard, or even switch layers from Plover to standard and back without needing to activate/deactivate Plover. + +In this mode, Plover expects to speak with a steno machine over a serial port so QMK will present itself to the operating system as a virtual serial port in addition to a keyboard. -When QMK speaks to Plover over a steno protocol Plover will not use the keyboard as input. This means that you can switch back and forth between a standard keyboard and your steno keyboard, or even switch layers from Plover to standard and back without needing to activate/deactivate Plover. +> Note: Due to hardware limitations, you might not be able to run both a virtual serial port and mouse emulation at the same time. -In this mode Plover expects to speak with a steno machine over a serial port so QMK will present itself to the operating system as a virtual serial port in addition to a keyboard. By default QMK will speak the TX Bolt protocol but can be switched to GeminiPR; the last protocol used is stored in non-volatile memory so QMK will use the same protocol on restart. +!> Serial stenography protocols are not supported on [V-USB keyboards](compatible_microcontrollers#atmel-avr). -> Note: Due to hardware limitations you may not be able to run both a virtual serial port and mouse emulation at the same time. +To enable stenography protocols, add the following lines to your `rules.mk`: +```mk +STENO_ENABLE = yes +``` ### TX Bolt :id=tx-bolt -TX Bolt communicates the status of 24 keys over a very simple protocol in variable-sized (1-5 byte) packets. +TX Bolt communicates the status of 24 keys over a simple protocol in variable-sized (1–4 bytes) packets. -### GeminiPR :id=geminipr +To select TX Bolt, add the following lines to your `rules.mk`: +```mk +STENO_ENABLE = yes +STENO_PROTOCOL = txbolt +``` -GeminiPR encodes 42 keys into a 6-byte packet. While TX Bolt contains everything that is necessary for standard stenography, GeminiPR opens up many more options, including supporting non-English theories. +Each byte of the packet represents a different group of steno keys. Determining the group of a certain byte of the packet is done by checking the first two bits, the remaining bits are set if the corresponding steno key was pressed for the stroke. The last set of keys (as indicated by leading `11`) needs to keep track of less keys than there are bits so one of the bits is constantly 0. -## Configuring QMK for Steno :id=configuring-qmk-for-steno +The start of a new packet can be detected by comparing the group “ID” (the two MSBs) of the current byte to that of the previously received byte. If the group “ID” of the current byte is smaller or equal to that of the previous byte, it means that the current byte is the beginning of a new packet. -Firstly, enable steno in your keymap's Makefile. You may also need disable mousekeys, extra keys, or another USB endpoint to prevent conflicts. The builtin USB stack for some processors only supports a certain number of USB endpoints and the virtual serial port needed for steno fills 3 of them. +The format of TX Bolt packets is shown below. +``` +00HWPKTS 01UE*OAR 10GLBPRF 110#ZDST +``` + +Examples of steno strokes and the associated packet: +- `EUBG` = `01110000 10101000` +- `WAZ` = `00010000 01000010 11001000` +- `PHAPBGS` = `00101000 01000010 10101100 11000010` + +### GeminiPR :id=geminipr + +GeminiPR encodes 42 keys into a 6-byte packet. While TX Bolt contains everything that is necessary for standard stenography, GeminiPR opens up many more options, including differentiating between top and bottom `S-`, and supporting non-English theories. -```make +To select GeminiPR, add the following lines to your `rules.mk`: +```mk STENO_ENABLE = yes -MOUSEKEY_ENABLE = no +STENO_PROTOCOL = geminipr ``` -In your keymap create a new layer for Plover. You will need to include `keymap_steno.h`. See `planck/keymaps/steno/keymap.c` for an example. Remember to create a key to switch to the layer as well as a key for exiting the layer. If you would like to switch modes on the fly you can use the keycodes `QK_STENO_BOLT` and `QK_STENO_GEMINI`. If you only want to use one of the protocols you may set it up in your initialization function: +All packets in the GeminiPR protocol consist of exactly six bytes, used as bit-arrays for different groups of keys. The beginning of a packet is indicated by setting the most significant bit (MSB) to 1 while setting the MSB of the remaining five bytes to 0. -```c -void eeconfig_init_user() { - steno_set_mode(STENO_MODE_GEMINI); // or STENO_MODE_BOLT -} +The format of GeminiPR packets is shown below. +``` +1 Fn #1 #2 #3 #4 #5 #6 +0 S1- S2- T- K- P- W- H- +0 R- A- O- *1 *2 res1 res2 +0 pwr *3 *4 -E -U -F -R +0 -P -B -L -G -T -S -D +0 #7 #8 #9 #A #B #C -Z ``` -Once you have your keyboard flashed launch Plover. Click the 'Configure...' button. In the 'Machine' tab select the Stenotype Machine that corresponds to your desired protocol. Click the 'Configure...' button on this tab and enter the serial port or click 'Scan'. Baud rate is fine at 9600 (although you should be able to set as high as 115200 with no issues). Use the default settings for everything else (Data Bits: 8, Stop Bits: 1, Parity: N, no flow control). +Examples of steno strokes and the associated packet: +- `EUBG` = `10000000 00000000 00000000 00001100 00101000 00000000` +- `WAZ` = `10000000 00000010 00100000 00000000 00000000 00000001` +- `PHAPBGS` = `10000000 00000101 00100000 00000000 01101010 00000000` -On the display tab click 'Open stroke display'. With Plover disabled you should be able to hit keys on your keyboard and see them show up in the stroke display window. Use this to make sure you have set up your keymap correctly. You are now ready to steno! +### Switching protocols on the fly :id=switching-protocols-on-the-fly + +If you wish to switch the serial protocol used to transfer the steno chords without having to recompile your keyboard firmware every time, you can press the `QK_STENO_BOLT` and `QK_STENO_GEMINI` keycodes in order to switch protocols on the fly. + +To enable these special keycodes, add the following lines to your `rules.mk`: +```mk +STENO_ENABLE = yes +STENO_PROTOCOL = all +``` + +If you want to switch protocols programatically, as part of a custom macro for example, don't use `tap_code(QK_STENO_*)`, as `tap_code` only supports [basic keycodes](keycodes_basic). Instead, you should use `steno_set_mode(STENO_MODE_*)`, whose valid arguments are `STENO_MODE_BOLT` and `STENO_MODE_GEMINI`. + +The default protocol is Gemini PR but the last protocol used is stored in non-volatile memory so QMK will remember your choice between reboots of your keyboard — assuming that your keyboard features (emulated) EEPROM. + +Naturally, this option takes the most amount of firmware space as it needs to compile the code for all the available stenography protocols. In most cases, compiling a single stenography protocol is sufficient. + +The default value for `STENO_PROTOCOL` is `all`. + +## Configuring QMK for Steno :id=configuring-qmk-for-steno + +After enabling stenography and optionally selecting a protocol, you may also need disable mouse keys, extra keys, or another USB endpoint to prevent conflicts. The builtin USB stack for some processors only supports a certain number of USB endpoints and the virtual serial port needed for steno fills 3 of them. + +!> If you had *explicitly* set `VIRSTER_ENABLE = no`, none of the serial stenography protocols (GeminiPR, TX Bolt) will work properly. You are expected to either set it to `yes`, remove the line from your `rules.mk` or send the steno chords yourself in an alternative way using the [provided interceptable hooks](#interfacing-with-the-code). + +In your keymap, create a new layer for Plover, that you can fill in with the [steno keycodes](#keycode-reference) (you will need to include `keymap_steno.h`, see `planck/keymaps/steno/keymap.c` for an example). Remember to create a key to switch to the layer as well as a key for exiting the layer. + +Once you have your keyboard flashed, launch Plover. Click the 'Configure...' button. In the 'Machine' tab, select the Stenotype Machine that corresponds to your desired protocol. Click the 'Configure...' button on this tab and enter the serial port or click 'Scan'. Baud rate is fine at 9600 (although you should be able to set as high as 115200 with no issues). Use the default settings for everything else (Data Bits: 8, Stop Bits: 1, Parity: N, no flow control). + +To test your keymap, you can chord keys on your keyboard and either look at the output of the 'paper tape' (Tools > Paper Tape) or that of the 'layout display' (Tools > Layout Display). If your strokes correctly show up, you are now ready to steno! ## Learning Stenography :id=learning-stenography @@ -60,7 +121,7 @@ On the display tab click 'Open stroke display'. With Plover disabled you should The steno code has three interceptable hooks. If you define these functions, they will be called at certain points in processing; if they return true, processing continues, otherwise it's assumed you handled things. ```c -bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[6]); +bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[MAX_STROKE_SIZE]); ``` This function is called when a chord is about to be sent. Mode will be one of `STENO_MODE_BOLT` or `STENO_MODE_GEMINI`. This represents the actual chord that would be sent via whichever protocol. You can modify the chord provided to alter what gets sent. Remember to return true if you want the regular sending process to happen. @@ -72,15 +133,23 @@ bool process_steno_user(uint16_t keycode, keyrecord_t *record) { return true; } This function is called when a keypress has come in, before it is processed. The keycode should be one of `QK_STENO_BOLT`, `QK_STENO_GEMINI`, or one of the `STN_*` key values. ```c -bool postprocess_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[6], int8_t pressed); +bool postprocess_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[MAX_STROKE_SIZE], int8_t n_pressed_keys); ``` -This function is called after a key has been processed, but before any decision about whether or not to send a chord. If `IS_PRESSED(record->event)` is false, and `pressed` is 0 or 1, the chord will be sent shortly, but has not yet been sent. This is where to put hooks for things like, say, live displays of steno chords or keys. +This function is called after a key has been processed, but before any decision about whether or not to send a chord. This is where to put hooks for things like, say, live displays of steno chords or keys. + +If `IS_PRESSED(record->event)` is false, and `n_pressed_keys` is 0 or 1, the chord will be sent shortly, but has not yet been sent. This relieves you of the need of keeping track of where a packet ends and another begins. + +The `chord` argument contains the packet of the current chord as specified by the protocol in use. This is *NOT* simply a list of chorded steno keys of the form `[STN_E, STN_U, STN_BR, STN_GR]`. Refer to the appropriate protocol section of this document to learn more about the format of the packets in your steno protocol/mode of choice. +The `n_pressed_keys` argument is the number of physical keys actually being held down. +This is not always equal to the number of bits set to 1 (aka the [Hamming weight](https://en.wikipedia.org/wiki/Hamming_weight)) in `chord` because it is possible to simultaneously press down four keys, then release three of those four keys and then press yet another key while the fourth finger is still holding down its key. +At the end of this scenario given as an example, `chord` would have five bits set to 1 but +`n_pressed_keys` would be set to 2 because there are only two keys currently being pressed down. ## Keycode Reference :id=keycode-reference -As defined in `keymap_steno.h`. +You must include `keymap_steno.h` to your `keymap.c` with `#include "keymap_steno.h"` before you can use these keycodes > Note: TX Bolt does not support the full set of keys. The TX Bolt implementation in QMK will map the GeminiPR keys to the nearest TX Bolt key so that one key map will work for both. @@ -124,10 +193,10 @@ As defined in `keymap_steno.h`. |`STN_SR`|`STN_SR`| `-S`| |`STN_DR`|`STN_DR`| `-D`| |`STN_ZR`|`STN_ZR`| `-Z`| -|`STN_FN`|| (GeminiPR only)| -|`STN_RES1`||(GeminiPR only)| -|`STN_RES2`||(GeminiPR only)| -|`STN_PWR`||(GeminiPR only)| +|`STN_FN`|| (Function)| +|`STN_RES1`||(Reset 1)| +|`STN_RES2`||(Reset 2)| +|`STN_PWR`||(Power)| If you do not want to hit two keys with one finger combined keycodes can be used. These are also defined in `keymap_steno.h`, and causes both keys to be reported as pressed or released. To use these keycodes define `STENO_COMBINEDMAP` in your `config.h` file. diff --git a/docs/feature_tap_dance.md b/docs/feature_tap_dance.md index c055a9989a..05134ec229 100644 --- a/docs/feature_tap_dance.md +++ b/docs/feature_tap_dance.md @@ -14,55 +14,48 @@ Optionally, you might want to set a custom `TAPPING_TERM` time by adding somethi ```c #define TAPPING_TERM 175 +#define TAPPING_TERM_PER_KEY ``` -The `TAPPING_TERM` time is the maximum time allowed between taps of your Tap Dance key, and is measured in milliseconds. For example, if you used the above `#define` statement and set up a Tap Dance key that sends `Space` on single-tap and `Enter` on double-tap, then this key will send `ENT` only if you tap this key twice in less than 175ms. If you tap the key, wait more than 175ms, and tap the key again you'll end up sending `SPC SPC` instead. +The `TAPPING_TERM` time is the maximum time allowed between taps of your Tap Dance key, and is measured in milliseconds. For example, if you used the above `#define` statement and set up a Tap Dance key that sends `Space` on single-tap and `Enter` on double-tap, then this key will send `ENT` only if you tap this key twice in less than 175ms. If you tap the key, wait more than 175ms, and tap the key again you'll end up sending `SPC SPC` instead. The `TAPPING_TERM_PER_KEY` definition is only needed if you control the tapping term through a [custom `get_tapping_term` function](tap_hold.md#tapping_term), which may be needed because `TAPPING_TERM` affects not just tap-dance keys. -Next, you will want to define some tap-dance keys, which is easiest to do with the `TD()` macro, that takes a number which will later be used as an index into the `tap_dance_actions` array. +Next, you will want to define some tap-dance keys, which is easiest to do with the `TD()` macro. That macro takes a number which will later be used as an index into the `tap_dance_actions` array and turns it into a tap-dance keycode. After this, you'll want to use the `tap_dance_actions` array to specify what actions shall be taken when a tap-dance key is in action. Currently, there are five possible options: * `ACTION_TAP_DANCE_DOUBLE(kc1, kc2)`: Sends the `kc1` keycode when tapped once, `kc2` otherwise. When the key is held, the appropriate keycode is registered: `kc1` when pressed and held, `kc2` when tapped once, then pressed and held. * `ACTION_TAP_DANCE_LAYER_MOVE(kc, layer)`: Sends the `kc` keycode when tapped once, or moves to `layer`. (this functions like the `TO` layer keycode). - * This is the same as `ACTION_TAP_DANCE_DUAL_ROLE`, but renamed to something that is clearer about its functionality. Both names will work. * `ACTION_TAP_DANCE_LAYER_TOGGLE(kc, layer)`: Sends the `kc` keycode when tapped once, or toggles the state of `layer`. (this functions like the `TG` layer keycode). * `ACTION_TAP_DANCE_FN(fn)`: Calls the specified function - defined in the user keymap - with the final tap count of the tap dance action. * `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: Calls the first specified function - defined in the user keymap - on every tap, the second function when the dance action finishes (like the previous option), and the last function when the tap dance action resets. -* ~~`ACTION_TAP_DANCE_FN_ADVANCED_TIME(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn, tap_specific_tapping_term)`~~: This functions identically to the `ACTION_TAP_DANCE_FN_ADVANCED` function, but uses a custom tapping term for it, instead of the predefined `TAPPING_TERM`. - * This is deprecated in favor of the Per Key Tapping Term functionality, as outlined [here](tap_hold.md#tapping-term). You'd want to check for the specific `TD()` macro that you want to use (such as `TD(TD_ESC_CAPS)`) instead of using this specific Tap Dance function. The first option is enough for a lot of cases, that just want dual roles. For example, `ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT)` will result in `Space` being sent on single-tap, `Enter` otherwise. !> Keep in mind that only [basic keycodes](keycodes_basic.md) are supported here. Custom keycodes are not supported. -Similar to the first option, the second option is good for simple layer-switching cases. +Similar to the first option, the second and third option are good for simple layer-switching cases. -For more complicated cases, use the third or fourth options (examples of each are listed below). - -Finally, the fifth option is particularly useful if your non-Tap-Dance keys start behaving weirdly after adding the code for your Tap Dance keys. The likely problem is that you changed the `TAPPING_TERM` time to make your Tap Dance keys easier for you to use, and that this has changed the way your other keys handle interrupts. +For more complicated cases, like blink the LEDs, fiddle with the backlighting, and so on, use the fourth or fifth option. Examples of each are listed below. ## Implementation Details :id=implementation Well, that's the bulk of it! You should now be able to work through the examples below, and to develop your own Tap Dance functionality. But if you want a deeper understanding of what's going on behind the scenes, then read on for the explanation of how it all works! -The main entry point is `process_tap_dance()`, called from `process_record_quantum()`, which is run for every keypress, and our handler gets to run early. This function checks whether the key pressed is a tap-dance key. If it is not, and a tap-dance was in action, we handle that first, and enqueue the newly pressed key. If it is a tap-dance key, then we check if it is the same as the already active one (if there's one active, that is). If it is not, we fire off the old one first, then register the new one. If it was the same, we increment the counter and reset the timer. - -This means that you have `TAPPING_TERM` time to tap the key again; you do not have to input all the taps within a single `TAPPING_TERM` timeframe. This allows for longer tap counts, with minimal impact on responsiveness. +Let's go over the three functions mentioned in `ACTION_TAP_DANCE_FN_ADVANCED` in a little more detail. They all receive the same too arguments: a pointer to a structure that holds all dance related state information, and a pointer to a use case specific state variable. The three functions differ in when they are called. The first, `on_each_tap_fn()`, is called every time the tap dance key is *pressed*. Before it is called, the counter is incremented and the timer is reset. The second function, `on_dance_finished_fn()`, is called when the tap dance is interrupted or ends because `TAPPING_TERM` milliseconds have passed since the last tap. When the `finished` field of the dance state structure is set to `true`, the `on_dance_finished_fn()` is skipped. After `on_dance_finished_fn()` was called or would have been called, but no sooner than when the tap dance key is *released*, `on_dance_reset_fn()` is called. It is possible to end a tap dance immediately, skipping `on_dance_finished_fn()`, but not `on_dance_reset_fn`, by calling `reset_tap_dance(state)`. -Our next stop is `tap_dance_task()`. This handles the timeout of tap-dance keys. +To accomplish this logic, the tap dance mechanics use three entry points. The main entry point is `process_tap_dance()`, called from `process_record_quantum()` *after* `process_record_kb()` and `process_record_user()`. This function is responsible for calling `on_each_tap_fn()` and `on_dance_reset_fn()`. In order to handle interruptions of a tap dance, another entry point, `preprocess_tap_dance()` is run right at the beginning of `process_record_quantum()`. This function checks whether the key pressed is a tap-dance key. If it is not, and a tap-dance was in action, we handle that first, and enqueue the newly pressed key. If it is a tap-dance key, then we check if it is the same as the already active one (if there's one active, that is). If it is not, we fire off the old one first, then register the new one. Finally, `tap_dance_task()` periodically checks whether `TAPPING_TERM` has passed since the last key press and finishes a tap dance if that is the case. -For the sake of flexibility, tap-dance actions can be either a pair of keycodes, or a user function. The latter allows one to handle higher tap counts, or do extra things, like blink the LEDs, fiddle with the backlighting, and so on. This is accomplished by using an union, and some clever macros. +This means that you have `TAPPING_TERM` time to tap the key again; you do not have to input all the taps within a single `TAPPING_TERM` timeframe. This allows for longer tap counts, with minimal impact on responsiveness. ## Examples :id=examples -### Simple Example :id=simple-example +### Simple Example: Send `ESC` on Single Tap, `CAPS_LOCK` on Double Tap :id=simple-example Here's a simple example for a single definition: 1. In your `rules.mk`, add `TAP_DANCE_ENABLE = yes` -2. In your `config.h` (which you can copy from `qmk_firmware/keyboards/planck/config.h` to your keymap directory), add `#define TAPPING_TERM 200` -3. In your `keymap.c` file, define the variables and definitions, then add to your keymap: +2. In your `keymap.c` file, define the variables and definitions, then add to your keymap: ```c // Tap Dance declarations @@ -92,40 +85,15 @@ All the enums used in the examples are declared like this: ```c // Enums defined for all examples: enum { - CT_SE, - CT_CLN, + TD_ESC_CAPS, CT_EGG, CT_FLSH, - X_TAP_DANCE -}; -``` - -#### Example 1: Send `:` on Single Tap, `;` on Double Tap :id=example-1 - -```c -void dance_cln_finished(qk_tap_dance_state_t *state, void *user_data) { - if (state->count == 1) { - register_code16(KC_COLN); - } else { - register_code(KC_SCLN); - } -} - -void dance_cln_reset(qk_tap_dance_state_t *state, void *user_data) { - if (state->count == 1) { - unregister_code16(KC_COLN); - } else { - unregister_code(KC_SCLN); - } -} - -// All tap dance functions would go here. Only showing this one. -qk_tap_dance_action_t tap_dance_actions[] = { - [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset), + CT_CLN, + X_CTL, }; ``` -#### Example 2: Send "Safety Dance!" After 100 Taps :id=example-2 +#### Example 1: Send "Safety Dance!" After 100 Taps :id=example-1 ```c void dance_egg(qk_tap_dance_state_t *state, void *user_data) { @@ -140,7 +108,7 @@ qk_tap_dance_action_t tap_dance_actions[] = { }; ``` -#### Example 3: Turn LED Lights On Then Off, One at a Time :id=example-3 +#### Example 2: Turn LED Lights On Then Off, One at a Time :id=example-2 ```c // On each tap, light up one LED, from right to left @@ -181,15 +149,74 @@ void dance_flsh_reset(qk_tap_dance_state_t *state, void *user_data) { ergodox_right_led_3_off(); } -// All tap dances now put together. Example 3 is "CT_FLASH" +// All tap dances now put together. Example 2 is "CT_FLSH" qk_tap_dance_action_t tap_dance_actions[] = { - [CT_SE] = ACTION_TAP_DANCE_DOUBLE(KC_SPC, KC_ENT), - [CT_CLN] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, dance_cln_finished, dance_cln_reset), + [TD_ESC_CAPS] = ACTION_TAP_DANCE_DOUBLE(KC_ESC, KC_CAPS), [CT_EGG] = ACTION_TAP_DANCE_FN(dance_egg), [CT_FLSH] = ACTION_TAP_DANCE_FN_ADVANCED(dance_flsh_each, dance_flsh_finished, dance_flsh_reset) }; ``` +#### Example 3: Send `:` on Tap, `;` on Hold :id=example-3 + +With a little effort, powerful tap-hold configurations can be implemented as tap dances. To emit taps as early as possible, we need to act on releases of the tap dance key. There is no callback for this in the tap dance framework, so we use `process_record_user()`. + +```c +typedef struct { + uint16_t tap; + uint16_t hold; + uint16_t held; +} tap_dance_tap_hold_t; + +bool process_record_user(uint16_t keycode, keyrecord_t *record) { + qk_tap_dance_action_t *action; + + switch (keycode) { + case TD(CT_CLN): // list all tap dance keycodes with tap-hold configurations + action = &tap_dance_actions[TD_INDEX(keycode)]; + if (!record->event.pressed && action->state.count && !action->state.finished) { + tap_dance_tap_hold_t *tap_hold = (tap_dance_tap_hold_t *)action->user_data; + tap_code16(tap_hold->tap); + } + } + return true; +} + +void tap_dance_tap_hold_finished(qk_tap_dance_state_t *state, void *user_data) { + tap_dance_tap_hold_t *tap_hold = (tap_dance_tap_hold_t *)user_data; + + if (state->pressed) { + if (state->count == 1 +#ifndef PERMISSIVE_HOLD + && !state->interrupted +#endif + ) { + register_code16(tap_hold->hold); + tap_hold->held = tap_hold->hold; + } else { + register_code16(tap_hold->tap); + tap_hold->held = tap_hold->tap; + } + } +} + +void tap_dance_tap_hold_reset(qk_tap_dance_state_t *state, void *user_data) { + tap_dance_tap_hold_t *tap_hold = (tap_dance_tap_hold_t *)user_data; + + if (tap_hold->held) { + unregister_code16(tap_hold->held); + tap_hold->held = 0; + } +} + +#define ACTION_TAP_DANCE_TAP_HOLD(tap, hold) \ + { .fn = {NULL, tap_dance_tap_hold_finished, tap_dance_tap_hold_reset}, .user_data = (void *)&((tap_dance_tap_hold_t){tap, hold, 0}), } + +qk_tap_dance_action_t tap_dance_actions[] = { + [CT_CLN] = ACTION_TAP_DANCE_TAP_HOLD(KC_COLN, KC_SCLN), +}; +``` + #### Example 4: 'Quad Function Tap-Dance' :id=example-4 By [DanielGGordon](https://github.com/danielggordon) @@ -329,7 +356,7 @@ And then simply use `TD(X_CTL)` anywhere in your keymap. If you want to implement this in your userspace, then you may want to check out how [DanielGGordon](https://github.com/qmk/qmk_firmware/tree/master/users/gordon) has implemented this in their userspace. -> In this configuration "hold" takes place **after** tap dance timeout (see `ACTION_TAP_DANCE_FN_ADVANCED_TIME`). To achieve instant hold, remove `state->interrupted` checks in conditions. As a result you may use comfortable longer tapping periods to have more time for taps and not to wait too long for holds (try starting with doubled `TAPPING_TERM`). +> In this configuration "hold" takes place **after** tap dance timeout. To achieve instant hold, remove `state->interrupted` checks in conditions. As a result you may use comfortable longer tapping periods to have more time for taps and not to wait too long for holds (try starting with doubled `TAPPING_TERM`). #### Example 5: Using tap dance for advanced mod-tap and layer-tap keys :id=example-5 @@ -511,8 +538,18 @@ void ql_reset(qk_tap_dance_state_t *state, void *user_data) { // Associate our tap dance key with its functionality qk_tap_dance_action_t tap_dance_actions[] = { - [QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED_TIME(NULL, ql_finished, ql_reset, 275) + [QUOT_LAYR] = ACTION_TAP_DANCE_FN_ADVANCED(NULL, ql_finished, ql_reset) }; + +// Set a long-ish tapping term for tap-dance keys +uint16_t get_tapping_term(uint16_t keycode, keyrecord_t *record) { + switch (keycode) { + case QK_TAP_DANCE ... QK_TAP_DANCE_MAX: + return 275; + default: + return TAPPING_TERM; + } +} ``` The above code is similar to that used in previous examples. The one point to note is that we need to be able to check which layers are active at any time so we can toggle them if needed. To do this we use the `layer_state_is(layer)` function which returns `true` if the given `layer` is active. @@ -521,6 +558,6 @@ The use of `cur_dance()` and `ql_tap_state` mirrors the above examples. The `case: TD_SINGLE_TAP` in `ql_finished` is similar to the above examples. The `TD_SINGLE_HOLD` case works in conjunction with `ql_reset()` to switch to `_MY_LAYER` while the tap dance key is held, and to switch away from `_MY_LAYER` when the key is released. This mirrors the use of `MO(_MY_LAYER)`. The `TD_DOUBLE_TAP` case works by checking whether `_MY_LAYER` is the active layer, and toggling it on or off accordingly. This mirrors the use of `TG(_MY_LAYER)`. -`tap_dance_actions[]` works similar to the above examples. Note that I used `ACTION_TAP_DANCE_FN_ADVANCED_TIME()` instead of `ACTION_TAP_DANCE_FN_ADVANCED()`. This is because I like my `TAPPING_TERM` to be short (\~175ms) for my non-tap-dance keys but find that this is too quick for me to reliably complete tap dance actions - thus the increased time of 275ms here. +`tap_dance_actions[]` works similar to the above examples. Note that, additionally, I set a longer tapping term for the tap dance keys. This is because I like my `TAPPING_TERM` to be short (\~175ms) for my non-tap-dance keys but find that this is too quick for me to reliably complete tap dance actions - thus the increased time of 275ms here. In order for the per-key tapping terms to take effect, `TAPPING_TERM_PER_KEY` must be defined in your `config.h`. Finally, to get this tap dance key working, be sure to include `TD(QUOT_LAYR)` in your `keymaps[]`. diff --git a/docs/feature_terminal.md b/docs/feature_terminal.md deleted file mode 100644 index f850622165..0000000000 --- a/docs/feature_terminal.md +++ /dev/null @@ -1,107 +0,0 @@ -# Terminal - -> This feature is currently *huge*, and should probably only be put on boards with a lot of memory, or for fun. - -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. - -To enable, stick this in your `rules.mk` or `Makefile`: - - TERMINAL_ENABLE = yes - -And use the `TERM_ON` and `TERM_OFF` keycodes to turn it on or off. - -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. - -`#define TERMINAL_HELP` enables some other output helpers that aren't really needed with this page. - -Pressing "up" and "down" will allow you to cycle through the past 5 commands entered. - -## Future Ideas - -* Keyboard/user-extensible commands -* Smaller footprint -* Arrow key support -* Command history - Done -* SD card support -* LCD support for buffer display -* Keycode -> name string LUT -* Layer status -* *Analog/digital port read/write* -* RGB mode stuff -* Macro definitions -* EEPROM read/write -* Audio control - -## Current Commands - -### `about` - -Prints out the current version of QMK with a build date: - -``` -> about -QMK Firmware - v0.5.115-7-g80ed73-dirty - Built: 2017-08-29-20:24:44 -``` - - -### `print-buffer` - -Outputs the last 5 commands entered - -``` -> print-buffer -0. print-buffer -1. help -2. about -3. keymap 0 -4. help -5. flush-buffer -``` - -### `flush-buffer` - -Clears command buffer -``` -> flush-buffer -Buffer cleared! -``` - - -### `help` - - -Prints out the available commands: - -``` -> help -commands available: - about help keycode keymap exit print-buffer flush-buffer -``` - -### `keycode <layer> <row> <col>` - -Prints out the keycode value of a certain layer, row, and column: - -``` -> keycode 0 1 0 -0x29 (41) -``` - -### `keymap <layer>` - -Prints out the entire keymap for a certain layer - -``` -> keymap 0 -0x002b, 0x0014, 0x001a, 0x0008, 0x0015, 0x0017, 0x001c, 0x0018, 0x000c, 0x0012, 0x0013, 0x002a, -0x0029, 0x0004, 0x0016, 0x0007, 0x0009, 0x000a, 0x000b, 0x000d, 0x000e, 0x000f, 0x0033, 0x0034, -0x00e1, 0x001d, 0x001b, 0x0006, 0x0019, 0x0005, 0x0011, 0x0010, 0x0036, 0x0037, 0x0038, 0x0028, -0x5cd6, 0x00e0, 0x00e2, 0x00e3, 0x5cd4, 0x002c, 0x002c, 0x5cd5, 0x0050, 0x0051, 0x0052, 0x004f, -> -``` - -### `exit` - -Exits the terminal - same as `TERM_OFF`. diff --git a/docs/flashing.md b/docs/flashing.md index 271e15b13c..dfb255f2dc 100644 --- a/docs/flashing.md +++ b/docs/flashing.md @@ -358,3 +358,7 @@ CLI Flashing sequence: 2. Wait for the OS to detect the device 3. Flash via QMK CLI eg. `qmk flash --keyboard handwired/onekey/blackpill_f411_tinyuf2 --keymap default` 4. Wait for the keyboard to become available + +### `make` Targets + +* `:uf2-split-left` and `:uf2-split-right`: Flashes the firmware but also sets the handedness setting in EEPROM by generating a side specific firmware. diff --git a/docs/ja/_summary.md b/docs/ja/_summary.md index 81b5756c27..8516a5eaaa 100644 --- a/docs/ja/_summary.md +++ b/docs/ja/_summary.md @@ -85,7 +85,6 @@ * [スワップハンド](ja/feature_swap_hands.md) * [タップダンス](ja/feature_tap_dance.md) * [タップホールド設定](ja/tap_hold.md) - * [ターミナル](ja/feature_terminal.md) * [ユニコード](ja/feature_unicode.md) * [ユーザスペース](ja/feature_userspace.md) * [WPM 計算](ja/feature_wpm.md) diff --git a/docs/ja/config_options.md b/docs/ja/config_options.md index fb43d015f2..42dd9d502a 100644 --- a/docs/ja/config_options.md +++ b/docs/ja/config_options.md @@ -144,7 +144,7 @@ QMK での全ての利用可能な設定にはデフォルトがあります。 ## 設定可能な挙動 :id=behaviors-that-can-be-configured * `#define TAPPING_TERM 200` - * タップがホールドになるまでの時間。500以上に設定された場合、タップ期間中にタップされたキーもホールドになります。(訳注: PERMISSIVE_HOLDも参照) + * タップがホールドになるまでの時間。 * `#define TAPPING_TERM_PER_KEY` * キーごとの `TAPPING_TERM` 設定の処理を有効にします * `#define RETRO_TAPPING` diff --git a/docs/ja/feature_tap_dance.md b/docs/ja/feature_tap_dance.md index a6d108f1e9..762816f21b 100644 --- a/docs/ja/feature_tap_dance.md +++ b/docs/ja/feature_tap_dance.md @@ -28,7 +28,6 @@ * `ACTION_TAP_DANCE_DOUBLE(kc1, kc2)`: 1回タップすると `kc1` キーコードを送信し、2回タップすると `kc2` キーコードを送信します。キーを押し続けているときは、適切なキーコードが登録されます: キーを押し続けた場合は `kc1`、一度タップしてから続けてもう一度キーを押してそのまま押し続けたときは、 `kc2` が登録されます。 * `ACTION_TAP_DANCE_LAYER_MOVE(kc, layer)`: 1回タップすると `kc` キーコードが送信され、2回タップすると `layer` レイヤーに移動します(これは `TO` レイヤーキーコードのように機能します)。 - * この機能は `ACTION_TAP_DANCE_DUAL_ROLE` と同じですが、機能が明確になるように関数名を変更しました。どちらの関数名でも実行できます。 * `ACTION_TAP_DANCE_LAYER_TOGGLE(kc, layer)`: 1回タップすると `kc` キーコードが送信され、2回タップすると `layer` の状態をトグルします(これは `TG` レイヤーキーコードのように機能します)。 * `ACTION_TAP_DANCE_FN(fn)`: ユーザーキーマップに定義した指定の関数が呼び出されます。タップダンス実行の回数分タップすると、最後の時点で呼び出されます。 * `ACTION_TAP_DANCE_FN_ADVANCED(on_each_tap_fn, on_dance_finished_fn, on_dance_reset_fn)`: タップする度にユーザーキーマップに定義した最初の関数が呼び出されます。タップダンスの実行が終わった時点で2番目の関数が呼び出され、タップダンスの実行をリセットするときに最後の関数が呼び出されます。 diff --git a/docs/ja/feature_terminal.md b/docs/ja/feature_terminal.md deleted file mode 100644 index 8e125ecee0..0000000000 --- a/docs/ja/feature_terminal.md +++ /dev/null @@ -1,112 +0,0 @@ -# ターミナル - -<!--- - original document: 0.8.147:docs/feature_terminal.md - git diff 0.8.147 HEAD -- docs/feature_terminal.md | cat ---> - -> この機能は現在のところ*巨大*であり、おそらく大量のメモリを搭載したキーボード、または楽しみのためにのみ配置する必要があります。 - -ターミナル機能はテキストエディタを介してキーストロークで通信するように設計されたコマンドラインのようなインタフェースです。エディタで自動インデント機能をオフにすることは有益です。 - -有効にするには、以下を `rules.mk` または `Makefile` に貼り付けます: - - TERMINAL_ENABLE = yes - -そして、オンまたはオフにするために、`TERM_ON` および `TERM_OFF` キーコードを使います。 - -有効な場合、`> ` プロンプトが現れ、ここでコマンドやバックスペース(オーディオが有効な場合は、先頭に到達するとベルが鳴ります)を入力することができ、エンターを入力するとコマンドを送信します。矢印キーは現在のところ無効なため、混乱することはありません。マウスでカーソルを移動することはお勧めしません。 - -`#define TERMINAL_HELP` は、このページでは実際には必要のない他の出力ヘルパーを有効にします。 - -"上矢印" および "下矢印" により、過去に入力した5つのコマンドを順に切り替えることができます。 - -## 今後のアイデア - -* キーボード/ユーザ拡張可能なコマンド -* より小さなフットプリント -* 矢印キーのサポート -* コマンド履歴 - 完了 -* SD カードのサポート -* バッファディスプレイのための LCD サポート -* キーコード -> 名称の対応表 -* レイヤー状態 -* *アナログ/デジタル ポートの読み込み/書き込み* -* RGB モード関連機能 -* マクロ定義 -* EEPROM の読み込み/書き込み -* オーディオ制御 - -## 現在のコマンド - -### `about` - -現在の QMK のバージョンとビルドした日の出力: - -``` -> about -QMK Firmware - v0.5.115-7-g80ed73-dirty - Built: 2017-08-29-20:24:44 -``` - - -### `print-buffer` - -最後に入力した5つのコマンドの出力 - -``` -> print-buffer -0. print-buffer -1. help -2. about -3. keymap 0 -4. help -5. flush-buffer -``` - -### `flush-buffer` - -コマンドバッファをクリア -``` -> flush-buffer -Buffer cleared! -``` - - -### `help` - - -利用可能なコマンドの出力: - -``` -> help -commands available: - about help keycode keymap exit print-buffer flush-buffer -``` - -### `keycode <layer> <row> <col>` - -特定のレイヤー、行および列のキーコード値の出力: - -``` -> keycode 0 1 0 -0x29 (41) -``` - -### `keymap <layer>` - -特定のレイヤーの全てのキーマップの出力 - -``` -> keymap 0 -0x002b, 0x0014, 0x001a, 0x0008, 0x0015, 0x0017, 0x001c, 0x0018, 0x000c, 0x0012, 0x0013, 0x002a, -0x0029, 0x0004, 0x0016, 0x0007, 0x0009, 0x000a, 0x000b, 0x000d, 0x000e, 0x000f, 0x0033, 0x0034, -0x00e1, 0x001d, 0x001b, 0x0006, 0x0019, 0x0005, 0x0011, 0x0010, 0x0036, 0x0037, 0x0038, 0x0028, -0x5cd6, 0x00e0, 0x00e2, 0x00e3, 0x5cd4, 0x002c, 0x002c, 0x5cd5, 0x0050, 0x0051, 0x0052, 0x004f, -> -``` - -### `exit` - -ターミナルの終了 - `TERM_OFF` と同じ。 diff --git a/docs/ja/understanding_qmk.md b/docs/ja/understanding_qmk.md index 1654f8e002..550ee3a7c0 100644 --- a/docs/ja/understanding_qmk.md +++ b/docs/ja/understanding_qmk.md @@ -161,7 +161,6 @@ const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = { * [`bool process_combo(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_combo.c#L115) * [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_printer.c#L77) * [`bool process_auto_shift(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_auto_shift.c#L94) - * [`bool process_terminal(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_terminal.c#L264) * [Quantum 固有のキーコードを識別して処理する](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L291) この一連のイベントの中の任意のステップで (`process_record_kb()` のような)関数は `false` を返して、以降の処理を停止することができます。 diff --git a/docs/platformdev_chibios_earlyinit.md b/docs/platformdev_chibios_earlyinit.md index aaa91ba438..e1256f2714 100644 --- a/docs/platformdev_chibios_earlyinit.md +++ b/docs/platformdev_chibios_earlyinit.md @@ -20,7 +20,7 @@ As such, if you wish to override this API consider limiting use to writing to lo | `#define STM32_BOOTLOADER_DUAL_BANK` | Relevant for dual-bank STM32 MCUs, signifies that a GPIO is to be toggled in order to enter bootloader mode. | `FALSE` | | `#define STM32_BOOTLOADER_DUAL_BANK_GPIO` | Relevant for dual-bank STM32 MCUs, the pin to toggle when attempting to enter bootloader mode, e.g. `B8` | `<none>` | | `#define STM32_BOOTLOADER_DUAL_BANK_POLARITY` | Relevant for dual-bank STM32 MCUs, the value to set the pin to in order to trigger charging of the RC circuit. e.g. `0` or `1`. | `0` | -| `#define STM32_BOOTLOADER_DUAL_BANK_DELAY` | Relevant for dual-bank STM32 MCUs, an arbitrary measurement of time to delay before resetting the MCU. Increasing number increases the delay. | `100000` | +| `#define STM32_BOOTLOADER_DUAL_BANK_DELAY` | Relevant for dual-bank STM32 MCUs, an arbitrary measurement of time to delay before resetting the MCU. Increasing number increases the delay. | `100` | Kinetis MCUs have no configurable options. diff --git a/docs/reference_info_json.md b/docs/reference_info_json.md index 90b28689d0..d2e9346ee3 100644 --- a/docs/reference_info_json.md +++ b/docs/reference_info_json.md @@ -187,3 +187,39 @@ Example: ``` The device version is a BCD (binary coded decimal) value, in the format `MMmr`, so the below value would look like `0x0100` in the generated code. This also means the maximum valid values for each part are `99.9.9`, despite it being a hexadecimal value under the hood. + +### Encoders + +This section controls the basic [rotary encoder](feature_encoders.md) support. + +The following items can be set. Not every value is required. + +* `pin_a` + * __Required__. A pad definition +* `pin_b` + * __Required__. B pad definition +* `resolution` + * How many pulses the encoder registers between each detent + +Examples: + +```json +{ + "encoder": { + "rotary": [ + { "pin_a": "B5", "pin_b": "A2" } + ] + } +} +``` + +```json +{ + "encoder": { + "rotary": [ + { "pin_a": "B5", "pin_b": "A2", "resolution": 4 } + { "pin_a": "B6", "pin_b": "A3", "resolution": 2 } + ] + } +} +``` diff --git a/docs/serial_driver.md b/docs/serial_driver.md index 3e89deffad..7c0daec9b1 100644 --- a/docs/serial_driver.md +++ b/docs/serial_driver.md @@ -1,129 +1,278 @@ # 'serial' Driver -This driver powers the [Split Keyboard](feature_split_keyboard.md) feature. + +The serial driver powers the [Split Keyboard](feature_split_keyboard.md) feature. Several implementations are available, depending on the platform of your split keyboard. Note that none of the drivers support split keyboards with more then two halves. + +| Driver | AVR | ARM | Connection between halves | +| --------------------------------------- | ------------------ | ------------------ | --------------------------------------------------------------------------------------------- | +| [Bitbang](#bitbang) | :heavy_check_mark: | :heavy_check_mark: | Single wire communication. One wire is used for reception and transmission. | +| [USART Half-duplex](#usart-half-duplex) | | :heavy_check_mark: | Efficient single wire communication. One wire is used for reception and transmission. | +| [USART Full-duplex](#usart-full-duplex) | | :heavy_check_mark: | Efficient two wire communication. Two distinct wires are used for reception and transmission. | ?> Serial in this context should be read as **sending information one bit at a time**, rather than implementing UART/USART/RS485/RS232 standards. -Drivers in this category have the following characteristics: -* bit bang and USART Half-duplex provide data and signaling over a single conductor -* USART Full-duplex provide data and signaling over two conductors -* They are all limited to single master and single slave communication scheme +<hr> + +## Bitbang -## Supported Driver Types +This is the Default driver, the absence of configuration assumes this driver. It works by [bit banging](https://en.wikipedia.org/wiki/Bit_banging) a GPIO pin using the CPU. It is therefore not as efficient as a dedicated hardware peripheral, which the Half-duplex and Full-duplex drivers use. -| | AVR | ARM | -| ----------------- | ------------------ | ------------------ | -| bit bang | :heavy_check_mark: | :heavy_check_mark: | -| USART Half-duplex | | :heavy_check_mark: | -| USART Full-duplex | | :heavy_check_mark: | +!> On ARM platforms the bitbang driver causes connection issues when using it together with the bitbang WS2812 driver. Choosing alternate drivers for both serial and WS2812 (instead of bitbang) is strongly recommended. -## Driver configuration +### Pin configuration + +``` + LEFT RIGHT ++-------+ SERIAL +-------+ +| SSP |-----------------| SSP | +| | VDD | | +| |-----------------| | +| | GND | | +| |-----------------| | ++-------+ +-------+ +``` -### Bitbang -Default driver, the absence of configuration assumes this driver. To configure it, add this to your rules.mk: +One GPIO pin is needed for the bitbang driver, as only one wire is used for receiving and transmitting data. This pin is referred to as the `SOFT_SERIAL_PIN` (SSP) in the configuration. A simple TRS or USB cable provides enough conductors for this driver to work. + +### Setup + +To use the bitbang driver follow these steps to activate it. + +1. Change the `SERIAL_DRIVER` to `bitbang` in your keyboards `rules.mk` file: ```make SERIAL_DRIVER = bitbang ``` -Configure the driver via your config.h: +2. Configure the GPIO pin of your keyboard via the `config.h` file: + ```c #define SOFT_SERIAL_PIN D0 // or D1, D2, D3, E6 -#define SELECT_SOFT_SERIAL_SPEED 1 // or 0, 2, 3, 4, 5 - // 0: about 189kbps (Experimental only) - // 1: about 137kbps (default) - // 2: about 75kbps - // 3: about 39kbps - // 4: about 26kbps - // 5: about 20kbps ``` -#### ARM +3. On ARM platforms you must turn on ChibiOS `PAL_USE_CALLBACKS` feature: + +* In `halconf.h` add the line `#define PAL_USE_CALLBACKS TRUE`. + +<hr> + +## USART Half-duplex + +Targeting ARM boards based on ChibiOS, where communication is offloaded to a USART hardware device that supports Half-duplex operation. The advantages over bitbanging are fast, accurate timings and reduced CPU usage. Therefore it is advised to choose this driver or the Full-duplex driver whenever possible. + +### Pin configuration + +``` + LEFT RIGHT ++-------+ | | +-------+ +| | R R | | +| | | SERIAL | | | +| TX |-----------------| TX | +| | VDD | | +| |-----------------| | +| | GND | | +| |-----------------| | ++-------+ +-------+ +``` + +Only one GPIO pin is needed for the Half-duplex driver, as only one wire is used for receiving and transmitting data. This pin is refereed to as the `SERIAL_USART_TX_PIN` in the configuration. Take care that the pin you chose can act as the TX pin of the USART peripheral. A simple TRS or USB cable provides enough conductors for this driver to work. As the split connection is configured to work in open-drain mode, an **external pull-up resistor is needed to keep the line high**. Resistor values of 1.5kΩ to 8.2kΩ are known to work. -!> The bitbang driver causes connection issues with bitbang WS2812 driver +### Setup -Along with the generic options above, you must also turn on the `PAL_USE_CALLBACKS` feature in your halconf.h. +To use the Half-duplex driver follow these steps to activate it. -### USART Half-duplex -Targeting STM32 boards where communication is offloaded to a USART hardware device. The advantage over bitbang is that this provides fast and accurate timings. `SERIAL_PIN_TX` for this driver is the configured USART TX pin. As this Pin is configured in open-drain mode an **external pull-up resistor is needed to keep the line high** (resistor values of 1.5k to 8.2k are known to work). To configure it, add this to your rules.mk: +1. Change the `SERIAL_DRIVER` to `usart` in your keyboards `rules.mk` file: ```make SERIAL_DRIVER = usart ``` -Configure the hardware via your config.h: +2. Configure the hardware of your keyboard via the `config.h` file: + +```c +#define SERIAL_USART_TX_PIN B6 // The GPIO pin that is used split communication. +``` + +For STM32 MCUs several GPIO configuration options can be changed as well. See the section ["Alternate Functions for selected STM32 MCUs"](alternate-functions-for-selected-stm32-mcus). + ```c -#define SOFT_SERIAL_PIN B6 // USART TX pin -//#define USART1_REMAP // Remap USART TX and RX pins on STM32F103 MCUs, see table below. -#define SELECT_SOFT_SERIAL_SPEED 1 // or 0, 2, 3, 4, 5 - // 0: about 460800 baud - // 1: about 230400 baud (default) - // 2: about 115200 baud - // 3: about 57600 baud - // 4: about 38400 baud - // 5: about 19200 baud -#define SERIAL_USART_DRIVER SD1 // USART driver of TX pin. default: SD1 +#define USART1_REMAP // Remap USART TX and RX pins on STM32F103 MCUs, see table below. #define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 -#define SERIAL_USART_TIMEOUT 20 // USART driver timeout. default 20 ``` -You must also enable the ChibiOS `SERIAL` feature: -* In your board's halconf.h: `#define HAL_USE_SERIAL TRUE` -* In your board's mcuconf.h: `#define STM32_SERIAL_USE_USARTn TRUE` (where 'n' matches the peripheral number of your selected USART on the MCU) +3. Decide either for ChibiOS `SERIAL` or `SIO` subsystem, see the section ["Choosing a ChibiOS driver subsystem"](#choosing-a-chibios-driver-subsystem). -Do note that the configuration required is for the `SERIAL` peripheral, not the `UART` peripheral. +<hr> -### USART Full-duplex -Targeting STM32 boards where communication is offloaded to a USART hardware device. The advantage over bitbang is that this provides fast and accurate timings. USART Full-Duplex requires two conductors **without** pull-up resistors instead of one conductor with a pull-up resistor unlike the Half-duplex driver. Due to its internal design it is more efficent, which can result in even faster transmission speeds. +## USART Full-duplex -#### Pin configuration +Targeting ARM boards based on ChibiOS where communication is offloaded to an USART hardware device. The advantages over bitbanging are fast, accurate timings and reduced CPU usage. Therefore it is advised to choose this driver or the Full-duplex driver whenever possible. Due to its internal design it is slightly more efficient then the Half-duplex driver, but it should be primarily chosen if Half-duplex operation is not supported by the USART peripheral. -`SERIAL_USART_TX_PIN` is the USART `TX` pin, `SERIAL_USART_RX_PIN` is the USART `RX` pin. No external pull-up resistors are needed as the `TX` pin operates in push-pull mode. To use this driver the usart peripherals `TX` and `RX` pins must be configured with the correct Alternate-functions. If you are using a Proton-C everything is already setup, same is true for STM32F103 MCUs. For MCUs which are using a modern flexible GPIO configuration you have to specify these by setting `SERIAL_USART_TX_PAL_MODE` and `SERIAL_USART_RX_PAL_MODE`. Refeer to the corresponding datasheets of your MCU or find those settings in the table below. +### Pin configuration + +``` + LEFT RIGHT ++-------+ +-------+ +| | SERIAL | | +| TX |-----------------| RX | +| | SERIAL | | +| RX |-----------------| TX | +| | VDD | | +| |-----------------| | +| | GND | | +| |-----------------| | ++-------+ +-------+ +``` -#### Connecting the halves and Pin Swap -Please note that `TX` of the master half has to be connected with the `RX` pin of the slave half and `RX` of the master half has to be connected with the `TX` pin of the slave half! Usually this pin swap has to be done outside of the MCU e.g. with cables or on the pcb. Some MCUs like the STM32F303 used on the Proton-C allow this pin swap directly inside the MCU, this feature can be enabled using `#define SERIAL_USART_PIN_SWAP` in your config.h. +Two GPIO pins are needed for the Full-duplex driver, as two distinct wires are used for receiving and transmitting data. The pin transmitting data is the `TX` pin and refereed to as the `SERIAL_USART_TX_PIN`, the pin receiving data is the `RX` pin and refereed to as the `SERIAL_USART_RX_PIN` in this configuration. Please note that `TX` pin of the master half has to be connected with the `RX` pin of the slave half and the `RX` pin of the master half has to be connected with the `TX` pin of the slave half! Usually this pin swap has to be done outside of the MCU e.g. with cables or on the PCB. Some MCUs like the STM32F303 used on the Proton-C allow this pin swap directly inside the MCU. A simple TRRS or USB cable provides enough conductors for this driver to work. -#### Setup -To use the driver, add this to your rules.mk: +To use this driver the usart peripherals `TX` and `RX` pins must be configured with the correct Alternate-functions. If you are using a Proton-C everything is already setup, same is true for STM32F103 MCUs. For MCUs which are using a modern flexible GPIO configuration you have to specify these by setting `SERIAL_USART_TX_PAL_MODE` and `SERIAL_USART_RX_PAL_MODE`. Reefer to the corresponding datasheets of your MCU or find those settings in the section ["Alternate Functions for selected STM32 MCUs"](#alternate-functions-for-selected-stm32-mcus). + +### Setup + +To use the Full-duplex driver follow these steps to activate it. + +1. Change the `SERIAL_DRIVER` to `usart` in your keyboards `rules.mk` file: ```make SERIAL_DRIVER = usart ``` -Next configure the hardware via your config.h: +2. Configure the hardware of your keyboard via the `config.h` file: ```c #define SERIAL_USART_FULL_DUPLEX // Enable full duplex operation mode. #define SERIAL_USART_TX_PIN B6 // USART TX pin #define SERIAL_USART_RX_PIN B7 // USART RX pin -//#define USART1_REMAP // Remap USART TX and RX pins on STM32F103 MCUs, see table below. -//#define SERIAL_USART_PIN_SWAP // Swap TX and RX pins if keyboard is master halve. - // Check if this feature is necessary with your keyboard design and available on the mcu. -#define SELECT_SOFT_SERIAL_SPEED 1 // or 0, 2, 3, 4, 5 - // 0: 460800 baud - // 1: 230400 baud (default) - // 2: 115200 baud - // 3: 57600 baud - // 4: 38400 baud - // 5: 19200 baud -#define SERIAL_USART_DRIVER SD1 // USART driver of TX and RX pin. default: SD1 +``` + +For STM32 MCUs several GPIO configuration options, including the ability for `TX` to `RX` pin swapping, can be changed as well. See the section ["Alternate Functions for selected STM32 MCUs"](alternate-functions-for-selected-stm32-mcus). + +```c +#define SERIAL_USART_PIN_SWAP // Swap TX and RX pins if keyboard is master halve. (Only available on some MCUs) +#define USART1_REMAP // Remap USART TX and RX pins on STM32F103 MCUs, see table below. #define SERIAL_USART_TX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 -#define SERIAL_USART_RX_PAL_MODE 7 // Pin "alternate function", see the respective datasheet for the appropriate values for your MCU. default: 7 +``` + +3. Decide either for ChibiOS `SERIAL` or `SIO` subsystem, see the section ["Choosing a ChibiOS driver subsystem"](#choosing-a-chibios-driver-subsystem). + +<hr> + +## Choosing a ChibiOS driver subsystem + +### The `SERIAL` driver + +The `SERIAL` Subsystem is supported for the majority of ChibiOS MCUs and should be used whenever supported. Follow these steps in order to activate it: + +1. In your keyboards `halconf.h` add: + +```c +#define HAL_USE_SERIAL TRUE +``` + +2. In your keyboards `mcuconf.h`: activate the USART peripheral that is used on your MCU. The shown example is for an STM32 MCU, so this will not work on MCUs by other manufacturers. You can find the correct names in the `mcuconf.h` files of your MCU that ship with ChibiOS. + +Just below `#include_next <mcuconf.h>` add: + +```c +#include_next <mcuconf.h> + +#undef STM32_SERIAL_USE_USARTn +#define STM32_SERIAL_USE_USARTn TRUE +``` + +Where 'n' matches the peripheral number of your selected USART on the MCU. + +3. In you keyboards `config.h`: override the default USART `SERIAL` driver if you use a USART peripheral that does not belong to the default selected `SD1` driver. For instance, if you selected `STM32_SERIAL_USE_USART3` the matching driver would be `SD3`. + +```c + #define SERIAL_USART_DRIVER SD3 + ``` + +### The `SIO` driver + +The `SIO` Subsystem was added to ChibiOS with the 21.11 release and is only supported on selected MCUs. It should only be chosen when the `SERIAL` subsystem is not supported by your MCU. + +Follow these steps in order to activate it: + +1. In your keyboards `halconf.h` add: + +```c +#define HAL_USE_SIO TRUE +``` + +2. In your keyboards `mcuconf.h:` activate the USART peripheral that is used on your MCU. The shown example is for an STM32 MCU, so this will not work on MCUs by other manufacturers. You can find the correct names in the `mcuconf.h` files of your MCU that ship with ChibiOS. + +Just below `#include_next <mcuconf.h>` add: + +```c +#include_next <mcuconf.h> + +#undef STM32_SIO_USE_USARTn +#define STM32_SIO_USE_USARTn TRUE +``` + +Where 'n' matches the peripheral number of your selected USART on the MCU. + +3. In you keyboards `config.h`: override the default USART `SIO` driver if you use a USART peripheral that does not belong to the default selected `SIOD1` driver. For instance, if you selected `STM32_SERIAL_USE_USART3` the matching driver would be `SIOD3`. + +```c + #define SERIAL_USART_DRIVER SIOD3 + ``` + +<hr> + +## Advanced Configuration + +There are several advanced configuration options that can be defined in your keyboards `config.h` file: + +### Baudrate + +If you're having issues or need a higher baudrate with serial communication, you can change the baudrate which in turn controls the communication speed for serial. You want to lower the baudrate if you experience failed transactions. + +```c +#define SELECT_SOFT_SERIAL_SPEED {#} +``` + +| Speed | Bitbang | Half-duplex and Full-duplex | +| ----- | -------------------------- | --------------------------- | +| `0` | 189000 baud (experimental) | 460800 baud | +| `1` | 137000 baud (default) | 230400 baud (default) | +| `2` | 75000 baud | 115200 baud | +| `3` | 39000 baud | 57600 baud | +| `4` | 26000 baud | 38400 baud | +| `5` | 20000 baud | 19200 baud | + +Alternatively you can specify the baudrate directly by defining `SERIAL_USART_SPEED`. + +### Timeout + +This is the default time window in milliseconds in which a successful communication has to complete. Usually you don't want to change this value. But you can do so anyways by defining an alternate one in your keyboards `config.h` file: + +```c #define SERIAL_USART_TIMEOUT 20 // USART driver timeout. default 20 ``` -You must also enable the ChibiOS `SERIAL` feature: -* In your board's halconf.h: `#define HAL_USE_SERIAL TRUE` -* In your board's mcuconf.h: `#define STM32_SERIAL_USE_USARTn TRUE` (where 'n' matches the peripheral number of your selected USART on the MCU) +<hr> + +## Troubleshooting + +If you're having issues withe serial communication, you can enable debug messages that will give you insights which part of the communication failed. The enable these messages add to your keyboards `config.h` file: + +```c +#define SERIAL_DEBUG +``` + +?> The messages will be printed out to the `CONSOLE` output. For additional information, refer to [Debugging/Troubleshooting QMK](faq_debug.md). -Do note that the configuration required is for the `SERIAL` peripheral, not the `UART` peripheral. +## Alternate Functions for selected STM32 MCUs -#### Pins for USART Peripherals with Alternate Functions for selected STM32 MCUs +Pins for USART Peripherals with -##### STM32F303 / Proton-C [Datasheet](https://www.st.com/resource/en/datasheet/stm32f303cc.pdf) +### STM32F303 / Proton-C [Datasheet](https://www.st.com/resource/en/datasheet/stm32f303cc.pdf) Pin Swap available: :heavy_check_mark: -| Pin | Function | Mode | +| Pin | Function | Mode | | ---------- | -------- | ---- | | **USART1** | | | | PA9 | TX | AF7 | @@ -151,11 +300,11 @@ Pin Swap available: :heavy_check_mark: | PD8 | TX | AF7 | | PD9 | RX | AF7 | -##### STM32F072 [Datasheet](https://www.st.com/resource/en/datasheet/stm32f072c8.pdf) +### STM32F072 [Datasheet](https://www.st.com/resource/en/datasheet/stm32f072c8.pdf) Pin Swap available: :heavy_check_mark: -| Pin | Function | Mode | +| Pin | Function | Mode | | ------ | -------- | ---- | | USART1 | | | | PA9 | TX | AF1 | @@ -180,7 +329,7 @@ Pin Swap available: :heavy_check_mark: | PA0 | TX | AF4 | | PA1 | RX | AF4 | -##### STM32F103 Medium Density (C8-CB) [Datasheet](https://www.st.com/resource/en/datasheet/stm32f103c8.pdf) +### STM32F103 Medium Density (C8-CB) [Datasheet](https://www.st.com/resource/en/datasheet/stm32f103c8.pdf) Pin Swap available: N/A @@ -190,7 +339,7 @@ Pin remapping: The pins of USART Peripherals use default Pins that can be remapped to use other pins using the AFIO registers. Default pins are marked **bold**. Add the appropriate defines to your config.h file. -| Pin | Function | Mode | USART_REMAP | +| Pin | Function | Mode | USART_REMAP | | ---------- | -------- | ---- | ------------------- | | **USART1** | | | | | **PA9** | TX | AFPP | | diff --git a/docs/understanding_qmk.md b/docs/understanding_qmk.md index 9b80fb179e..c1bcfe3ce9 100644 --- a/docs/understanding_qmk.md +++ b/docs/understanding_qmk.md @@ -155,7 +155,6 @@ The `process_record()` function itself is deceptively simple, but hidden within * [`bool process_printer(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_printer.c#L77) * [`bool process_auto_shift(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_auto_shift.c#L94) * `bool process_dynamic_tapping_term(uint16_t keycode, keyrecord_t *record)` - * [`bool process_terminal(uint16_t keycode, keyrecord_t *record)`](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/process_keycode/process_terminal.c#L264) * [Identify and process Quantum-specific keycodes](https://github.com/qmk/qmk_firmware/blob/e1203a222bb12ab9733916164a000ef3ac48da93/quantum/quantum.c#L291) At any step during this chain of events a function (such as `process_record_kb()`) can `return false` to halt all further processing. diff --git a/docs/zh-cn/_summary.md b/docs/zh-cn/_summary.md index dbad1021fa..3baee6dc2e 100644 --- a/docs/zh-cn/_summary.md +++ b/docs/zh-cn/_summary.md @@ -91,7 +91,6 @@ * [换手](zh-cn/feature_swap_hands.md) * [一键多用](zh-cn/feature_tap_dance.md) * [点按配置](zh-cn/tap_hold.md) - * [终端](zh-cn/feature_terminal.md) * [Unicode](zh-cn/feature_unicode.md) * [用户空间](zh-cn/feature_userspace.md) * [WPM计算](zh-cn/feature_wpm.md) diff --git a/docs/zh-cn/custom_quantum_functions.md b/docs/zh-cn/custom_quantum_functions.md index 29c5089052..dba9e7e7c0 100644 --- a/docs/zh-cn/custom_quantum_functions.md +++ b/docs/zh-cn/custom_quantum_functions.md @@ -240,7 +240,7 @@ void suspend_wakeup_init_user(void) { ```c layer_state_t layer_state_set_user(layer_state_t state) { - switch (biton32(state)) { + switch (get_highest_layer(state)) { case _RAISE: rgblight_setrgb (0x00, 0x00, 0xFF); break; @@ -267,7 +267,7 @@ layer_state_t layer_state_set_user(layer_state_t state) { ### `layer_state_set_*` 函数文档 -* 键盘/各子版本：`uint32_t layer_state_set_kb(uint32_t state)` +* 键盘/各子版本：`layer_state_t layer_state_set_kb(layer_state_t state)` * 布局: `layer_state_t layer_state_set_user(layer_state_t state)` @@ -325,7 +325,7 @@ void keyboard_post_init_user(void) { ```c layer_state_t layer_state_set_user(layer_state_t state) { - switch (biton32(state)) { + switch (get_highest_layer(state)) { case _RAISE: if (user_config.rgb_layer_change) { rgblight_sethsv_noeeprom_magenta(); rgblight_mode_noeeprom(1); } break; @@ -474,4 +474,3 @@ cancel_deferred_exec(my_token); ```c #define MAX_DEFERRED_EXECUTORS 16 ``` - |