Define custom keycodes/scancodes

[toshokan]

I'm new to QMK and have been looking through the docs and building a layout. I've also been looking though the sources trying to find a place where I can define codes that aren't defined in qmk/tmk by default.

For example, I'm looking to map a key to the display key commonly found on laptops, which is read as XF86Display under GNU/Linux. I don't see this key mentioned anywhere in the sources or the keymap list/header. Is there a place I can define this key so I can use it?

Thanks :^)
Sorry if I'm missing something obvious

[hiro2016]

Hmm, what you see in keymap.c file within KEYMAP macro, like KC_A, KC_B are macros.
e.g.

 #define KC_A 0x04   

And as you can see in the above, it's expanded into a number before compilation;to a hid usage id.
http://www.usb.org/developers/hidpage/Hut1_12v2.pdf

So what you have to do is to find the right hid usage id and put in in KEYMAP marco statement, no definition needed.
But be warned, to support old ps2 keyboard or whatever, operation systems remaps hid usage ids to scancodes and sometimes it does so differently for each keyboard.

In the case of linux:

• driver translates id to kernel keycode(potentially vendor id and device id specific rule involved)
• xserver translates kernel keycode to x11 keycode(configuration dependent)

I do not know much about display key but if that is hardware related, then apci might be involved as well. Good luck.

[drashna]

Not sure that this would work, as it may need drivers on all systems.

[toshokan]

If this wouldn't work, what would a better way to do this be?

[madivad]

Why is this issue closed? If it’s not an issue and there is a way to achieve what the OP was asking, could someone enlighten us?

I’m searching for this answer myself and have not yet found a solution (I expect it is out there, I just haven’t found it yet).

When you have an extra key and you are trying to may it to a scan code that can be passed onto the kernel, it would be best to try and choose a code that’s least likely to be utilised by the system at hand.

I think I am looking for a slightly different approach in that I want to custom define my scan codes so they are nowhere near the general user space and then setup my own rules in hwdb\rules to map them as appropriate.

Back to the OPs question, how/where should he achieve his desired outcome?

[fauxpark]

In regard to the question in the OP:

The keycode "XF86Display" is not all that useful - this is just what X.Org calls the action that key represents. It can map to various things depending on the hardware, including, as was mentioned above, however ACPI sends button presses to the OS/kernel.

It does appear that there is a HID usage for this action (0xB5, System Display Toggle Int/Ext) in the Generic Desktop page (0x01): https://www.usb.org/sites/default/files/documents/hut1_12v2.pdf#page=27

And on Linux at least, it is recognised by the kernel:
https://github.com/torvalds/linux/blob/41de59634046b19cd53a1983594a95135c656997/drivers/hid/hid-input.c#L671-L677

Three problems with this:

1. That particular chunk of code was only just added 7 months ago at the time of writing, so it is probably not particularly prevalent (unless modern distros are really up to date with their kernels, IDK much about that).
2. I am not sure if Windows or macOS will recognise it either. Outside of the keyboard, mouse, and media key usages, the majority of these more obscure ones still go unsupported, which is a shame because there's some really interesting stuff in the HUTs.
3. The available QMK keycode space for adding new "media keys" is currently all but depleted - there is only one spot left. This can be mitigated by removing the deprecated KC_FN* keycodes, but will take a while as there are tons of keymaps both here and in the wild which still use them, so I need to wait for the next breaking change window (couldn't get around to it this first round).

@madivad as for your problem, this is just as tricky, not just because of 3. above, but also because QMK internally constrains what keycodes it actually emits over the wire. You could modify those functions so that they accept your keycodes, but that seems a bit messy.

Perhaps the best solution here would be to combine the usual process_record_user() method with the Raw HID feature. The catch is that you'll have to write a program that runs on the host and is always listening to the keyboard on the raw HID interface. This is... not very well documented, but involves implementing one or both of these functions: https://github.com/qmk/qmk_firmware/blob/master/tmk_core/common/raw_hid.h

[madivad]

@fauxpark Thanks very much for your reply. Very informative. I'm only very new to QMK and still waiting for my first device to arrive :) I'm quite excited to dig in after many failed attempts at using commercial macro boards and keyboards, I've figured, "stuff this, I'm making my own!" I have Hasu's USB-USB converter arriving in the next couple of days plus I have another macro board that I'm going to recycle into a custom QMK keyboard, plus I have my main board I have in mind to build. I'm very much looking forward to getting into this and having some serious fun.

I don't want to choke up this issue (at least it's closed I suppose), but is there any good forums or especially IRC channels good for discussion in depth Linux evdev stuff and especially QMK? I'd love some pointers and although I've been extensively researching it, it's hard wading through an internet of dozens of distros over just as many years and filtering out what's current, what's cutting edge and what's been deprecated for aeons! lol. Any links appreciated. cheers. (and thanks for the above links and info, I didn't realise the space was so tight).

[fauxpark]

Unfortunately I don't know a whole lot about the Linux end, but good places to ask about QMK stuff are the Discord, and the OLKB subreddit.

I also thought of an easier solution: just use KC_F13 through KC_F24. These generally don't do anything on most OSes, but should be widely recognised. I imagine it would be trivial to remap these to whatever you want in Linux. On Windows, you would use something like AutoHotKey, and Karabiner for macOS.

[ridingqwerty]

@madivad xmodmap is the way to do this. This came up in the QMK Discord a few weeks ago, but on some Linux distros, F13 is already being rebound to XF86Tools via xmodmap, which is halfway to what OP wanted already.

Typing KC_F13 into xev yields the following:

KeyPress event, serial 33, synthetic NO, window 0x3400001,
    root 0x17c, subw 0x0, time 14093171, (362,325), root:(2692,345),
    state 0x0, keycode 191 (keysym 0x1008ff81, XF86Tools), same_screen YES,
    XKeysymToKeycode returns keycode: 179
    XLookupString gives 0 bytes:
    XmbLookupString gives 0 bytes:
    XFilterEvent returns: False

You can create a custom ~/.Xmodmap containing these lines (one starting with ! is comment showing default behavior):

! keycode 191 = XF86Tools NoSymbol XF86Tools
keycode 191 = XF86Display NoSymbol XF86Display

...and then make these changes take effect until reboot by doing xmodmap ~/.Xmodmap