Overcoming limitations for macros on Keychron keyboards

The short version: It is possible to change the number of Via and Vial macros and change the space for them to be essentially unlimited. Unfortunately, there are many different ways of achieving it, depending on the particular keyboard, the particular source code version, and the particular firmware type, but this is an attempt to clear up the confusion.

The focus is on Keychron keyboards, but most applies to any Vial or QMK keyboard or macro pad.

Some history

I initially got a Keychron V5 and some time later posted comments on a Reddit post on how to expand the space for Via macros (after the OP repeatedly did not reveal any useful information on how to do it; instead the OP opted for the completely useless RTFM route. RTFM is completely useless and superfluous in general. And in this particular case, it isn’t actually in the very terse QMK documentation, at least not in any direct form; most has to be deduced from the source code)).

Later, I expanded it in a Reddit comment, as the original information was only valid for wired-only Keychron keyboards and only for QMK versions approximately 2023. For example, QMK changed to data-driven configuration for the space for Via macros in February 2024 (though the old method may still work; it probably overrides the data-driven configuration method). And Keychron’s fork of QMK, used for all the wireless Keychron keyboards, is many years behind the main QMK project and thus uses an old method.

I also wrote a blog post about how to overcome the lack of support of mouse actions in Via macros. It also lists the many limitations of Via macros.

How-tos

Unfortunately, there isn’t a single method. It has changed over time. For example, both the names and the set of the preprocessor symbols have changed over time. And now there is a move to data-driven configuration, but different versions and forks are in a different state. For example, it appears the data-driven configuration method is supported in Vial, but it doesn’t do anything…

The method to use depends on:

1. QMK/Via or Vial
2. The version of Via or Vial
3. Which fork of Via or Vial, if any
4. Which Git branch (mainly for the Keychron fork of QMK)

There are at least three different methods:

1. xxx
2. yyy
3. aaa

The meaning of the numbers has also changed:

1. For Keychron V6 with QMK as of 2023. The number is the actual space for Via macros
2. yyy
3. dd config: The number is the total space for emulated, not the actual space. There is an about 800 bytes overhead, which should be taken into consideration.

Space limits

It is possible to increase the space for Via macros, but what are the actual limits?

At first, it may appear as if the limit is set by the remaining flash memory (not taken up by the QMK keyboard firmware). For example,

xcxcx xc xc xc

But that is not the case. Looking closer, the emulated EEPROM is “backed” by RAM. And the size of this “backing” RAM must be at least double the size of the emulated EEPROM. Thus, if the RAM size is 64 KB, then the maximum size of the emulated EEPROM memory is 32 KB (not counting the overhead for other use of RAM).

Presumably, the “backing” RAM is for reducing the number of writes to flash memory (for example, only write to flash memory when some time has passed without write—the writes are sort of cached in RAM). And probably also for making it faster, at least for reading.

The compilation process may not give a warning if something risks being overwritten if setting the space specification too high.

Limiting factors

1. Size of the flash memory, in particular what is left over after the main QMK keyboard firmware has taken its share
2. Size of the RAM memory, in particular what is left over after the main QMK keyboard firmware has taken its share. As RAM memory is required for “backing” of the emulated EEPROM in flash memory
3. Inherent limits in QMK for the size of the EEPROM (whether physical or emulated)

Hardware extension

This hasn’t been explored, but it is possible to add extra hardware that can extended the EEPROM space. In particular, it doesn’t require “backing” in RAM, so the RAM size does not become a limiting factor