Enable NuPhy Field75 volume knob on FreeBSD 14

       683 words, 4 minutes

By default, FreeBSD 14.1 does not recognized the multimedia keys of my NuPhy Field75 USB keyboard. Worse than that, the (beloved) metal knob used for volume control doesn’t work either.

Hopefully, after a bunch of readings & trials & errors, I ended up finding the configuration bits required to have it fully working!

Identifying the hardware

From dmesg(8), everything looked identified.

hkbd1: <NuPhy NuPhy Field75 Keyboard> on hidbus3
kbd3 at hkbd1
hkbd2: <NuPhy NuPhy Field75 Keyboard> on hidbus4
kbd4 at hkbd2
hsctrl1: <NuPhy NuPhy Field75 System Control> on hidbus4
hcons1: <NuPhy NuPhy Field75 Consumer Control> on hidbus4
hms1: <NuPhy NuPhy Field75 Mouse> on hidbus4
hms1: 5 buttons and [XYWH] coordinates ID=5
hms2: <NuPhy NuPhy Field75 Mouse> on hidbus5
hms2: 5 buttons and [XYWH] coordinates ID=0

From usbconfig(8), it appears as an Apple keyboard. No matter if you switch the keyboard in Windows or Apple mode, the reference and the overall behaviour are the same.

$ sudo usbconfig
(...)
ugen0.7: <Aluminium Keyboard (ANSI) Apple, Inc.> at usbus0, cfg=0 md=HOST spd=FULL (12Mbps) pwr=ON (100mA)
(...)

$ sudo usbconfig -d 0.7 -v
ugen0.7: <Aluminium Keyboard (ANSI) Apple, Inc.> at usbus0, cfg=0 md=HOST spd=FULL (12Mbps) pwr=ON (100mA)
ugen0.7.0: usbhid3: <NuPhy NuPhy Field75, class 0/0, rev 2.00/2.02, addr 6>
ugen0.7.1: usbhid4: <NuPhy NuPhy Field75, class 0/0, rev 2.00/2.02, addr 6>
ugen0.7.2: usbhid5: <NuPhy NuPhy Field75, class 0/0, rev 2.00/2.02, addr 6>
(...)

From xev(1), all keys were getting a keycode except the G1 to G4 ones and the volume knob.

Enabling multimedia keys

The fails

I tried to remove the USB keyboard from kbdmux.

kbdcontrol -K < /dev/console
kbdcontrol -a atkbd0 < /dev/kbdmux0
kbdcontrol -k /dev/kbdmux0 < /dev/console

This didn’t work. The USB keyboard still attached to kbdmux0 and no multimedia keys were available.

I tried teaching Xorg that there were 2 different keyboards to manage, but it kept using the keyboard multiplexer.

# cat /usr/local/etc/X11/xorg.conf.d/00-keyboard.conf
Section "InputClass"
       Identifier "thinkpad-keyboard"
       MatchIsKeyboard "on"
       MatchProduct "AT keyboard" # xinput
       Option "XkbLayout" "fr"
       Option "XkbModel" "pc105"
       Option "XkbVariant" ""
       Option "XkbOptions" ""
EndSection

Section "InputClass"
       Identifier "nuphy-keyboard"
       MatchIsKeyboard "on"
       MatchProduct "NuPhy NuPhy Field75" # xinput
       Option "XkbLayout" "us,us"
       Option "XkbModel" "pc105"
       Option "XkbVariant" "euro,intl"
       Option "XkbOptions" "grp:win_space_toggle"
EndSection

The success

The working solution appeared in the Howto: Enabling multimedia keys, gamepads/joysticks for desktop; usbhid thread from the FreeBSD Forums.

EDIT 2024-09-05: Correct parameters order in loader.conf.
Diane Bruce pointed me to the fact that “You need the module loaded before you can set it”. In the case usbhid is not loaded yet, you won’t have access to hw.usb.usbhid.enable. Thanks a lot!

To have the volume knob working, issue the following commands as root:

# kldload usbhid
# sysctl hw.usb.usbhid.enable="1"
# usbconfig reset ugen0.7

To have the volume knob working automatically after each boot, edit the loader.conf configuration file:

# cat >> /boot/loader.conf
usbhid_load="YES"
hw.usb.usbhid.enable="1"
^D

And that’s all. As simple as this 😅

Note that setting usbhid_load="YES" in /etc/rc.conf does not work.

Multi keyboard layout

It’s a bit off-topic regarding the multimedia keys problem but I use various keyboard logical layouts ; the ThinkPad keyboard is an ISO AZERTY and the NuPhy is an ANSI US. I sometimes also have to write french using the QWERTY keyboard so I like to enable the international layout to get accented characters.

To configure Xorg, simply add the keyboard configuration file as described in the FreeBSD Handbook .

$ cat /usr/local/etc/X11/xorg.conf.d/00-keyboard.conf
Section "InputClass"
    Identifier "Keyboard1"
    MatchIsKeyboard "on"
    Option "XkbLayout" "us,us,fr"
    Option "XkbModel" "pc105"
    Option "XkbVariant" "euro,intl,"
    Option "XkbOptions" "grp:win_space_toggle"
EndSection

Depending on the window manager and/or desktop environment, this can also be configured in the DE. In my experience, Xfce has its own configuration that can bypass Xorg and xfce4-kbd-plugin only displays Xfce configuration. In KDE 5, the Xorg configuration seem to be integrated in a better way as the keyboard plugin will inherit from Xorg configuration.

With this configuration, I can switch using <Super_L>+<space> between

That’s All Folks!

Related posts: