From 7060cb7b267e78ba693a77a3346c77c2d4209b01 Mon Sep 17 00:00:00 2001 From: precondition <57645186+precondition@users.noreply.github.com> Date: Thu, 23 Jun 2022 20:43:24 +0200 Subject: Refactor steno and add `STENO_PROTOCOL = [all|txbolt|geminipr]` (#17065) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Refactor steno into STENO_ENABLE_[ALL|GEMINI|BOLT] * Update stenography documentation * STENO_ENABLE_TXBOLT → STENO_ENABLE_BOLT TXBOLT is a better name but BOLT is more consistent with the pre-existing TX Bolt related constants, which all drop the "TX " prefix * Comments * STENO_ENABLE_[GEMINI|BOLT|ALL] → STENO_PROTOCOL = [geminipr|txbolt|all] * Add note on lacking V-USB support * Clear chord at the end of the switch(mode){send_steno_chord} block * Return true if NOEVENT * update_chord_xxx → add_xxx_key_to_chord * Enable the defines for all the protocols if STENO_PROTOCOL = all * Mention how to use `steno_set_mode` * Set the default steno protocol to "all" This is done so that existing keymaps invoking `steno_set_mode` don't all suddenly break * Add data driver equivalents for stenography feature * Document format of serial steno packets (Thanks dnaq) * Add missing comma --- quantum/process_keycode/process_steno.c | 312 +++++++++++++++++--------------- 1 file changed, 170 insertions(+), 142 deletions(-) (limited to 'quantum/process_keycode/process_steno.c') diff --git a/quantum/process_keycode/process_steno.c b/quantum/process_keycode/process_steno.c index 12ee898212..20b8b9db4b 100644 --- a/quantum/process_keycode/process_steno.c +++ b/quantum/process_keycode/process_steno.c @@ -1,4 +1,4 @@ -/* Copyright 2017 Joseph Wasson +/* Copyright 2017, 2022 Joseph Wasson, Vladislav Kucheriavykh * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -15,77 +15,118 @@ */ #include "process_steno.h" #include "quantum_keycodes.h" -#include "eeprom.h" #include "keymap_steno.h" -#include "virtser.h" #include +#ifdef VIRTSER_ENABLE +# include "virtser.h" +#endif +#ifdef STENO_ENABLE_ALL +# include "eeprom.h" +#endif -// TxBolt Codes -#define TXB_NUL 0 -#define TXB_S_L 0b00000001 -#define TXB_T_L 0b00000010 -#define TXB_K_L 0b00000100 -#define TXB_P_L 0b00001000 -#define TXB_W_L 0b00010000 -#define TXB_H_L 0b00100000 -#define TXB_R_L 0b01000001 -#define TXB_A_L 0b01000010 -#define TXB_O_L 0b01000100 -#define TXB_STR 0b01001000 -#define TXB_E_R 0b01010000 -#define TXB_U_R 0b01100000 -#define TXB_F_R 0b10000001 -#define TXB_R_R 0b10000010 -#define TXB_P_R 0b10000100 -#define TXB_B_R 0b10001000 -#define TXB_L_R 0b10010000 -#define TXB_G_R 0b10100000 -#define TXB_T_R 0b11000001 -#define TXB_S_R 0b11000010 -#define TXB_D_R 0b11000100 -#define TXB_Z_R 0b11001000 -#define TXB_NUM 0b11010000 - -#define TXB_GRP0 0b00000000 -#define TXB_GRP1 0b01000000 -#define TXB_GRP2 0b10000000 -#define TXB_GRP3 0b11000000 -#define TXB_GRPMASK 0b11000000 - -#define TXB_GET_GROUP(code) ((code & TXB_GRPMASK) >> 6) - -#define BOLT_STATE_SIZE 4 -#define GEMINI_STATE_SIZE 6 -#define MAX_STATE_SIZE GEMINI_STATE_SIZE - -static uint8_t state[MAX_STATE_SIZE] = {0}; -static uint8_t chord[MAX_STATE_SIZE] = {0}; -static int8_t pressed = 0; +// All steno keys that have been pressed to form this chord, +// stored in MAX_STROKE_SIZE groups of 8-bit arrays. +static uint8_t chord[MAX_STROKE_SIZE] = {0}; +// The number of physical keys actually being held down. +// This is not always equal to the number of 1 bits 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. +static int8_t n_pressed_keys = 0; + +#ifdef STENO_ENABLE_ALL static steno_mode_t mode; - -static const uint8_t boltmap[64] PROGMEM = {TXB_NUL, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_S_L, TXB_S_L, TXB_T_L, TXB_K_L, TXB_P_L, TXB_W_L, TXB_H_L, TXB_R_L, TXB_A_L, TXB_O_L, TXB_STR, TXB_STR, TXB_NUL, TXB_NUL, TXB_NUL, TXB_STR, TXB_STR, TXB_E_R, TXB_U_R, TXB_F_R, TXB_R_R, TXB_P_R, TXB_B_R, TXB_L_R, TXB_G_R, TXB_T_R, TXB_S_R, TXB_D_R, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_Z_R}; - -#ifdef STENO_COMBINEDMAP -/* Used to look up when pressing the middle row key to combine two consonant or vowel keys */ -static const uint16_t combinedmap_first[] PROGMEM = {STN_S1, STN_TL, STN_PL, STN_HL, STN_FR, STN_PR, STN_LR, STN_TR, STN_DR, STN_A, STN_E}; -static const uint16_t combinedmap_second[] PROGMEM = {STN_S2, STN_KL, STN_WL, STN_RL, STN_RR, STN_BR, STN_GR, STN_SR, STN_ZR, STN_O, STN_U}; +#elif defined(STENO_ENABLE_GEMINI) +static const steno_mode_t mode = STENO_MODE_GEMINI; +#elif defined(STENO_ENABLE_BOLT) +static const steno_mode_t mode = STENO_MODE_BOLT; #endif -static void steno_clear_state(void) { - memset(state, 0, sizeof(state)); +static inline void steno_clear_chord(void) { memset(chord, 0, sizeof(chord)); } -static void send_steno_state(uint8_t size, bool send_empty) { - for (uint8_t i = 0; i < size; ++i) { - if (chord[i] || send_empty) { -#ifdef VIRTSER_ENABLE +#ifdef STENO_ENABLE_GEMINI + +# ifdef VIRTSER_ENABLE +void send_steno_chord_gemini(void) { + // Set MSB to 1 to indicate the start of packet + chord[0] |= 0x80; + for (uint8_t i = 0; i < GEMINI_STROKE_SIZE; ++i) { + virtser_send(chord[i]); + } +} +# else +# pragma message "VIRTSER_ENABLE = yes is required for Gemini PR to work properly out of the box!" +# endif // VIRTSER_ENABLE + +/** + * @precondition: `key` is pressed + */ +bool add_gemini_key_to_chord(uint8_t key) { + // Although each group of the packet is 8 bits long, the MSB is reserved + // to indicate whether that byte is the first byte of the packet (MSB=1) + // or one of the remaining five bytes of the packet (MSB=0). + // As a consequence, only 7 out of the 8 bits are left to be used as a bit array + // for the steno keys of that group. + const int group_idx = key / 7; + const int intra_group_idx = key - group_idx * 7; + // The 0th steno key of the group has bit=0b01000000, the 1st has bit=0b00100000, etc. + const uint8_t bit = 1 << (6 - intra_group_idx); + chord[group_idx] |= bit; + return false; +} +#endif // STENO_ENABLE_GEMINI + +#ifdef STENO_ENABLE_BOLT + +# define TXB_GRP0 0b00000000 +# define TXB_GRP1 0b01000000 +# define TXB_GRP2 0b10000000 +# define TXB_GRP3 0b11000000 +# define TXB_GRPMASK 0b11000000 + +# define TXB_GET_GROUP(code) ((code & TXB_GRPMASK) >> 6) + +static const uint8_t boltmap[64] PROGMEM = {TXB_NUL, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_S_L, TXB_S_L, TXB_T_L, TXB_K_L, TXB_P_L, TXB_W_L, TXB_H_L, TXB_R_L, TXB_A_L, TXB_O_L, TXB_STR, TXB_STR, TXB_NUL, TXB_NUL, TXB_NUL, TXB_STR, TXB_STR, TXB_E_R, TXB_U_R, TXB_F_R, TXB_R_R, TXB_P_R, TXB_B_R, TXB_L_R, TXB_G_R, TXB_T_R, TXB_S_R, TXB_D_R, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_Z_R}; + +# ifdef VIRTSER_ENABLE +static void send_steno_chord_bolt(void) { + for (uint8_t i = 0; i < BOLT_STROKE_SIZE; ++i) { + // TX Bolt uses variable length packets where each byte corresponds to a bit array of certain keys. + // If a user chorded the keys of the first group with keys of the last group, for example, there + // would be bytes of 0x00 in `chord` for the middle groups which we mustn't send. + if (chord[i]) { virtser_send(chord[i]); -#endif } } + // Sending a null packet is not always necessary, but it is simpler and more reliable + // to unconditionally send it every time instead of keeping track of more states and + // creating more branches in the execution of the program. + virtser_send(0); } +# else +# pragma message "VIRTSER_ENABLE = yes is required for TX Bolt to work properly out of the box!" +# endif // VIRTSER_ENABLE + +/** + * @precondition: `key` is pressed + */ +static bool add_bolt_key_to_chord(uint8_t key) { + uint8_t boltcode = pgm_read_byte(boltmap + key); + chord[TXB_GET_GROUP(boltcode)] |= boltcode; + return false; +} +#endif // STENO_ENABLE_BOLT + +#ifdef STENO_COMBINEDMAP +/* Used to look up when pressing the middle row key to combine two consonant or vowel keys */ +static const uint16_t combinedmap_first[] PROGMEM = {STN_S1, STN_TL, STN_PL, STN_HL, STN_FR, STN_PR, STN_LR, STN_TR, STN_DR, STN_A, STN_E}; +static const uint16_t combinedmap_second[] PROGMEM = {STN_S2, STN_KL, STN_WL, STN_RL, STN_RR, STN_BR, STN_GR, STN_SR, STN_ZR, STN_O, STN_U}; +#endif +#ifdef STENO_ENABLE_ALL void steno_init() { if (!eeconfig_is_enabled()) { eeconfig_init(); @@ -94,19 +135,20 @@ void steno_init() { } void steno_set_mode(steno_mode_t new_mode) { - steno_clear_state(); + steno_clear_chord(); mode = new_mode; eeprom_update_byte(EECONFIG_STENOMODE, mode); } +#endif // STENO_ENABLE_ALL /* override to intercept chords right before they get sent. * return zero to suppress normal sending behavior. */ -__attribute__((weak)) bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[6]) { +__attribute__((weak)) bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[MAX_STROKE_SIZE]) { return true; } -__attribute__((weak)) bool postprocess_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[6], int8_t pressed) { +__attribute__((weak)) 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) { return true; } @@ -114,108 +156,94 @@ __attribute__((weak)) bool process_steno_user(uint16_t keycode, keyrecord_t *rec return true; } -static void send_steno_chord(void) { - if (send_steno_chord_user(mode, chord)) { - switch (mode) { - case STENO_MODE_BOLT: - send_steno_state(BOLT_STATE_SIZE, false); -#ifdef VIRTSER_ENABLE - virtser_send(0); // terminating byte -#endif - break; - case STENO_MODE_GEMINI: - chord[0] |= 0x80; // Indicate start of packet - send_steno_state(GEMINI_STATE_SIZE, true); - break; - } +bool process_steno(uint16_t keycode, keyrecord_t *record) { + if (keycode < QK_STENO || keycode > QK_STENO_MAX) { + return true; // Not a steno key, pass it further along the chain + /* + * Clearing or sending the chord state is not necessary as we intentionally ignore whatever + * normal keyboard keys the user may have tapped while chording steno keys. + */ } - steno_clear_state(); -} - -uint8_t *steno_get_state(void) { - return &state[0]; -} - -uint8_t *steno_get_chord(void) { - return &chord[0]; -} - -static bool update_state_bolt(uint8_t key, bool press) { - uint8_t boltcode = pgm_read_byte(boltmap + key); - if (press) { - state[TXB_GET_GROUP(boltcode)] |= boltcode; - chord[TXB_GET_GROUP(boltcode)] |= boltcode; - } else { - state[TXB_GET_GROUP(boltcode)] &= ~boltcode; + if (IS_NOEVENT(record->event)) { + return true; } - return false; -} - -static bool update_state_gemini(uint8_t key, bool press) { - int idx = key / 7; - uint8_t bit = 1 << (6 - (key % 7)); - if (press) { - state[idx] |= bit; - chord[idx] |= bit; - } else { - state[idx] &= ~bit; + if (!process_steno_user(keycode, record)) { + return false; // User fully processed the steno key themselves } - return false; -} - -bool process_steno(uint16_t keycode, keyrecord_t *record) { switch (keycode) { +#ifdef STENO_ENABLE_ALL case QK_STENO_BOLT: - if (!process_steno_user(keycode, record)) { - return false; - } if (IS_PRESSED(record->event)) { steno_set_mode(STENO_MODE_BOLT); } return false; case QK_STENO_GEMINI: - if (!process_steno_user(keycode, record)) { - return false; - } if (IS_PRESSED(record->event)) { steno_set_mode(STENO_MODE_GEMINI); } return false; +#endif // STENO_ENABLE_ALL #ifdef STENO_COMBINEDMAP case QK_STENO_COMB ... QK_STENO_COMB_MAX: { - uint8_t result; - result = process_steno(combinedmap_first[keycode - QK_STENO_COMB], record); - result &= process_steno(combinedmap_second[keycode - QK_STENO_COMB], record); - return result; + bool first_result = process_steno(combinedmap_first[keycode - QK_STENO_COMB], record); + bool second_result = process_steno(combinedmap_second[keycode - QK_STENO_COMB], record); + return first_result && second_result; } -#endif +#endif // STENO_COMBINEDMAP case STN__MIN ... STN__MAX: - if (!process_steno_user(keycode, record)) { - return false; - } - switch (mode) { - case STENO_MODE_BOLT: - update_state_bolt(keycode - QK_STENO, IS_PRESSED(record->event)); - break; - case STENO_MODE_GEMINI: - update_state_gemini(keycode - QK_STENO, IS_PRESSED(record->event)); - break; - } - // allow postprocessing hooks - if (postprocess_steno_user(keycode, record, mode, chord, pressed)) { - if (IS_PRESSED(record->event)) { - ++pressed; - } else { - --pressed; - if (pressed <= 0) { - pressed = 0; - send_steno_chord(); - } + if (IS_PRESSED(record->event)) { + n_pressed_keys++; + switch (mode) { +#ifdef STENO_ENABLE_BOLT + case STENO_MODE_BOLT: + add_bolt_key_to_chord(keycode - QK_STENO); + break; +#endif // STENO_ENABLE_BOLT +#ifdef STENO_ENABLE_GEMINI + case STENO_MODE_GEMINI: + add_gemini_key_to_chord(keycode - QK_STENO); + break; +#endif // STENO_ENABLE_GEMINI + default: + return false; } + if (!postprocess_steno_user(keycode, record, mode, chord, n_pressed_keys)) { + return false; + } + } else { // is released + n_pressed_keys--; + if (!postprocess_steno_user(keycode, record, mode, chord, n_pressed_keys)) { + return false; + } + if (n_pressed_keys > 0) { + // User hasn't released all keys yet, + // so the chord cannot be sent + return false; + } + n_pressed_keys = 0; + if (!send_steno_chord_user(mode, chord)) { + steno_clear_chord(); + return false; + } + switch (mode) { +#if defined(STENO_ENABLE_BOLT) && defined(VIRTSER_ENABLE) + case STENO_MODE_BOLT: + send_steno_chord_bolt(); + break; +#endif // STENO_ENABLE_BOLT && VIRTSER_ENABLE +#if defined(STENO_ENABLE_GEMINI) && defined(VIRTSER_ENABLE) + case STENO_MODE_GEMINI: + send_steno_chord_gemini(); + break; +#endif // STENO_ENABLE_GEMINI && VIRTSER_ENABLE + default: + break; + } + steno_clear_chord(); } - return false; + break; } - return true; + return false; } -- cgit v1.2.3