Other languages: English, 简体中文

Table of Contents

• Table of Contents
• Overview
• Directory Structure
• Code Branches
• Highlights
• Supported hardware
• Building
  • Keyboard manufacturers/QMK firmware users
  • Developers
• Flashing
• Community

Overview

This is a porting of QMK keyboard firmware for CH58x series, with the main focus on bridging the application layer (QMK) and the underlying hardware.

Directory Structure

• CherryUSB, qmk_firmware, mcuboot: Components introduced as submodules, NO any file is modified.

  The qmk_firmware submodule should be able to keep up with upstream.

• CherryUSB_porting, mcuboot_porting: Files used to configure submodules and add them into the building system.

• qmk_porting: The adapter layer for QMK to running on the CH58x chip.

• sdk: Directory for placing WCH SDK.

Code Branches

• via: All the basic functions needed by wired keyboards are done, including VIA support. For lights, WS2812 (both SPI and PWM driven) and AW20216S (SPI driven) are supported currently.
• debug: Used for presenting specific issues, ignore if use of QMK is all you want.

Highlights

• Support wired, Bluetooth, and triple mode 2.4G (WIP).
• Capability to update along with the QMK repo, and supports most of the features of QMK.
• Low power comsumption in wireless modes.

Supported hardware

Currently only CH582M is tested, but it should also work for CH582F.

Building

• A WCH-specified toolchain is provided in this repo, if you want to use the public version, you may find it here. Note that you need to add it to your PATH environment variable manually.
• A global defination INT_SOFT is needed or the ISR handlers might not working properly.

Keyboard manufacturers/QMK firmware users

Fork this repository then manually upload you keyboard configuration file to keyboards. You'll be able to use the GitHub Actions to build your firmware online.

Note that currently the configuration file is slightly different from the original QMK ones, you may take this keyboard as a start point.

Developers

Visual Studio Code is recommended.

You can follow this guide to set up a development environment locally. Or you can also use Codespace instead.

Or follow these steps below to build it on your system:

1. Install compiler and nrf command line tools:

   Download and configure the compiler provided by WCH, and the nrf command line tools.

   • For deb-based Linux distributions users (Debian GNU/Linux, Ubuntu, or Ubuntu on WSL2):

     The following commands will download them from their official websites and extract the files to the $HOME/.local/opt directory.

     $ wget http://file.mounriver.com/tools/MRS_Toolchain_Linux_X64_V170.tar.xz
     $ wget https://nsscprodmedia.blob.core.windows.net/prod/software-and-other-downloads/desktop-software/nrf-command-line-tools/sw/versions-10-x-x/10-21-0/nrf-command-line-tools-10.21.0_linux-amd64.tar.gz
     $ mkdir -p $HOME/.local/opt
     $ tar xvf MRS_Toolchain_Linux_X64_V170.tar.xz -C $HOME/.local/opt
     $ tar xvf nrf-command-line-tools-10.21.0_linux-amd64.tar.gz -C $HOME/.local/opt

     Next, add these programs to your $PATH. For bash users, this can typically be accomplished by:

     $ echo 'export PATH=$HOME/.local/opt/MRS_Toolchain_Linux_x64_V1.70/RISC-V\ Embedded\ GCC/bin/:$HOME/.local/opt/nrf-command-line-tools/bin/:$PATH' >> $HOME/.bashrc
     $ source $HOME/.bashrc

   • For macOS users:

     Download and install the nrf command line tools from here. And use the following commands to download and configure the compiler:

     $ curl -O http://file.mounriver.com/tools/MRS_Toolchain_MAC_V180.zip
     $ unzip MRS_Toolchain_MAC_V180.zip -d $HOME/.local/opt
     $ unzip $HOME/.local/opt/MRS_Toolchain_MAC_V180/xpack-riscv-none-embed-gcc-8.2.0.zip -d $HOME/.local/opt

     Next, add these programs to your $PATH. For bash users, this can typically be accomplished by:

     $ echo 'export PATH=$HOME/.local/opt/xpack-riscv-none-embed-gcc-8.2.0/bin/:$PATH' >> $HOME/.bashrc
     $ source $HOME/.bashrc

2. Install some other dependencies:

   • For deb-based Linux distributions users:

     $ sudo apt update
     $ sudo apt install git cmake ccache python3 python3-click python3-cbor2 python3-intelhex

   • For macOS users, assuming XCode is installed here:

     $ pip3 install --user cryptography click cbor2 intelhex

3. Clone this repository by:

$ git clone https://github.com/O-H-M2/qmk_port_ch582.git
$ cd qmk_port_ch582
$ git -c submodule."qmk_porting/keyboards_private".update=none submodule update --recursive --init

4. Create a directory for the building:

$ mkdir build
$ cd build

5. Running cmake for dependencies checking and generating Makefile:

$ cmake -Dkeyboard=m2wired -Dkeymap=default ..

You may replace m2wired and default in the above command with the names of your own keyboard and keymap.

6. Build:

$ make -j$(nproc)

.uf2 and .hex will be generated in the top directory of the project if the build succeeds.

Flashing

For end users: Use Bootmagic Lite with .uf2 only, or take your own risk of bricking your keyboard.

For developers: You may use the flashing utility which is provided by WCH.

Community

• QQ group: 860356332
• Discord