Creating a firmware for the Mysterium keyboard with OLED support

October 22, 2024 Reading time: 6 minutes

I have built two Mysterium keyboards from kits by 42Keebs. Building the keyboards was fun and I use them in the office and at home nearly every day. The only thing that bugged me was that the firmware I downloaded from the 42Keebs website did not display anything on the (optional) OLED of the keyboard.

I assumed that either nobody bothered or got around to utilizing the display yet or that the firmware was compiled without OLED support being configured.

Since I used the Vial version of the firmware, I cloned https://github.com/vial-kb/vial-qmk.

git clone git@github.com:vial-kb/vial-qmk.git

I use Debian and I had problems with QMK installed via pip. Using the QMK version provided via the Debian software repository worked much better for me.

sudo apt install qmk

QMK needs to be initialized before it can be used:

cd vial-qmk
qmk setup

The changed to the directory which contains the code for the Mysterium keyboard is located in:

cd keyboards/42keebs/mysterium/

The directory contains sub-directories with names which hint at revision 1.5c and 1.5d. My keyboards are revision 1.5e, but since there was no directory for this revision, I changed  checked the configuration in v15d:

cat v15d/rules.mk

To my surprise, OLED_ENABLE was set to "yes" already, but after I compiled and flashed the firmware, the OLED of my keyboard still did not display anything. Luckily I already had some experience in tinkering with QMK and I knew where to check.

cat v15d/v15d.c

I was surprised that the file contained code to turn the content of the OLED by 180 degree, but it did not contain the method which is required to display anything. I changed the file to:

/* Copyright 2019 coseyfannitutti
 *
 * 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/>.
 */
#include "v15d.h"

#ifdef OLED_ENABLE
oled_rotation_t oled_init_kb(oled_rotation_t rotation) {
    return OLED_ROTATION_180;
}

bool oled_task_user(void) {

  oled_write_ln_P(PSTR(" Mysterium  TKL "), true);

  // Host Keyboard LED Status
  led_t led_state = host_keyboard_led_state();
  oled_write_P(PSTR("Caps Lock:   "), false);
  oled_write_ln_P(led_state.caps_lock ? PSTR("On") : PSTR("Off"), false);
  oled_write_P(PSTR("Scroll Lock: "), false);
  oled_write_ln_P(led_state.scroll_lock ? PSTR("On") : PSTR("Off"), false);

  return false;
}
#endif

I tried to compile the firmware:

qmk compile -kb 42keebs/mysterium/v15d -km vial

Unfortunately, QMK informed me that the firmware image was too large and I did not find anything I could strip away. I guess this is the reason why the code for displaying anything in the OLED display is not contained in the repository.

Luckily this was not the end of the story. Vial is cool, but to be honest, I use a pretty standard configuration of my keyboard (ISO, German keys) and I can live without Vial support in the firmware.

That's why I tried compiling the firmware with:

qmk compile -kb 42keebs/mysterium/v15d -km default

The firmware image is located in the .build folder in the top directory of the cloned repository. After I flashed the firmware, the OLED is finally working and it even displays some useful information.

If you don't want to compile the firmware yourself, you can download my version (right-click and save as): 42keebs_mysterium_v15d_default.hex

update: If you have an ISO keyboard, please also read Creating a firmware for the Mysterium keyboard with OLED support (REVISITED)

Flashing the firmware of the Mysterium DIY keyboard

October 21, 2024 Reading time: 2 minutes

42Keebs provides firmware images for their DIY keyboard kits on their website.

The firmware of the Mysterium firmware can be flashed using avrdude:

1. Install avrdude:

   sudo apt install avrdude

2. Download hex file to install from https://42keebs.eu/firmware/
3. Connect the keyboard to the computer, hold boot button and press reset to enter boot mode.
4. Flash firmware with:

   sudo avrdude -p atmega32a -c usbasp -U flash:w:/path/to/42keebs_mysterium_v15d_vial.hex:i

Flashing the firmware of the Pocket Science Lab v6 board with mcbootflash

October 9, 2024 Reading time: ~1 minute

Updating the firmware of the PSLab v6 the way it is decribed on https://github.com/fossasia/pslab-firmware did not work for me. I used mcbootflash instead, which is installed as a dependency of the pslab Python library:

./mcbootflash --port /dev/serial/by-id/usb-Silicon_Labs_CP2102N_USB_to_UART_Bridge_Controller_5ecc207eeba8eb11828e98374232452f-if00-port0 -b 460800 ~/Downloads/pslab-firmware_v6.hex 

The ID is individual for each board.

Fix missing dependency for TuxGuitar under Debain

October 25, 2023 Reading time: ~1 minute

If TuxGuitar refuses to load GuitarPro files (.gp) with the error message "org/apache/commons/compress/archivers/zip/ZipArchiveInputStream", a dependency is is missing.

To install the missing dependency, execute the following command:

sudo apt install libcommons-compress-java

A bug report has been submitted already: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1043253

Restarting I2C when touchpad is not working

January 11, 2022 Reading time: ~1 minute

After I replaced the Clickpad of my Lenovo L440 with a touchpad (see https://mastodon.xyz/@nause_marc/107111989617471186) the Touchpad would not work occasionally under Debian when returning from suspend. I created a small script called restarti2c.sh with the following content:

sudo /sbin/rmmod i2c_i801 && sudo /sbin/modprobe i2c_i801

This restarts the I2C bus kernel module, which makes the touchpad work again. I run it whenever necessary.

Viewing the output of a C64 on a laptop via an STK1160 based video grabber

January 22, 2020 Reading time: 2 minutes

I bought a cheap (< €15) USB 2.0 video grabber which is based on the SyntekSTK1160 chipset. My goal was to display the output of my Commodore 64 on the screen of my laptop. The cable which connects the C64 with the video grabber allows me to use an s-video signal.

Read more