How to Flash Custom Firmware with Battery Level Indicator on Keychron Q0 Max Numpad

Required Programs

Git Bash/Command Line/Powershell

QMK MSYS

QMK Toolbox

Python 3

PIP

python.exe -m pip install --upgrade pip

Setup

  1. Open a Bash/Command Line/Powershell terminal
  2. Install qmk
py -m pip install qmk
  1. Open a QMK MSYS terminal
  2. Download the wireless_playground repository for keychron keyboards
qmk setup -b wireless_playground Keychron/qmk_firmware

Note: Refer to the Keychron firmware repository and choose a different branch if you can't find your keyboard

Note 2: This command will create the qmk_firmware repository in your C:/User/[Your Username] folder

Note 3: The "We do not recommend avr-gcc newer than 8. Downgrading to 8.x is recommended." warning can be ignored

Reasoning:
The avr-gcc compiler is exclusively used for older, 8-bit ATmega microcontrollers (like the ones found on older custom keyboards like the GH60 or older Ergodoxes).
Your Keychron Q0 Max runs on a highly modern, 32-bit ARM Cortex-M4 chip. Because of this, QMK completely bypasses avr-gcc and uses a totally different compiler called arm-none-eabi-gcc to build your firmware.  
Even if your avr-gcc version is brand new, it won't touch a single line of your code during compilation. 
QMK Doctor throws that flag simply because it checks all possible tools in the suite, regardless of which keyboard you actually own.
  1. Make sure the folder for your specific keyboard exists by navigating to it
cd qmk_firmware/keyboards/keychron/q0_max

Updating Firmware Code

Adding Battery Level Function

  1. Go to keymaps folder
cd q0_max/encoder/keymaps/via
  1. Create/edit config.h with the following code
/* Copyright 2024 @ Keychron (https://www.keychron.com)
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

#pragma once

// Lights up keys 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9 -> 0 to show remaining battery level
#define BAT_LEVEL_LED_LIST { 19, 20, 21, 15, 16, 17, 10, 11, 12, 24 }

Note: To change the order that keys light up refer to the "Key Matrix to LED Index" section in encoder.c

cd q0_max/encoder/encoder.c

Note 2: config.h also exists in q0_max/encoder. These are global/keyboard level configs. This file gets loaded first and the new config file will be appended on top of it.

  1. Save the file

Assigning Battery Level Function

  1. Go to keymaps folder for your desired mode
cd q0_max/encoder/keymaps/via
  1. Edit keymap.c
  2. Add BAT_LVL to desired key (usually Fn + B or MO(1) + 0)

Note: BAT_LVL is loaded in keychron_common.h

cd qmk_firmware/keyboards/keychron/common/keychron_common.h
  1. Save the file

Adding Battery Level Function to VIA Custom Keycodes

  1. Go to via_json folder
cd q0_max/via_json
  1. Edit q0_max_encoder.json
  2. Add the Battery Level option to the customKeycodes list
{"name": "Battery Level", "title": "Show battery level", "shortName": "Batt"}
  1. Save the file

Note: The Keychron Launcher web app caches default device profiles aggressively and uses its own hardcoded template, completely ignoring the new layout array item in your local file. Use the official VIA web app instead to view changes to the list of Custom Keycodes

Compiling Updated Firmware

  1. After your updates have been saved, navigate back to the base folder
cd ~/qmk_firmware
  1. Compile the firmware
qmk compile -kb keychron/q0_max/encoder -km via

Note: Compiling with the -km via option retains full freedom to remap your keys dynamically using the web-based Keychron Launcher or VIA anytime you want without re-compiling

  1. a BIN file will be generated in the base folder Ex) keychron_q0_max_encoder_via.bin

Note: the BIN file will be overwritten every time you run qmk compile

Flashing Generated Firmware

  1. Run qmk_toolbox.exe
  2. Load the generated BIN file
  3. Disconnect the keyboard you want to flash the firmware on
  4. Ensure the hardware switch on the back is on Cable mode
  5. Press and hold ESC for regular keyboards or O for numpads while connecting the USB cable to put the keyboard/numpad in DFU mode
  6. QMK Toolbox should say STM32 DFU device connected (WinUSB) in yellow
  7. Click the Flash button to flash the firmware
  8. Do not disconnect the keyboard/numpad until Flash complete appears in yellow or you risk bricking your keyboard/numpad
  9. Disconnect the USB cable and change the hardware switch on the back to G mode to test changes
  10. Your firmware should be flashed successfully