ZHEK (Work in Progress)

Z-axis Hall-Effect Keyboard firmware

• APM32 HAL

  • CherryUSB Migrate
    • DW2
    • HS
  • ADC DMA Based Scan
  • UART (LOG / DEBUG)
  • FatFS (internal flash or RAM based)
  • WS2812

• Bootloader

  • Press ESC, and then Plug in USB to enter bootloader mode

• USB

  • Composed descriptor
    • HID
    • CDC
    • MSC

• HE

  • Filter
  • Calibration
  • Rapid Trigger
  • Dynamic Keystroke (DKS)
  • Simultaneous Opposing Cardinal Directions (SOCD)

• Keyboard

  • Mod-Tap

• WebTool

  • WebHID
  • WebUSB

To update the submodules, run the following command:

git submodule update --init --recursive

The MAD60 HE firmware has three build targets:

The APP contains BLIMG, a compiled copy of BL. On startup it compares the installed Bootloader region with the embedded image. If they differ, it updates and verifies the Bootloader, posts an Application-start event, and resets. The Bootloader mailbox retains the lifecycle state across warm resets: a cold start defaults to the App, while a reset from APP_STARTING or APP_RUNNING falls back to the Bootloader. Explicit App/Bootloader events and the physical ESC recovery entry override that default state transition once.

Use zhekdev.sh from Git Bash to manage the build targets:

./tools/zhekdev.sh build
./tools/zhekdev.sh build --refresh-bl
./tools/zhekdev.sh rebuild
./tools/zhekdev.sh pack
./tools/zhekdev.sh load-appdbg
./tools/zhekdev.sh load-allinone

build and rebuild always compile BL, APP and APPDBG, then generate the UF2. By default they keep the existing src/app/mad60he/zhek/zhek_blimg.c, so an ordinary build cannot silently change the Bootloader embedded in the App. Pass --refresh-bl when a new Bootloader is intentionally ready to ship; the freshly built zhek-bl.hex is then embedded before the App targets are compiled. The flag is also accepted by load-appdbg and load-allinone, before their normal build-and-flash flow.

The internal refresh step delegates to the Fire/IntelHex-based tools/zhekdev.py; other Python tools can import its load_bootloader_image, render_blimg_source, and refresh_blimg APIs directly. Python dependencies are pinned in tools/requirements-freeze.txt. Use pack to regenerate the UF2 from an existing APP HEX without compiling.

load-appdbg performs a chip erase and installs APPDBG. load-allinone performs a chip erase and installs both BL at 0x08000000 and APP at 0x08020000; use it for initial installation. Subsequent APP updates can use the generated UF2 file.

Check the available targets and packs with the following command:

 pyocd list -t -s pack --pack tools/Geehy.APM32F4xx_DFP.1.0.12.pack

Check if the pack is detected:

pyocd list --targets

To flash the firmware, run the following command:

pyocd load -t apm32f407vg -f 10m -e chip prj/mad60he/zhek/MAD60HE_APPDBG/Exe/zhek-appdbg.hex