Creating a firmware for the Mysterium keyboard with OLED support (REVISITED)

November 2, 2024 Reading time: 2 minutes

After creating my own firmware for the Mysterium keyboard with OLED support I noticed that one key (< > |) did not work. Of course! I missed that he default keymap was for ANSI keyboards and my keyboards are ISO keyboards. šŸ¤¦

TheĀ https://github.com/vial-kb/vial-qmk repository does not contain an ISO keymap for the Mysterium. That's why I tried the https://github.com/piit79/qmk_firmware repository by 42Keebs. Unfortunately, it seems to be a little bit outdated. I was not able to compile the firmware without editing the code first and volume control had problems when I tested the keyboard with a Windows system (volume was unintentionally set to minimum or maximum).

That's why I decided to create a Frankenstein firmware by using the vial-qmk repo with a copy of the ISO keymap from the qmk branch by 42Keebs. My fork of vial-qmk can be found at https://github.com/marcnause/vial-qmk.

I made the following changes:

  • add OLED support (as described in previous blog article, see link in first paragraph)
  • change encoder resolution (volume would only be changed on every second step)
  • add ISO keymap from 42Keebs' qmk branch
  • change key code from KC_PAUS to KC_MUTE for the encoder to be able to mute voluem by pressing the encoder

Then I compiled the firmware with

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

and flashed it as described in Flashing the firmware of the Mysterium DIY keyboard.

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


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.

An error window with a "do not enter" traffic sign and the message "org/apache/commons/compress/archivers/zip/ZipArchiveInputStream"

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


Bludit posting to Mastodon

March 30, 2023 Reading time: 26 minutes

My blog can posts new content to my Mastodon account using the Bludit Mastodon Plugin now.