【Hanwen】HelloWord-Keyboard

# [Hanwen] HelloWord-Smart Keyboard ![hw1.jpg] > `Hanwen` Smart Keyboard is a **multifunctional** and **modular** mechanical keyboard that I designed for my own needs. > > The keyboard uses a modular design. The **multi-functional scene interaction module** on the left can be replaced with various custom components. The default one is a `Dynamic component` with an e-ink screen and FOC force feedback knob; the keyboard Use the keyboard firmware and module firmware based on the ARM Cortex-M chip that I developed myself; the keyboard body uses a shift register to implement an optimized key scanning circuit; the module and the keyboard body can be used alone, or they can communicate and call each other through the serial port protocol . > > **The open source information in this warehouse includes: ** > > > * 10 PCB design source files of Hanwen font hardware design, providing the file format of Lichuang EDA Professional Edition > * Shell design structure file > * Keyboard body Firmware source code (relatively complete) > * Firmware source code of Dynamic component (completed framework, more APP extensions WIP) > * Keyboard secondary development SDK (under development) > > > **Keyboard function demonstration can refer to: ** > > > * [[Homemade] I made a modular mechanical keyboard! [Softcore]\_bilibili\_bilibili](https://www.bilibili.com/video/BV19V4y1J7Hx) > > * [ I Made A Customized Modular Keyboard ! - YouTube](https://www.youtube.com/watch?v=mGShD9ZER1c) ## 1. Project Description### 1.1 Project File Description: #### 1.1.1 Hardware Hardware The folder contains the schematic diagrams and PCB files of all circuits used in Hanwen keyboard. Currently, the format provided is [EDA Professional Edition] (https://oshwhub.com/pengzhihui/helloword-smart-keyboard) Source files and light painting files in Gerber format are provided to manufacturers for direct processing. ![hw5.png] There are a total of the following boards: * **HelloWord-Keyboard**: PCB of the main keyboard, the controller is STM32F103, which can be used alone with the base, providing regular key input functions, with full-key independent RGB lights . * **HelloWord-Ctrl**: The PCB of the Dynamic component on the left, the controller is STM32F405, which can be used alone with the base to provide FOC force feedback knob, electronic ink screen display, OLED display, RGB light and other functions. * **HelloWord-Connector**: The main keyboard is used to connect to the contact PCB of the base, and is connected to the keyboard PCB through an FFC cable. * **HelloWord-Connector-Ctrl**: The Dynamic component is used to connect to the contact PCB of the base and is connected to the Dynamic component PCB through the FFC cable. * **HelloWord-Encoder**: Magnetic encoder PCB, used to provide position feedback to the brushless motor, needs to work with a radially magnetized permanent magnet. * **HelloWord-Hub1**: The two additional USB-A interfaces extended on the base are connected to the PCB and connected to the TypeC interface board through FFC cables. * **HelloWord-Hub2**: The female PCB of two additional USB-A interfaces extended from the base is reserved for USB3.0 female connectors and pins, but currently only the 2.0 interface is used and can be upgraded in the future. to USB3.0 HUB. * **HelloWord-TypeC**: The TypeC interface PCB on the base is used to connect to the computer. It has a power charging management chip and a USB-HUB chip onboard, and is connected to the other modules through FFC cables. * **HelloWord-OLED**: Minimum driver circuit and adapter board for OLED screens on Dynamic components. * **HelloWord-TouchBar**: The optional capacitive touch bar module PCB uses a 6-button capacitive touch chip to form a linear sensing array, and is connected to the main keyboard PCB through an FFC cable. #### 1.1.2 Firmware Firmware provides the firmware source code for all the above boards, and the **precompiled bin firmware** can be burned directly, mainly including the following two projects: * **HelloWord-Keyboard-fw **: The main keyboard's firmware mainly implements high-speed key scanning based on hardware SPI and shift register, bus-based RGB light control based on hardware SPI&DMA, HID high-speed device keyboard enumeration & message protocol implementation, and non-volatile storage configuration , multi-layer key mapping and other functions. * **HelloWord-Dynamic-fw: **Dynamic component firmware, which mainly implements FOC-based motor control code, configurable touch package class, e-ink screen driver, OLED driver, USB full-speed composite device enumeration and communication protocol, RGB light control and other functions. The projects are all implemented based on STM32HAL, so the corresponding `.ioc` file is provided, which can be opened with STM32CubeMX to generate the corresponding keil or STM32IDE project file. Dangrang can also use CLion or STM32CubeIDE to compile and download like me. The `_Release` folder contains precompiled bin files, which can be directly downloaded to the chip using software such as **ST-Link Utility** or STM32CubeProgrammer. The implementation details of the firmware will be explained later. > For the method of turning CLion into an STM32 IDE, please refer to a tutorial I posted before: [Configuring CLion for STM32 development [Elegant Embedded Development]] (https://zhuanlan.zhihu.com/p/145801160). #### 1.1.3 Software Software provides some computer-side host software for interacting with the keyboard, including the fool-proof host computer software for modifying ink screen images demonstrated in the video, and will be gradually added later for** Graphical software for modifying key positions and adding APP** application store software to the ** module are still under development. #### 1.1.4 Tools Tools mainly provides some third-party tool software, such as **STM32 ST-LINK Utility**, **zadig** for driver installation, etc. #### 1.1.5 The 3D Model folder contains 3D model files of all structural parts used in the keyboard, which can be used for 3D printing. #### 1.1.6 Docs Related reference documents, including chip Datasheet, etc. ## 2. Hardware architecture description** About structural design? ** The structure of Hanwen consists of three parts: **docking base**, **keyboard input module** and **replaceable multi-functional interactive module**, keyboard input module and replaceable multi-functional interactive module It is connected to the top of the docking station base through a number of contact contacts: ![hw2.jpg] The keyboard body is also a standard customized keyboard laminated structure design, including shock-absorbing cotton, PCBA, positioning plate, under-axis pad, etc. : ![hw3.jpg] The structural design of the keyboard is mainly modified by Xikii based on the S98. It has a 75-key layout. Students who need other layouts can modify the PCB and firmware adaptation by themselves. > Regarding the structural parts shown in the video, since it is Xikii's solution, I cannot release the source files without authorization. Moreover, the original version of the structure is for CNC machining, so the cost will be relatively high. > > So I also asked Xikii to help design a simplified version of the structural parts that can be used in 3D, and open sourced it and put it in the warehouse. **About chip selection? ** * The chip used for the keyboard main control is STM32F103CBT6. In fact, C8T6 can also be used. However, considering the scalability of future firmware functions, CBT6 with twice the size of Flash is more cost-effective. Since my firmware is basically implemented using the HAL library, the main control can actually be replaced with any chip in the STM32 series. The chip needs to have two SPI hardware interfaces for button scanning and RGB light driving. , and a full-speed USB interface. * The STM32F4 controlled by the Dynamic component. This is because I have more of this chip on hand. In theory, it can be replaced by the more cost-effective F1 series, as long as the chip has an advanced timer for PWM generation and 2 hardware SPI interfaces for The encoder communicates with the e-ink screen, an I2C interface for OLED driver, and a full-speed USB interface. * I use AS5047P as the magnetic encoder chip of the motor. It is also a very commonly used magnetic encoding chip with good performance, but the cost is slightly higher. I just chose this one because I had it on hand. It can also be modified to other cheaper models. For example, MT6816, etc., of course the firmware driver code also needs to be modified. * The shift register used for key scanning uses 74HC165. Domestic chips retail for about 0.5 yuan each. One chip can drive 8 keys. Just modify the series register chip according to the number of keys you need. Imported 165, such as the original TI chip, is more expensive than the domestic one, and the performance will be slightly better. However, since the key scanning frequency of 4MHz is completely sufficient in this project, even the domestic 16MHz chip is more than enough. * The capacitive touch panel is implemented using a 6-channel capacitive touch button chip XW06A. This has certain requirements for the design of the PCB induction disk. The warehouse has provided the designed PCB. The reading method of the chip is actually no different from ordinary buttons, so 74HC165 is also used for scanning and reading in this solution. * The motor FOC driver circuit is completely transplanted from my Ctrl driver, using FD8288Q as the gate driver without current sensor. **About the burning method? ** For programming using debuggers such as JLink and STLink, I have reserved SWD debugging ports on both the PCB and the casing. For students who have no hardware development experience, I will also release a Bootloader later, which can directly upgrade the firmware through the USB port. **About motor selection? ** I am using a 2204 second-hand motor, but this motor seems to be not easy to buy at the moment. You can choose a brushless motor of similar size to replace it. In terms of parameters, the KV value needs to be lower, preferably around 200. The motor needs to manually install a radially magnetized permanent magnet on the rotor for encoder positioning. Different models of motors require some adjustments to the FOC parameters. ![hw4.jpg] ## 3. Software architecture description** About the key mapping method of keyboard firmware? ** In order to take full advantage of the shift register scanning scheme mentioned in the video, the PCB Layout and key scanning sequence are decoupled in the firmware code and remapped through software. In other words, the connection of the keys in the PCB can be arbitrary. After the wiring is completed, the mapping method can be specified in `keyMap[KEYMAP_NUM][IO_NUMBER]` in the `hw_keyboard.h` file. > This is a two-dimensional array, representing the `KEYMAP_NUM` layer key mapping. Each layer has `IO_NUMBER` keys (that is, the number of your keyboard keys); layer 0 is special and is responsible for mapping PCB keys. Randomly layout to the standard key layout of the keyboard. The subsequent 1, 2, 3, 4... layers are all customized and are responsible for mapping the standard key layout to any layout. **For example:** Consider the button pointed by the arrow in the schematic diagram. This button can be anywhere on the PCB, but we can see that it is from left to right (according to the connection sequence of 74HC165, that is, shifting Scanning order), so its number is 9 (counting from 0). ![hw5.jpg] If we place it on the **right Alt** position on the actual PCB board, then Refer to the **red box** in the code below. The serial number of `RIGHT_ALT` in the first layer mapping (that is, the standard layout) is 76, then the variable number 76 in the 0th layer mapping is filled in with 9 (blue box ). In this way, fill in all the keys on your PCB with layer 0 mapping, and you will get a mapped standard keyboard. Subsequent layers 2, 3, 4, 5... can be modified and added as desired according to the mapping required. There is no need to use numerical numbers. Instead, it is convenient to directly use the enumerated button names. > So for those who want to modify the keyboard layout, they only need to add or delete a few 74HC165s in series on the schematic diagram, then route the PCB as desired, and then delete or add some numbers to the layer 0 mapping in the code (for example, in In the example below, my keyboard has 83 keys); the modifications in the following layers can be deduced in this way. In the code, different layers are mapped through the `keyboard.Remap` function. For example, the sentence `keyboard.Remap(2)` uses layer 2 mapping. ![hw6.jpg] **About the filtering method of keyboard firmware? ** The firmware uses independent filtering for each button, but it is implemented in a very efficient way (after all, for 1KHz messages, the buttons are scanned at least twice during each message, which means that every second **1000*2*[number of keys]** times of filtering). The basic principle is very simple. The reason why the button jitters is that it will jump repeatedly between high and low levels after being pressed. This stabilization time is generally tens of us (note that it is the level stabilization time, not the button triggering time. The latter is due to Caused by the uncertainty of the key reed contact time, which may be as long as several ms). Several filtering methods used are described in QMK's [qmk\_firmware/feature\_debounce\_type](https://github.com/qmk/qmk_firmware/blob/master/docs/feature_debounce_type.md) document. For Eager and Defer, symmetry and asymmetry, etc., the default is to use **symmetric delay global filter**, which means that all keys are filtered equally, and the scan data is submitted after all keys are stable and no longer change. . > Corresponding to this is the radical filtering method, which means that once a key change is detected, the data will be submitted, but no key will be responded to for N milliseconds thereafter (this avoids submitting the constantly shaking keys). This method has low triggering delay, but is very sensitive to noise and prone to false triggering. What I use in Hanwen's firmware is **Symmetric Delay Independent Filtering**, that is, each button is detected twice. If a button change is detected for the first time, the interval is N microseconds (this parameter can be configured, greater than the typical jitter time of the key) and then detect it again. If the two detection results are consistent, then it is judged that the key has been pressed. At this time, it can be ensured that the key has changed and the key will not be triggered repeatedly, taking into account delay and stability. ![hw7.jpg] **What about HID descriptors for keyboard firmware? ** This can directly refer to the `usbd_customhid.c` file of the source code. I configured two ReportIDs. ID-0 is for reporting key scan data (full key without collision), and ID-1 is reserved for subsequent follow-up. It is used for machine modification key software communication. **About RGB control? ** The code uses a single-bus ws2812b series lamp bead, which can connect a large number of RGBs in series with one wire. The code implements SPI-DMA simulation timing and achieves an ultra-high refresh rate. Currently, only one demo light effect is written in the code (very simple, it is polling for color). If you want to add additional light effects yourself, set the RGB value through the `keyboard.SetRgbBuffer` function, and then send the data to the LED with `SyncLights`: ## 4. SDK design & secondary development to be added.