Last time, I showed you how to throw together a few modules and make a working macropad that could act like a keyboard or a mouse. My prototype was very simple, so there wasn’t much to debug. But what happens if you want to do something more complex? In this installment, I’ll show you how to add the obligatory blinking LED and, just to make it interesting, a custom macro key.

There is a way to print data from the keyboard, through the USB port, and into a program that knows how to listen for it. There are a few choices, but the qmk software can do it if you run it with the console argument.

The Plan

In theory, it is fairly easy to just add the console feature to the keyboard.json file:
{
...
"features": {
"mousekey": true,
"extrakey": true,
"nkro": false,
"bootmagic": false,
"console": true
},
...

That allows the console to attach, but now you have to print.

Output

The code in a keyboard might be tight, depending on the processor and what else it is doing. So a full-blown printf is a bit prohibitive. However, the system provides you with four output calls: uprint,uprintf, dprint, and dprintf.

The “u” calls will always output something. The difference is that the normal print version takes a fixed string while the printf version allows some printf-style formatting. The “d” calls are the same, but they only work if you have debugging turned on. You can turn on debugging at compile time, or you can trigger it with, for example, a special key press.

To view the print output, just run:
qmk console
Note that printing during initialization may not always be visible. You can store things in static variables and print them later, if that helps.

Macros

You can define your own keycodes in keymap.c. You simply have to start them at SAFE_RANGE:
enum custom_keycodes {
SS_STRING = SAFE_RANGE
};

You can then “catch” those keys in a process_record_user function, as you’ll see shortly. What you do is up to you. For example, you could play a sound, turn on some I/O, or anything else you want. You do need to make a return value to tell qmk you handled the key.

An Example

In the same Git repo, I created a branch rp2040_led. My goal was to simply flash the onboard LED annoyingly. However, I also wanted to print some things over the console.

Turning on the console is simple enough. I also added a #define for USER_LED at the end of config.h (GP25 is the onboard LED).

A quick read of the documentation will tell you the calls you can use to manipulate GPIO. In this case, we only needed gpio_set_pin_output and the gpio_write_pin* functions.

I also sprinkled a few print functions in. In general, you provide override functions in your code for things you want to do. In this case, I set up the LED in keyboard_post_init_user. Then, at first, I use a timer and the user part of the matrix scan to periodically execute.

Notice that even though the keyboard doesn’t use scanning, the firmware still “scans” it, and so your hook gets a call periodically. Since I’m not really using scanning, this works, but if you were trying to do this with a real matrix keyboard, it would be smarter to use housekeeping_task_user(void) which avoids interfering with the scan timing, so I changed to that.

Here’s most of the code in keymap.c:
#include QMK_KEYBOARD_H
enum custom_keycodes {
SS_STRING = SAFE_RANGE
};
const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
[0] = LAYOUT(
// 4 buttons
KC_KB_VOLUME_UP, KC_KB_MUTE, KC_KB_VOLUME_DOWN, SS_STRING,
// Mouse
QK_MOUSE_CURSOR_UP, QK_MOUSE_CURSOR_DOWN, QK_MOUSE_CURSOR_LEFT, QK_MOUSE_CURSOR_RIGHT, QK_MOUSE_BUTTON_1),
};

void keyboard_pre_init_user(void) {
// code that runs very early in the keyboard initialization
}

void keyboard_post_init_user(void) {
// code that runs after the keyboard has been initialized
gpio_set_pin_output(USER_LED);
gpio_write_pin_high(USER_LED);
uprint("init\n");
}

#if 1 // in case you want to turn off that $<em>$</em># blinking
void housekeeping_task_user(void) {
static uint32_t last;
static bool on;
uint32_t now = timer_read32();
uprintf("scan tick %lu\n",now);
if (TIMER_DIFF_32(now, last) > 500) { // toggle every 500 ms
last = now;
on = !on;
if (on)
gpio_write_pin_high(USER_LED);
else
gpio_write_pin_low(USER_LED);
}
}
#endif

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
switch (keycode) {
case SS_STRING:
if (record->event.pressed) {
SEND_STRING("http://www.hackaday.com\n");
}
return false;
}
return true;
}

You’ll notice the process_record_user function is now in there. It sees every keycode an when it finds the custom keycode, it sends out your favorite website’s URL.

More Tips

I mentioned last time that you have to let the CPU finish loading even after the flash utility says you are done. There are some other tips that can help you track down problems. For one thing, the compile script is pretty lax about your json. So you may have an error in your json file that is stopping things from working, but it won’t warn you. You can use jq to validate your json:
jq . keyboard.json
Another thing to do is use the “lint” feature of qmx. Just replace the compile or flash command with lint, and it will do some basic checks to see if there are any errors. It does require a few arbitrary things like a license header in some files, but for the most part, it catches real errors.

Get Started!

What are you waiting for? Now you can build that monster keyboard you’ve dreamed up. Or the tiny one. Whatever. You might want to read more about the RP2040 support, unless you are going to use a different CPU. Don’t forget the entire directory is full of example keyboards you can — ahem — borrow from.

You might think there’s not much you can do with a keyboard, but there are many strange and wonderful features in the firmware. You can let your keyboard autocorrect your common misspellings, for example. Or interpret keys differently when you hold them versus tapping them. Want a key that inserts the current time and date? Code it. If you want an example of getting the LCD to work, check out the rp2040-disp branch.

One thing interesting about qmk, too, is that many commercial keyboards use it or, at least, claim to use it. After all, it is tempting to have the firmware ready to go. However, sometimes you get a new keyboard and the vendor hasn’t released the source code yet, so if that’s your plan, you should find the source code before you plunk down your money!

You’ll find plenty of support for lighting, of course. But there are also strange key combinations, layers, and even methods for doing stenography. There’s only one problem. Once you start using qmk there is a real chance you may start tearing up your existing keyboards. You have been warned.

hackaday.com/2025/08/25/debugg…

I did something recently I haven’t done in a long time: I recompiled the Linux kernel. There was a time when this was a common occurrence. You might want a feature that the default kernel didn’t support, or you might have an odd piece of hardware. But these days, in almost all the cases where you need something like this, you’ll use loadable kernel modules (LKM) instead. These are modules that the kernel can load and unload at run time, which means you can add that new device or strange file system without having to rebuild or even restart the kernel.

Normally, when you write programs for Linux, they don’t have any special permissions. You typically can’t do direct port I/O, for example, or arbitrarily access memory. The kernel, however, including modules, has no such restriction. That can make debugging modules tricky because you can easily bring the system to its knees. If possible, you might think about developing on a virtual machine until you have what you want. That way, an errant module just brings down your virtual machine.

History

Some form of module support has been around since Linux 1.2. However, modern kernels can be built to include support for things or support them as modules. For example, you probably don’t want to put drivers for every single known video card in your kernel. But it is perfectly fine to build dozens or hundreds of modules you might need and then load the one you need at run time.

LKMs are at the heart of device drivers, file system drivers, and network drivers. In addition, modules can add new system calls, override existing system calls, add TTY line disciplines, and handle how executables run.

In Use

If you want to know what modules you have loaded, that’s the lsmod command. You’ll see that some modules depend on other modules and some don’t. There are two ways to load modules: insmod and modprobe. The insmod command simply tries to load a module. The modprobe command tries to determine if the module it is loading needs other modules and picks them up from a known location.

You can also remove modules with rmmod assuming they aren’t in use. Of course, adding and removing modules requires root access. You can usually run lsmod as a normal user if you like. You might also be interested in depmod to determine dependencies, and modinfo which shows information about modules.

Writing a Module

It is actually quite easy to write your own module. In fact, it is so simple that the first example I want to look at is a little more complex than necessary.

This simple module can load and unload. It leaves a message in the system messages (use dmesg, for example) to tell you it is there. In addition, it allows you to specify a key (just an arbitrary integer) when you load it. That number will show up in the output data. Here’s the code:
#include <linux/module.h>
#include <linux/moduleparam.h>
#include <linux/printk.h>

MODULE_AUTHOR("Al Williams");
MODULE_DESCRIPTION("Hackaday LKM");
MODULE_LICENSE("GPLv2"); // many options, GPL, GPLv2, Proprietary, etc.

static int somedata __initdata=0xbeef; // this is just some static variable available only at init
static int key=0xAA; // you can override this using insmod
// Note 0644 means that the sysfs entry will be rw-r--r--
module_param(key,int,0644); // use module_param_named if you want different names internal vs external
MODULE_PARM_DESC(key,"An integer ID unique to this module");

static int __init had_init(void)
{
// This is the usual way to do this (don't forget \n and note no comma after KERN_INFO), but...
printk(KERN_INFO "Hackaday is in control (%x %x)\n",key,somedata);
return 0;
}

static void __exit had_exit(void)
{
// ... you can also use the pr_info macro which does the same thing
pr_info("Returning control of your system to you (%x)!\n",key);
}

module_init(had_init);
module_exit(had_exit);</pre>

This isn’t hard to puzzle out. Most of it is include files and macros that give modinfo something to print out. There are some variables: somedata is just a set variable that is readable during initialization. The key variable has a default but can be set using insmod. What’s more, is because module_param specifies 0644 — an octal Linux permission — there will be an entry in the /sys/modules directory that will let the root set or read the value of the key.

At the end, there are two calls that register what happens when the module loads and unloads. The rest of the code is just something to print some info when those events happen.

I printed data in two ways: the traditional printk and using the pr_info macro which uses printk underneath, anyway. You should probably pick one and stick with it. I’d normally just use pr_info.

Building the modules is simple assuming you have the entire build environment and the headers for the kernel. Here’s a simple makefile (don’t forget to use tabs in your makefile):
<pre>obj-m += hadmod1.o

PWD := $(CURDIR) # not needed in most cases, but useful if using sudo

all:
make -C /lib/modules/$(shell uname -r)/build M=$(PWD) modules

clean:
make -C /lib/modules/$(shell uname -r)/build M=$(PWD) clean</pre>

Once you build things, you should have a .ko file (like hadmod.ko). That’s the module. Try a few things:

1. sudo insmod hadmod.ko # load the module
2. sudo dmesg # see the module output
3. cat /sys/modules/hadmodule/key # see the key (you can set it, too, if you are root)
4. sudo rmmod hadmod.ko # unload the module
5. sudo insmod hadmod.ko key=128 # set key this time and repeat the other steps

That’s It?

That is it. Of course, the real details lie in how you interact with the kernel or hardware devices, but that’s up to you. Just to give a slightly meatier example, I made a second version of the module that adds /proc/jollywrencher to the /proc filesystem. Here’s the code:
#include <linux/init.h>
#include <linux/module.h>
#include <linux/moduleparam.h>
#include <linux/printk.h>
#include <linux/uaccess.h>
#include <linux/fs.h>
#include <linux/proc_fs.h> // Module metadata
#include <linux/version.h>

MODULE_AUTHOR("Al Williams");
MODULE_DESCRIPTION("Hackaday LKM1");
MODULE_LICENSE("GPLv2"); // many options, GPL, GPLv2, Proprietary, etc.

static char logo[]=
" \n"\
" \n"\
" \n"\
" #@@@@@@ ,@@@@@@ \n"\
" &@@@@@* &@@@@@, \n"\
" @@@@@@% @@@@@@# \n"\
" @@ .@@@@@@@@@ .@@@@@@@@@ .@# \n"\
" &@@@& /@@@@@@@@@@@@ @@@@@@@@@@@@ @@@@* \n"\
" @@@@@@@@@@@@@@@@@@@@@# @@@@@@@@@@@@@@@@@@@@@, \n"\
" &@@@@@@@@@@@@@@@@@@@@@* ,@@@@@@@@@@@@% &@@@@@@@@@@@@@@@@@@@@@* \n"\
" ,*. @@@@@@@@@@@/ .@@@@@@@@@@@@@@@@@@@@& &@@@@@@@@@@# ** \n"\
" @@@@@@, &@@@@@@@@@@@@@@@@@@@@@@@@@, %@@@@@& \n"\
" ,@& /@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@ \n"\
" &@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@* \n"\
" %@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@. \n"\
" @@@@@@ #@@@@@@@. /@@@@@@ \n"\
" /@@@@& @@@@@@. @@@@@ \n"\
" ,@@@@% (@@@@@@@@@@&* @@@@@ \n"\
" @@@@@# @@@@@@@@@@@@@@@@@@% @@@@@& \n"\
" /@@@@@@@@@@@@@@@, #@@@@@@@@@@@@@@@ \n"\
" @@ *@@@@@@@@@@@@@& ( @@@@@@@@@@@@@@ .@( \n"\
" %@@@@@. @@@@@@@@@@@@@@@@@@@@@@@@@@@@% #@@@@@* \n"\
" (%&%((@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@@@@@% ,@@@@@@@@@@*#&/ \n"\
" @@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@@@@@@@@@( @@@@@@@@@@@@@@@@@@@@@& \n"\
" @@@@@@@@@@@@@@@@@@@@@ @@@@@@*@@@@@@/%@@@@@& *@@@@@@@@@@@@@@@@@@@@# \n"\
" @@@@. @@@@@@@@@@@. .. . . (@@@@@@@@@@# /@@@* \n"\
" @, %@@@@@@@@ .@@@@@@@@. \n"\
" ,@@@@@( @@@@@@ \n"\
" *@@@@@@ (@@@@@@ \n"\
" @@@@@@, %@@@@@@ \n"\
" \n"\
" ";

static struct proc_dir_entry *proc_entry;
static ssize_t had_read(struct file *f, char __user * user_buffer, size_t count, loff_t * offset)
{
size_t len;
if (*offset>0) return 0; // no seeking, please!
copy_to_user(user_buffer,logo,len=strlen(logo)); // skipped error check
*offset=len;
return len;
}

#if LINUX_VERSION_CODE >= KERNEL_VERSION(5,6,0)
static struct proc_ops procop = // prior to Linux 5.6 you needed file_operations
{
.proc_read=had_read
};
#else
static struct file_operations procop =
{
.owner=THIS_MODULE,
.read=had_read
#endif

static int __init had_init(void)
{
// This is the usual way to do this (don't forget \n and note no comma after KERN_INFO), but...
printk(KERN_INFO "Hackaday<1>; is in control\n");
proc_entry=proc_create("jollywrencher",0644,NULL,&procop);
return 0;
}

static void __exit had_exit(void)
{
// ... you can also use the pr_info macro which does the same thing
pr_info("Returning control of your system to you...\n");
proc_remove(proc_entry);
}

module_init(had_init);
module_exit(had_exit);

The only thing here is you have an extra function that you have to register and deregister with the kernel. However, that interface changed in Kernel 5.6, so the code tries to do the right thing. Until, of course, it gets changed again.

Once you load this module using insmod, you can cat /proc/jollywrencher to see your favorite web site’s logo.

Of course, this is a dead simple example, but it is enough to get you started. You can grab all the source code online. One great way to learn more is to find something similar to what you want to build and take it apart.

We don’t suggest it, but you can write an LKM in Scratch. If you really want to learn the kernel, maybe start at the beginning.