keyboards/xd84/dev.md

   1 # XD84
   2
   3 Development docs covering the following:
   4 - Kimera core
   5 - RGB
   6 - Backlight
   7 - Light Through Cat
   8
   9 ## Kimera core
  10 ![Kimera core](https://gd2.alicdn.com/imgextra/i4/159916802/TB2qsIgdrJkpuFjy1zcXXa5FFXa_!!159916802.jpg)
  11
  12 What little available info that was available for the qmk port
  13 - atmega32u4 16Mhz
  14   - board seems to have a 6Mhz crystal
  15 - 2x PCA9555 I2C IO expander
  16
  17 Links:
  18 - [Schematic, BOM, Gerbers](/kairyu/kimera/blob/master/kimera_core)
  19 - [Original firmware](https://github.com/kairyu/tmk_keyboard_custom/tree/master/keyboard/kimera)
  20
  21 ```c
  22 /*
  23 Kimera_core_v1.0 Components
  24
  25              U1 (atmega32u4)
  26            ,----------------.
  27       TX --| TX0(PD3)   RAW |--
  28       RX --| RX1(PD2)   GND |--
  29          --| GND      RESET |-- RST
  30          --| GND        VCC |--
  31      SDA --| 2(PD1) (PF4)A3 |--
  32      SCL --| 3(PD0) (PF5)A2 |--
  33    (INT) --| 4(PD4) (PF6)A1 |--
  34          --| 5(PC6) (PF7)A0 |--
  35          --| 6(PD7) (PB1)15 |-- SCK
  36     LED2 --| 7(PE6) (PB3)14 |-- MISO
  37     LED1 --| 8(PB4) (PB2)16 |-- MOSI
  38     LED3 --| 9(PB5) (PB6)10 |-- LED4
  39           `----------------'
  40
  41          IC1 (PCA9555)                  IC2 (PCA9555)
  42          ,----------.                   ,----------.
  43    SDA --| SDA  P00 |-- P1        SDA --| SDA  P00 |-- P17
  44    SCL --| SCL  P01 |-- P2        SCL --| SCL  P01 |-- P18
  45    INT --| INT  P02 |-- P3        INT --| INT  P02 |-- P19
  46          |      P03 |-- P4              |      P03 |-- P20
  47    GND --| A0   P04 |-- P5        VCC --| A0   P04 |-- P21
  48    SJ1 --| A1   P05 |-- P6        SJ1 --| A1   P05 |-- P22
  49    SJ2 --| A2   P06 |-- P7        SJ2 --| A2   P06 |-- P23
  50          |      P07 |-- P8              |      P07 |-- P24
  51          |          |                   |          |
  52          |      P10 |-- P9              |      P10 |-- P25
  53          |      P11 |-- P10             |      P11 |-- P26
  54          |      P12 |-- P11             |      P12 |-- P27
  55          |      P13 |-- P12             |      P13 |-- P28
  56          |      P14 |-- P13             |      P14 |-- P29
  57          |      P15 |-- P14             |      P15 |-- P30
  58          |      P16 |-- P15             |      P16 |-- P31
  59          |      P17 |-- P16             |      P17 |-- P32
  60          `----------'                   `----------'
  61 */
  62
  63 ```
  64
  65 ### Bootloader
  66 Default bootloader is `atmel-dfu`.
  67 Reboot to bootloader via magnetic switch next to icsp header.
  68 Flash using regular dfu methods.
  69
  70 ### XD84 pin mappings
  71 Taken from [kimera-config.json](https://github.com/kairyu/tkg/blob/master/keyboard/config/kimera-config.json)
  72
  73         "row_mapping": [ 1, 2, 3, 4, 5, 6 ],
  74         "col_mapping": [ 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31 ],
  75
  76 # RGB
  77 - PIN C7
  78 - Number of RGB LED 7
  79
  80 # Backlight
  81 - PIN B6
  82
  83 # Light Through Cat
  84     TODO - PWM C6
  85
  86 ## Assumptions
  87 ### Pin/Port mappings
  88 - All cols are on the same IC
  89 - All rows are on the same IC and port
  90 - Pins mapped sequentially
  91 - Each port only does row or column not a mixture of both
  92   - No need to have complex port config
  93   -
  94
  95 | ROW index | Kimera Pin | PCA9555           |
  96 | ----------|------------|-------------------|
  97 | 0         | 1          | IC1 Port 0  pin 0 |
  98 | 1         | 2          | IC1 Port 0  pin 1 |
  99 | 2         | 3          | IC1 Port 0  pin 2 |
 100 | 3         | 4          | IC1 Port 0  pin 3 |
 101 | 4         | 5          | IC1 Port 0  pin 4 |
 102 | 5         | 6          | IC1 Port 0  pin 5 |
 103
 104 - Safe enough to assume `row_index == pin`
 105
 106
 107 | COL index | Kimera Pin | PCA9555           |
 108 | ----------|------------|-------------------|
 109 | 0         | 17         | IC2 Port 0  pin 0 |
 110 | 1         | 18         | IC2 Port 0  pin 1 |
 111 | 2         | 19         | IC2 Port 0  pin 2 |
 112 | 3         | 20         | IC2 Port 0  pin 3 |
 113 | 4         | 21         | IC2 Port 0  pin 4 |
 114 | 5         | 22         | IC2 Port 0  pin 5 |
 115 | 6         | 23         | IC2 Port 0  pin 6 |
 116 | 7         | 24         | IC2 Port 0  pin 7 |
 117 | 8         | 25         | IC2 Port 1  pin 0 |
 118 | 9         | 26         | IC2 Port 1  pin 1 |
 119 | 10        | 27         | IC2 Port 1  pin 2 |
 120 | 11        | 28         | IC2 Port 1  pin 3 |
 121 | 12        | 29         | IC2 Port 1  pin 4 |
 122 | 13        | 30         | IC2 Port 1  pin 5 |
 123 | 14        | 31         | IC2 Port 1  pin 6 |
 124
 125 - Safe enough to assume here col_index does not need to be converted to pin
 126 - Reading both ports one after the other gives us the same sequential behavior
 127   - maps to the usual practice of reading matrix columns
 128   - while this technically gives 16 column reads, the 16th column can never be set so is safely ignored
 129
 130 ## Notes
 131 [pca9555 datasheet](https://www.ti.com/lit/ds/symlink/pca9555.pdf)
 132
 133 - Other Kimera based boards with non sequential pin mappings, pins mapped across ICs, or mixed row/col configs will need more complicated `pin -> i2c_addr,port,pin` logic as well as rather more complex pin functions.
 134
 135 ## Return to stock firmware
 136 Not tested but original firmware seems to be available in the [kairyu/tkg-firmware](https://github.com/kairyu/tkg-firmware/blob/master/kimera-core.hex) repo.