Keymap iterator

Simple USB HID keycode remapper. Works as basic keyboard layout converter and runs on nanoCH32V203 or nanoCH32V305 RISC-V dual USB MCU boards.



Get riscv-none-elf-gcc-xpack toolchain, unpack it and temporarily add to PATH.

Clone kite repository:

git clone cd kite

Depending on target MCU checkout either ch32v203 or ch32v305 branch (or ch32rv305 one if the plan is to run kite in reverse mode):

git checkout ch32v305

RISC-V MCU boards

Compile firmware and configure layout (check Layouts folder for options):

make LAYOUT=jnsf

When dealing with multilingual layouts, specify language too:

make LAYOUT=skarp/nb


After building firmware you should get kite.bin file in build folder.

Flash it to MCU board. Connect PC to either USB1 or USB2 port using USB cable.

Muse Lab boards

Enter bootloader mode. Hold BOOT button, press and release RST button and then release BOOT button.

Then flash firmware, for example using wchisp tool:

wchisp flash ./build/kite.bin


Once firmware is flashed, connect keyboard to USB1 port and PC to USB2 port.


On Muse Lab boards USB type C ports are rather close to each other, leaving no space for type C to type A adapters.

Type C to type A female

When dealing with type A keyboard connectors use type C to type A female cable instead of adapter.

Reverse mode

One can compile kite to run in reverse mode (not applicable to CH32V203) with keyboard connected to USB2-HS port and PC connected to USB1-FS port.


To do that checkout ch32rv305 branch:

git checkout ch32rv305

Then compile and flash firmware.

Reverse mode is useful when dealing with keyboards that only work in high speed mode.

Evaluation board

One can run kite on one of WCH evaluation boards — CH32V203C8T6-EVT-R0 as it's based on the same CH32V203C8T6 MCU as nanoCH32V203 board.

While board is very similar to unsupported CH32F103C8T6 and CH32F203C8T6 ARM evalutions boards, those devices are not compatible, so don't flash RISC-V firmware to ARM boards or vise versa.

Board lacks BOOT button and to put board in bootloader mode one has to shorten pins as described below.

CH32V203C8T6-EVT-R0 boards

With BOOT1 grounded and BOOT0 connected to 3V3 pin one can connect USB device port (marked P6, next to power switch) to PC with type A to A cable, it enters bootloader mode. Then one can disconnect BOOT0 from 3V3 pin and flash firmware with wchisp tool.

Once firmware is flashed, connect PC to USB device port with P6 label (next to power switch) and keyboard to one of USB host/device ports with P7/P8 labels.

Note that board has type A device port (P6) that can be connected to PC using type A male to mail cable (not included).

Type A male to male cable

Keyboard shortcuts

By default keyboard shortcuts follow keymap, but it is possible to keep shortcuts intact by modifying KEYMAP_SUSPEND_MASK in kite.h


will keep shortcuts that involve modifiers other then Shift and AltGr intact and


will keep shortcuts that involve modifiers other then Shift intact.


Scroll lock

Scroll lock behavior is controlled by SCROLL_LOCK_OVERRIDE in kite.h


If defined it specifies keycode that should be sent instead of scroll lock and turns scroll lock into layout toggle and scroll lock LED into layout LED.


By default it's left undefined and scroll lock LED follows scroll lock state and is synchronized between keyboards like other lock LED indicators.

March 31, 2023. Giorgi Chavchanidze.