qmk_firmware

QMK firmware for my keyboards (Corne, Sweep Ferris) and trackball (Ploopy Adept)
Log | Files | Refs | Submodules | LICENSE

readme.md (6165B)


      1 # Fast and extensible matrix.c
      2 
      3 This matrix.c is faster and more extensible than the standard quantum/matrix.c.
      4 
      5 * The execution speed of the `matrix_scan()` function is several times faster than quantum/matrix.c.
      6 * In addition to handling MCU GPIOs, it can be extended to handle I/O extenders.
      7 
      8 ## ToDo list
      9 - [x] support Pro Micro
     10 - [x] support Proton-C
     11 - [x] support DIRECT_PINS
     12 - [x] support DIODE_DIRECTION == ROW2COL
     13 - [x] support 74HC157: quadruple 2-line to 1-line data selectors / multiplexers
     14 - [x] support 74HC153: dual 4-line to 1-line data selectors / multiplexers
     15 - [ ] support I/O expander (MCP23018)
     16 - [ ] support MCU & I/O expander (MCP23018) mixture like ErgoDox
     17 
     18 ## Current performance
     19 
     20   | MCU               | delay type    | execution time <br> of <br> `matrix_scan()` | matrix scan rate |
     21   |-------------------|---------------|------------|-----------------|
     22   | Pro Micro (16MHz) | fast adaptive | 75.6us     |  8090 scans/sec |
     23   | Proton C (72MHz)  | fast adaptive | 49.8us     | 15100 scans/sec |
     24 
     25 ## Configuration
     26 
     27 This matrix.c requires a different configuration than quantum/matrix.c.
     28 
     29 ### Output pins configuration
     30 
     31 The output pins is the Row pins if `DIODE_DIRECTION == COL2ROW`, and the Col pins if `DIODE_DIRECTION == ROW2COL`. When DIRECT_PINS is defined, the output pins do not need to be set.
     32 
     33 Example:
     34 ```c
     35 // list of OUTPUT(row) ports
     36 #define MATRIX_OUT_PORTS  \
     37     (Port_D, MCU_GPIO, D0), \
     38     (Port_C, MCU_GPIO, C0), \
     39     (Port_E, MCU_GPIO, E0), \
     40     (Port_B, MCU_GPIO, B0)
     41 // list of OUTPUT pins
     42 #define MATRIX_OUT_PINS  \
     43     (0, Port_D, 4), \
     44     (1, Port_C, 6), \
     45     (2, Port_D, 7), \
     46     (3, Port_E, 6), \
     47     (4, Port_B, 4), \
     48     (5, Port_B, 5)
     49 ```
     50 
     51 ### Input pins configuration
     52 
     53 The input pins is the Col pins if `DIODE_DIRECTION == COL2ROW`, and the Row pins if `DIODE_DIRECTION == ROW2COL`. When DIRECT_PINS is defined, the input pin settings will enumerate the connection pins of all switches.
     54 
     55 Example:
     56 ```c
     57 // list of INPUT ports
     58 #define MATRIX_IN_PORTS (Port_F, MCU_GPIO, F0), (Port_B, MCU_GPIO, B0)
     59 // list of INPUT pins
     60 #define MATRIX_IN_PINS \
     61     (0, Port_F, 4), \
     62     (1, Port_F, 5), \
     63     (2, Port_F, 6), \
     64     (3, Port_F, 7), \
     65     (4, Port_B, 1), \
     66     (5, Port_B, 3)
     67 ```
     68 
     69 ### Multiplexer Extension
     70 
     71 By defining the `MATRIX_EXTENSION_74HC157` macro or `MATRIX_EXTENSION_74HC153` macro, you can connect a multiplexer to the GPIO to extend the input pins.
     72 
     73 Example:
     74 ```c
     75 #define MATRIX_EXTENSION_74HC157 B2 /* or #define MATRIX_EXTENSION_74HC153 B2, B6 */
     76 
     77 // list of OUTPUT ports
     78 #define MATRIX_OUT_PORTS (Port_D, MCU_GPIO, D0), (Port_C, MCU_GPIO, C0), (Port_E, MCU_GPIO, E0), (Port_B, MCU_GPIO, B0)
     79 // list of OUTPUT pins
     80 #define MATRIX_OUT_PINS  (0, Port_D, 4), (1, Port_C, 6), (2, Port_D, 7), (3, Port_E, 6), (4, Port_B, 4), (5, Port_B, 5)
     81 
     82 // list of INPUT ports
     83 #define MATRIX_IN_PORTS \
     84     (Port_Fa, MCU_GPIOa, F0), \
     85     (Port_Ba, MCU_GPIOa, B0), \
     86     (Port_Fb, MCU_GPIOb, F0), \
     87     (Port_Bb, MCU_GPIOb, B0)
     88 // list of INPUT pins
     89 #define MATRIX_IN_PINS \
     90     (0, Port_Fa, 4), \
     91     (1, Port_Fb, 5), \
     92     (2, Port_Fb, 6), \
     93     (3, Port_Fa, 7), \
     94     (4, Port_Ba, 1), \
     95     (5, Port_Bb, 3)
     96 ```
     97 
     98 ### I/O expander Extension
     99 
    100 I plan to provide extensions to support I/O expanders such as MCP23018 and PCA9555.
    101 
    102 ## Compile
    103 
    104 * Measure the execution time of matrix_scan()
    105   * `make MTEST=matrix_debug_scan[,<other options>..] handwired/symmetric70_proto/promicro/fast:default:flash`
    106 * Measure delay time.
    107   * `make MTEST=matrix_debug_delay[,<other options>..] handwired/symmetric70_proto/promicro/fast:default:flash`
    108 
    109 ## Measurement result
    110 ### Pro Micro (ATmega32u4 16Mhz)
    111 #### Default setting (show `matrix_scan()` time)
    112  - `make MTEST=matrix_debug_scan handwired/symmetric70_proto/promicro/fast:default:flash`
    113  - CH1: Row 0
    114  - CH2: Row 1
    115  - CH3: Row 4
    116  - CH4: matrix_scan()
    117  - Execution time of matrix_scan()  75.6us
    118  - Frequency of matrix scan 8.09kHz (123.6us)
    119  ![DS1Z_QuickPrint7](https://user-images.githubusercontent.com/2170248/116003927-538d9100-a63b-11eb-9b36-7db47d9b1541.png)
    120 
    121 #### Default setting (show delay time)
    122  - `make MTEST=matrix_debug_delay handwired/symmetric70_proto/promicro/fast:default:flash`
    123 ##### Press R0C0 key
    124  - CH1: Row 0
    125  - CH2: Row 1
    126  - CH3: Row 4
    127  - CH4: delay time
    128  - Frequency of matrix scan 7.84kHz (127.6us)
    129 
    130 ![DS1Z_QuickPrint9](https://user-images.githubusercontent.com/2170248/116003974-99e2f000-a63b-11eb-9c9e-3b3b1025db66.png)
    131 ![DS1Z_QuickPrint10](https://user-images.githubusercontent.com/2170248/116003978-a1a29480-a63b-11eb-97d8-5a6e11c0db2f.png)
    132 
    133 ### Proton C
    134 #### Default setting (show `matrix_scan()` time)
    135  - `make MTEST=matrix_debug_scan handwired/symmetric70_proto/proton_c/fast:default:flash`
    136  - CH1: Row 0
    137  - CH2: Row 1
    138  - CH3: Row 4
    139  - CH4: matrix_scan()
    140  - Execution time of matrix_scan()  49.8us
    141  - Frequency of matrix scan 15.1kHz (66.2.6us)
    142 
    143 ![DS1Z_QuickPrint11](https://user-images.githubusercontent.com/2170248/116088141-8cca0d80-a6dc-11eb-8782-1d29c57690b8.png)
    144 
    145 #### Default setting (show delay time)
    146  - `make MTEST=matrix_debug_delay handwired/symmetric70_proto/proton_c/fast:default:flash`
    147 ##### Press R0C0 key
    148  - CH1: Row 0
    149  - CH2: Row 1
    150  - CH3: Row 4
    151  - CH4: delay time
    152  - Frequency of matrix scan 13.9kHz (71.8us)
    153 
    154 ![DS1Z_QuickPrint12](https://user-images.githubusercontent.com/2170248/116088247-a8cdaf00-a6dc-11eb-8a47-104694a40117.png)
    155 ![DS1Z_QuickPrint13](https://user-images.githubusercontent.com/2170248/116088262-ac613600-a6dc-11eb-804c-7dcbd71c83d5.png)
    156 
    157 ##### Connect a 500pF capacitor between C0 line and GND, Press R0C0, R1C0, R2C0,  R3C0,  R4C0 keys
    158  - CH1: Row 0
    159  - CH2: Row 1
    160  - CH3: Col 0
    161  - CH4: delay time
    162  - Delay time 11.6us
    163  - Threshold Voltage 1.9V
    164 
    165 ![DS1Z_QuickPrint14](https://user-images.githubusercontent.com/2170248/116089205-90aa5f80-a6dd-11eb-89c4-72315c80ba0e.png)
    166 
    167 ##### Connect a 1000pF capacitor between C0 line and GND, Press R0C0, R1C0, R2C0,  R3C0,  R4C0 keys
    168  - CH1: Row 0
    169  - CH2: Row 1
    170  - CH3: Col 0
    171  - CH4: delay time
    172  - Delay time 18.6us
    173  - Threshold Voltage 1.9V
    174 
    175 ![DS1Z_QuickPrint15](https://user-images.githubusercontent.com/2170248/116089229-96a04080-a6dd-11eb-8b63-f91b03a9db0c.png)