GMOBILE.UDEV(5)

💖 gmobile.udev — device config for gmobile, but make it hwdb 💖

okay bestie, so this is gmobile.udev from section 5 of the manual, and it's literally the glow-up guide for telling gmobile how your specific device should behave. it's not a command, it's a vibe document. no cap.

---

✨ NAME ✨

gmobile.udev — device configuration for gmobile 🎀

---

🌸 DESCRIPTION 🌸

so gmobile lets you configure certain aspects of itself through udev's hwdb. the hwdb docs live over at https://www.freedesktop.org/software/systemd/man/hwdb.html if you wanna go read the lore yourself.

these are the properties that are supported, and yes we're going through all of them, don't scroll 🫶

---

🔥 WAKEUP KEYS 🔥

an input device's wakeup keys are the ones that say "hey, unblank the screen" when your device is just chillin' idle. by default, all keys are wakeup keys. iconic, but sometimes not it.

you can flip that default on a per-keyboard level with:

GM_WAKEUP_KEY_DEFAULT=0

and then, if you want to be ✨specific✨ about individual keys, you hand over their keycodes like this:

GM_WAKEUP_KEY_<keycode>=[0|1]

the keycode here is the linux event code. that's the one. that's the number.

heads up bestie: gmobile merely provides that information. it does not apply it. the Wayland compositor is the one responsible for actually applying it. gmobile is just the messenger 💅

for the tea on how to actually add these properties to hwdb, scroll down to the section below, i got you.

---

🧚 TORCH BRIGHTNESS 🧚

a LED that's used as a camera flash can also be used as a torch (main character behaviour honestly). the minimum torch brightness should still be visible to the user, so you don't just silently drain your battery for nothing. usually level 1 is where that lands. and GM_TORCH_MIN_BRIGHTNESS lets you override that value:

GM_TORCH_MIN_BRIGHTNESS=10

same deal as before: gmobile merely provides that information. the applications using the flash as a torch are the ones responsible for applying it. not gmobile's problem, not gmobile's job 🙈

for details on how to add these properties to hwdb, see below. (yes, again. it's a whole thing.)

---

🌈 CONFIGURING HWDB 🌈

okay so, the hwdb contains a set of match rules that assign udev properties, and those properties become available the moment the device is connected. slay.

real talk though: this section only describes the hwdb in relation to gmobile. it is not full documentation on how the hwdb works. for that, please go read the hwdb(7) man page. periodt.

gmobile's use of the hwdb is limited to properties that systemd and custom rules files (where available) provide.

🔍 Querying the hwdb

gmobile currently only uses device nodes in the form of /dev/input/eventX, where X is the number of the specific device. running libinput debug-events lists all devices currently available to libinput and their event node name:

$> sudo libinput debug-events
-event0   DEVICE_ADDED            gpio-keys                         seat0 default group1  cap:k
-event2   DEVICE_ADDED            30370000.snvs:snvs-powerkey       seat0 default group2  cap:k
-event3   DEVICE_ADDED            generic ft5x06 (f0)               seat0 default group3  cap:t ntouches 10 calib
...

not me telling you to note the event node name for your device 📝 and then translate it into a syspath in the form of /sys/class/input/eventX. that path can be supplied to udevadm info:

$> udevadm info -p /sys/class/input/event0/
P: /devices/platform/gpio-keys/input/input0/event0
M: event0
R: 0
U: input
D: c 13:64
N: input/event0
L: 0
S: input/by-path/platform-gpio-keys-event
E: DEVPATH=/devices/platform/gpio-keys/input/input0/event0
E: SUBSYSTEM=input
E: DEVNAME=/dev/input/event0
E: MAJOR=13
E: MINOR=64
E: USEC_INITIALIZED=5327886
E: ID_INPUT=1
E: ID_INPUT_KEY=1
E: ID_PATH=platform-gpio-keys
E: ID_PATH_TAG=platform-gpio-keys
E: GM_WAKEUP_KEY_114=0
E: GM_WAKEUP_KEY_115=0
…

lines starting with E: are udev properties available to applications. properties added by gmobile all have a GM_ prefix. and lowkey important: they're only present if a hwdb entry matches. no match, no property, no vibes.

♻️ Reloading the hwdb

the actual hwdb is stored in a binary file on-disk, and it must be updated manually whenever a .hwdb file changes. this is required both when a user manually edits the .hwdb file or when gmobile ships an updated set of entries. either way, manual. every time. 😭

to update the binary file on-disk, run:

sudo systemd-hwdb update

then, to trigger a reload of all properties on your device, run:

sudo udevadm trigger /sys/class/input/eventX

then check with udevadm info whether the properties were actually updated — see Querying the hwdb above, bestie, i told you it'd come back around 🦋

and if a new property does not appear on the device, use udevadm test to check for error messages by udev and the hwdb (think syntax errors in the udev rules files):

sudo udevadm test /sys/class/input/eventX

🛠️ Modifying the hwdb

this section is for the users who need to add, change, or remove a hwdb entry for their device. and uh, listen:

note that the hwdb is not part of the public API and may change at any time. no cap, it can move under your feet.

once a device has been made to work, the change must be submitted to the gmobile repository at https://gitlab.gnome.org/World/Phosh/gmobile. that's the rule. we share the wealth here 💜

hwdb entries are only applied if a udev rules calls out to the hwdb with the right match format. gmobile ships with a set of rules to query the hwdb, and the different rules are reflected by their prefix. again — not part of the public API, don't get attached. gmobile's matches are composed of:

1. a literal "gmobile"
2. then either the device name (prefixed with name:) followed by the machine's first device tree compatible (prefixed with dt:)
3. or dmi modalias

for example:

gmobile:name:gpio-keys:dt:purism,librem5*

the device name is available in the device's /sys/class/input/eventX/device/name, while the device tree compatible is available in /sys/firmware/devicetree/base/compatible. go get 'em.

so the hwdb match string is the first portion of the hwdb entry. the second portion is the property to set. and each hwdb entry may match on multiple devices and may apply multiple properties. like:

gmobile:name:gpio-keys:dt:purism,librem5*
  GM_WAKEUP_KEY_114=0
  GM_WAKEUP_KEY_115=0

in the example above, the matching gpio-keys device will have both properties applied. two for one, we love to see it ✨

now, plot twist:

the hwdb does not allow removing properties. where a property must be unset, it should be set to 0. that's the move. that's the only move. 💀

and for testing, any user-specific hwdb entries should be placed in a file at /etc/udev/hwdb.d/99-gmobile.hwdb — but please, please, make sure to submit them upstream, as the hwdb format might change without notice. don't let your local hack become a cursed orphan 🙏

---

👑 SEE ALSO 👑

hwdb(7) systemd-hwdb(8) phoc(1) phosh(1)

---

okay that's the whole page bestie, you ate it 💅 and for the cute sign-off: the footer of this page is just gmobile.udev() — that's the source/version line, sitting in section 5 of the manual, and ngl there's no date stamp on it, so don't go looking for one. mwah 🫶💖