From v0.6 to v0.7#

RMK v0.7 is a major update that includes many changes. One notable change is that RMK switched the BLE stack to TrouBLE, a great BLE host implementation with async support and better compatibility.

Updating to TrouBLE brings lots of benefits, including:

• More microcontrollers are supported, such as CYW43 (used on Pi Pico W)
• We don't need to maintain different BLE stacks for different microcontrollers. This makes BLE split keyboards automatically supported for ESP32 and Pi Pico W
• For ESP32, RMK migrates to Espressif's official esp-hal, making it possible to use USB on ESP32S3. Now you can build a dual-mode keyboard using ESP32S3, with all the features of RMK!
• You can even build a split keyboard using different microcontrollers; for example, use ESP32 as a dongle and use nRF52 as the peripherals

The following is the step-by-step guide to update your project to v0.7.

1. Update rmkit#

cargo install rmkit --force

2. Update Cargo Dependencies#

Many dependencies are updated from v0.6 to v0.7.

The best updating approach is to copy the new Cargo.toml file from the examples to replace the old one, delete the old Cargo.lock file, adjust the RMK features used, and then rebuild the project using:

cargo update
cargo build --release

3. Add the Path of keyboard.toml to .cargo/config.toml#

In v0.7, RMK requires you to set the path of keyboard.toml in .cargo/config.toml. This makes the path of keyboard.toml configurable.

In versions before v0.7, keyboard.toml was located in the root directory of the project. So you will need to add the following to .cargo/config.toml after updating to v0.7:

[env]
KEYBOARD_TOML_PATH =  { value = "keyboard.toml", relative = true }

4. Platform-Specific Changes#

nRF BLE Stack Migration#

For nRF chips, RMK now uses Nordic's latest SoftDevice Controller (SDC) in nrfxlib as the low-level BLE controller, bringing better performance and stability, but it's not compatible with the old SoftDevice stack.

For more details about the difference between SoftDevice Controller and the old SoftDevice, you can refer to this article.

The migration process is simple; you just need to:

1. Update the RMK version in Cargo.toml

2. Update your memory.x according to whether you are using the uf2 bootloader or not

   // These values correspond to the nRF52840 WITH Adafruit nRF52 bootloader
   MEMORY
   {
   -  FLASH : ORIGIN = 0x00027000, LENGTH = 820K
   -  RAM : ORIGIN = 0x20020000, LENGTH = 128K
   +  FLASH : ORIGIN = 0x00001000, LENGTH = 1020K
   +  RAM : ORIGIN = 0x20000008, LENGTH = 255K
   }

   // These values correspond to the nRF52840 WITHOUT Adafruit nRF52 bootloader
   MEMORY
   {
   -  FLASH : ORIGIN = 0x00027000, LENGTH = 820K
   -  RAM : ORIGIN = 0x20020000, LENGTH = 128K
   +  FLASH : ORIGIN = 0x00000000, LENGTH = 1024K
   +  RAM : ORIGIN = 0x20000000, LENGTH = 256K
   }

3. Compile your firmware and flash it to your controller

ESP32 BLE Stack Migration#

Older versions of RMK use esp-idf-hal, which is now community-maintained. RMK v0.7 now uses Espressif's official esp-hal. Because the difference between esp-hal and esp-idf-hal is significant, the recommended way to migrate to v0.7 is to recreate your project from scratch and migrate your keymap and configuration to the new project.

5. Check Out New Features#

RMK v0.7 brings many exciting features, making configuration easier and more flexible. Check out the CHANGELOG for more details.

Troubleshooting#

1. BLE peripheral doesn't work

   In the new version, RMK uses the nRF chip's unique address as the device address. If the BLE peripheral doesn't work after updating, it's likely that the old fixed device address is stored in the chip. You should clear the storage for both central and peripheral:

   1. Set clear_storage to true for both peripheral & central
   2. Flash both central & peripheral firmware
   3. Set clear_storage back to false and compile
   4. Flash both splits again

Known Issues#

1. The dongle setting and multiple peripherals are not working