libhmk

This repository contains libraries for building a Hall-effect keyboard firmware.

Table of Contents

• Features
• Limitations
• Getting Started
• Porting
• Acknowledgements

Features

• Analog Input: Customizable actuation point for each key and many other features.
• Rapid Trigger: Register a key press or release based on the change in key position and the direction of that change
• Continuous Rapid Trigger: Deactivate Rapid Trigger only when the key is fully released.
• Null Bind (SOCD + Rappy Snappy): Monitor 2 keys and select which one is active based on the chosen behavior.
• Dynamic Keystroke: Assign up to 4 keycodes to a single key. Each keycode can be assigned up to 4 actions for 4 different parts of the keystroke.
• Tap-Hold: Send a different keycode depending on whether the key is tapped or held.
• Toggle: Toggle between key press and key release. Hold the key for normal behavior.
• N-Key Rollover: Support for N-Key Rollover and automatically fall back to 6-Key Rollover in BIOS.
• Automatic Calibration: Automatically calibrate the analog input without requiring user intervention.
• EEPROM Emulation: No external EEPROM required. Emulate EEPROM using the internal flash memory.
• Web Configurator: Configure the firmware using hmkconf without needing to recompile the firmware.
• Bootloader: Optional UF2 bootloader for firmware updates over USB.
• Gamepad: Support for gamepad functionality.
• Tick Rate: Customizable tick rate for Tap-Hold and Dynamic Keystroke.

Limitations

• Polling Rate: The firmware is designed to run at 1 kHz polling rate.
• RGB Lighting: The firmware does not support RGB lighting.

Getting Started

Prerequisites

• PlatformIO
• Python 3 (Optional, for generating the distance lookup table)

Building the Firmware

1. Clone the repository:

git clone https://github.com/peppapighs/libhmk.git

2. Open the project in PlatformIO, for example, through Visual Studio Code.

3. Create a directory for your keyboard under src/keyboards/ and create a config.h file with the required configurations. An example keyboards/gauss64/config.h is provided. See the header files in include/ and hardware/ for the available options.

4. Configure the platformio.ini file for your keyboard. The configuration file includes the following sections:

   • env: Shared configuration for all environments. The following options are configurable:
     • debug_tool (Optional): See Debugging.
     • upload_protocol (Optional): See Upload.
   • env:<YOUR_ENVIRONMENT_NAME>: Configuration specific to your keyboard. An example env:gauss64 is provided. The following options are configurable:
     • board: The microcontroller used by your keyboard. See Platform.
     • board_build.f_cpu (Optional): The clock frequency of the microcontroller if it is not the default value. See Platform.
     • build_flags: Flags passed to the compiler. Include the path to the hardware-specific header files and the configuration file for your keyboard that you created in the previous step. See Build.
     • build_src_filter: Filter for the source files. Include the path to the hardware-specific source files. See Build.
     • framework: Framework used by the implementation of the hardware-specific code. See Platform.
     • platform: Platform used by the implementation of the hardware-specific code. See Platform.

5. (Optional) Since the relationship between the ADC value and the key travel distance is non-linear, a lookup table is used to assist the conversion between the two. The table can be found in include/distance.h. The table distance_table is generated by running the Python script distance_lut.py. To adjust the table for your keyboard, you should sample the ADC values at various key travel distances, and add the samples to this Desmos graph. The samples can be obtained from the Debug tab of hmkconf. You are minimally required to add the samples for a fully released key, and a fully pressed key. Fit the curve to obtain the coefficient a, which is required to run the script. The script will generate the table for you to replace the existing one.

6. Build the firmware using PlatformIO.

7. Flash the firmware to your keyboard through PlatformIO, the bootloader of your keyboard, or any other method.

8. Configure the keyboard using hmkconf.

Porting

See hardware/stm32f446xx and src/hardware/stm32f446xx for an example implementation of the hardware-specific code for the STM32F446xx microcontroller.

Acknowledgements

• hathach/tinyusb for the USB stack.
• qmk/qmk_firmware for inspiration, including EEPROM emulation and matrix scanning.
• @riskable for pioneering custom Hall-effect keyboard firmware development.
• @heiso for his macrolev and his helpfulness throughout the development process.
• Wooting for pioneering Hall-effect gaming keyboards and introducing many advanced features based on analog input.
• GEONWORKS for the Venom 60HE PCB and inspiring the web configurator.