TPB(1)

📦 version 0.6.4, in debian bookworm, ubuntu jammy

💖 TPB(1) — the ThinkPad special keys bestie 💖

General Commands Manual · TPB(1)

✨ NAME ✨

tpb — the program you use to make the IBM ThinkPad (tm) special keys actually do stuff 🎀

🌸 SYNOPSIS 🌸

tpb [options]

🦋 DESCRIPTION 🦋

okay so picture this: you've got a ThinkPad and it has all these cute lil buttons — ThinkPad, Mail, Home, Search — and by default they're just... there. TPB fixes that. With TPB you can bind a program to the ThinkPad, Mail, Home and Search button. Obsessed.

And it gets better. TPB can also run a callback program on each state change, passing the changed state and the new state as options. So yeah, you can trigger several actions on different events, no cap. 💅

TPB also has an on-screen display (OSD) to show volume, mute, brightness and some other information. Iconic. ✨

AND — hear me out — TPB supports a software mixer, because the R series ThinkPads have no hardware mixer to change the volume. So if your volume buttons are giving nothing, that's why, and TPB is the fix. 🫶

💅 OPTIONS 💅

  • -h, --help — Display help. literally the "what do I do" button 🥺
  • -d, --daemon — Startup as daemon. she runs in the background, main character energy, no notes 👑
  • -c, --config=FILE — Read FILE as additional configuration file. extra config? yes bestie, we love options 🍓
  • -A, --apm=STATE — So some ThinkPads generate mouse and keyboard events, or have a high CPU load when polling /proc/apm. 💀 You may enable this if you want the AC connected/AC disconnected messages. Default is off.
  • -P, --powermgt=STATE — The program apmiser (part of the tpctl package) switches the power management mode according to the needs of the user. Which sounds great until you realize it results in lots of changes displayed in OSD 😭. To avoid this, the power management messages can be turned off. Default is auto.
  • -x, --xevents=STATE — Some of the special keys generate X11 events instead of changing the nvram. TPB is able to grab those keys and run an application. In general, events are only grabbed for keys for which a command is assigned, or if the callback script is configured. However some people like to use the X11 events through xmodmap or the like, so this option turns off the grabbing of all events regardless if they are configured or not. Affected keys are HOME, SEARCH, MAIL, FAVORITES, RELOAD, ABORT, BACKWARD, FORWARD and FN. Default is on.
  • -m, --mixer=STATE — Use OSS mixer to change volume and for mute/unmute. This should be used on models with no hardware mixer (volume and mute buttons show no effect). R31 is reported to have no hardware mixer. To use this you must enable write access to the NVRAM device (possibly dangerous 🚨). Possible values are on and off. Default is off.
ngl bestie, that NVRAM write access thing is giving "proceed with caution". She said possibly dangerous and she MEANT it. 🙈
  • -o, --osd=STATE — Show on-screen display for volume, mute and brightness. Possible values are on and off. Default is on. ✨
  • -p, --poll=DELAY — Set delay between polls in microseconds. Default is 200000. yeah, microseconds. she's precise like that 💅
  • -t, --thinkpad=CMD — String with command and options that should be executed when the ThinkPad button is pressed. It is possible to execute any program. The program needs to include the complete path to the executable. By default no command is executed.
  • -H, --home=CMD — String with command and options that should be executed when the Home button is pressed. By default no command is executed. 🏠
  • -S, --search=CMD — String with command and options that should be executed when the Search button is pressed. By default no command is executed. 🔍
  • -M, --mail=CMD — String with command and options that should be executed when the Mail button is pressed. By default no command is executed. 📧
  • -W, --wireless=CMD — String with command and options that should be executed when the Wireless button is pressed. By default no command is executed. 📶
  • -C, --callback=CMD — String with command and options that should be executed each button press and state change. tpb passes an identifier as first argument and the new state as second argument to the callback. So you can do fancy things :) By default no command is executed. the callback one is the moment fr fr 🌈
  • -v, --verbose — Print information about pressed keys. she's telling you EVERYTHING, no secrets between us 💖

okay that's the whole option list, but the page keeps going... 🌸

💾 CONFIGURATION FILE 💾

okay so bestie, you can totally override all the default values of tpb with a config file. and the priority of the config options goes like this, top to bottom, later ones win:

  • builtin defaults
  • configuration in /etc/tpbrc
  • configuration in $HOME/.tpbrc
  • configuration in file given with the --config command line option
  • command line options

tpb goes looking for the file ~/.tpbrc. the config is literally just lines that look like this:

# COMMENT

KEYWORD ARGUMENT # COMMENT

and the keywords are... girl, there's a lot, let's go:

  • NVRAM — should define the nvram device from where the info about key states gets read. default is to try /dev/nvram, then /dev/misc/nvram after that.
  • POLLTIME — defines the delay between polls in microseconds. default is 200000.
  • THINKPAD — a string with the command and options that should be run when the ThinkPad button is pressed. you can execute literally any program here. by default, no command is executed.
  • HOME — string with command and options to run when the Home button is pressed (only available on A and S series). by default, nothing happens.
  • SEARCH — string with command and options to run when the Search button is pressed (only available on A and S series). by default, no command.
  • MAIL — string with command and options to run when the Mail button is pressed (only available on A and S series). default: no command.
  • FAVORITES — string with command and options to run when the Favorites button is pressed (only available on A series). default: no command.
  • RELOAD — string with command and options to run when the Reload button is pressed (only available on A series). default: no command.
  • ABORT — string with command and options to run when the Abort button is pressed (only available on A series). default: no command.
  • BACKWARD — string with command and options to run when the Backward button is pressed (only available on A series). default: no command.
  • FORWARD — string with command and options to run when the Forward button is pressed (only available on A series). default: no command.
  • FN — string with command and options to run when the Fn button is pressed. this only gets triggered when Fn is released again and it wasn't used for a key combination. default: no command.
  • CALLBACK — string with command and options that should be executed on each button press and state change. tpb passes an identifier as the first argument and the new state as the second argument to the callback. so you can do fancy things :) by default no command is executed. the supported identifiers and states are:
    • thinkpad — pressed
    • home — pressed
    • search — pressed
    • mail — pressed
    • favorites — pressed
    • reload — pressed
    • abort — pressed
    • backward — pressed
    • forward — pressed
    • fn — pressed
    • zoom — on, off
    • thinklight — on, off
    • display — lcd, crt, both
    • expand — on, off
    • brightness — PERCENT
    • volume — PERCENT
    • mute — on, off
    • ac_power — connected, disconnected
    • powermgt_ac — high, auto, manual
    • powermgt_battery — high, auto, manual
  • MIXER — use OSS mixer to change volume and for mute/unmute. this should be used on models with no hardware mixer (where the volume and mute buttons show no effect). R31 is reported to have no hardware mixer. to use this you must enable write access to the NVRAM device (possibly dangerous ⚠️). possible values are on and off. default is off.
  • MIXERSTEPS — defines how much steps should be available when using the OSS mixer. default is 14. if another number of steps is used, tpb needs write access to the nvram device.
  • MIXERDEV — defines the mixer device to use for OSS mixer support. default is /dev/mixer.
  • APM — some ThinkPads generate mouse and keyboard events or have a high CPU load when polling /proc/apm. you may enable this if you want the AC connected/AC disconnected messages. default is off.
  • POWERMGT — the program apmiser (part of the tpctl package) switches the power management mode according to the needs of the user. this results in lots of changes displayed in the OSD. to avoid this, the power management messages can be turned off. default is auto.
  • XEVENTS — some of the special keys generate X11 events instead of changing the nvram. TPB is able to grab those keys and run an application. in general events are only grabbed for keys that have a command assigned or if the callback script is configured. however some people like to use the X11 events through xmodmap or the like. this option turns off the grabbing of all events regardless of whether they're configured or not. affected keys are HOME, SEARCH, MAIL, FAVORITES, RELOAD, ABORT, BACKWARD, FORWARD and FN. default is on.
  • OSD — show on-screen display for volume, mute and brightness. possible values are on and off. default is on.
  • OSDZOOM — specific switch for showing the on-screen display for the zoom button. possible values are on and off. default is unset, follows the OSD option.
  • OSDTHINKLIGHT — specific switch for showing the on-screen display for the thinklight button. possible values are on and off. default is unset, follows the OSD option.
  • OSDDISPLAY — specific switch for showing the on-screen display for the display output button. possible values are on and off. default is unset, follows the OSD option.
  • OSDHVEXPANSION — specific switch for showing the on-screen display for the HV expansion button. possible values are on and off. default is unset, follows the OSD option.
  • OSDBRIGHTNESS — specific switch for showing the on-screen display for the brightness buttons. possible values are on and off. default is unset, follows the OSD option.
  • OSDVOLUME — specific switch for showing the on-screen display for the volume and mute buttons. possible values are on and off. default is unset, follows the OSD option.
  • OSDPOWERMGT — specific switch for showing the on-screen display for power management changes. possible values are on and off. default is unset, follows the OSD option.
  • OSDFONT — defines the font for the on-screen display. you may use "xfontsel" to choose one. default is the default font of the xosd library.
  • OSDCOLOR — defines the color of the on-screen display. you may use "xcolors" to choose one. default is BLUE.
  • OSDTIMEOUT — defines how long (in seconds) the on-screen display is shown after the last key was pressed. default is 3.
  • OSDOFFSET — for backward compatibility. same as OSDVERTICAL.
  • OSDSHADOW — defines the offset of the font shadow in pixels. default is 2.
  • OSDSHADOWCOLOR — defines the color of the shadow of the on-screen display. you may use "xcolors" to choose one. default is BLACK.
  • OSDOUTLINE — defines the width of the font outline in pixels. default is 1.
  • OSDOUTLINECOLOR — defines the color of the outline of the on-screen display. you may use "xcolors" to choose one. default is BLACK.
  • OSDVERTICAL — defines the offset from the top or bottom of the screen in pixels. default is 25.
  • OSDHORIZONTAL — defines the offset from the left or right of the screen in pixels. only supported by xosd 2.0.0 and above. default is 25.
  • OSDPOS — defines where the osd is shown. possible values are top, middle and bottom. the value middle is only supported by xosd 2.0.0 and above. default is bottom.
  • OSDALIGN — defines the alignment of the osd. possible values are left, center and right. default is left.

📝 NOTES

requires the NVRAM device /dev/nvram. this must be enabled in your kernel. although the device file must exist. the device file could be created with mknod /dev/nvram c 10 144 💅

this program was developed on a Thinkpad Model T21.

🌟 EXAMPLE

tpb --osd=off --verbose --thinkpad="xterm -T ntpctl -e ntpctl"

Copyright 2002-2005, Markus Braun <markus.braun@krawel.de>

Licensed under GNU GPL version 2 or later. this is free software; see the source for copying conditions. there is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

✍️ AUTHOR

Written by Markus Braun

okay that's the whole vibe, bestie 🫶 this page is from version 0.6.4, dated 25 Juli 2005, and it lives under the name TPB(1) — iconic, legendary, vintage ThinkPad excellence, no cap 💖✨🎀

📦 where this page comes from