thinkpad-dock¶
set the screens when going to and from the docking station
Author: | Martin Ueding <mu@martin-ueding.de> |
---|---|
Manual section: | 1 |
Synopsis¶
thinkpad-dock [on|off]
Description¶
This program sets the screen resolution correctly when putting the ThinkPad onto the docking station. It also sets the Wacom input devices to act on the internal screen only.
It deduces what to do automatically, if no option is given. If it is docked, it will perform the docking action. When you pressed the eject button on the docking station, it will un-dock.
There will be an udev rule installed that will automatically dock it when set
onto the station and un-dock when you press the eject button. Technically, this
rule calls the thinkpad-dock-hook
.
What it does¶
When docking, the following things are done:
- Activating the external monitor.
- Setting the external monitor as primary monitor.
- Deactivate the wireless connection.
- Set the Wacom devices to the internal screen only.
- Set the brightness to a fixed value, currently 60%.
- Unmute the speakers and set the volume to 100%.
When undocking, the following things are done:
- Deactivating external monitor.
- Setting the internal monitor as primary monitor.
- Activating the wireless connection.
- Set the speakers to some medium volume, currently 50%.
Options¶
- on|off
If you have it sitting on the docking station and want it to dock, use
on
. Otherwise useoff
before you take the ThinkPad off the docking station.You can omit this option and the script will guess what to do by checking whether a dock is docked in
/sys
.
Exit Status¶
- 0
- Everything okay.
- 1
- Some error.
Files¶
Config¶
You can create a config file in $HOME/.config/thinkpad-scripts/config.ini
,
which has standard INI format. The old config can be converted using the
thinkpad-scripts-config-migrate
script that was introduced in version 4.0.
A sample config would look like this:
[sound]
dock_loudness = 50%
[network]
disable_wifi = true
[screen]
relative_position = left-of
I will list all possible options in a moment. Since the INI format is
hierarchical, I will denote the options with a dot. The first one would be
sound.dock_loudness
for example.
Those are the possible options:
dock.lsusb_indicator_regex
Some docks might not have a docking indicator in the sysfs. In Issue 129 it has been discussed to use a particular USB device that is attached only at the dock to function as an indicator. If this option is set to a non-zero length string, it will be used as a regular expression. The output of
lsusb
is searched for that regular expression. If a match is found, the laptop is assumed to be on the docking station.Example
The output of
lsusb
might contain lines like the following:Bus 002 Device 003: ID 056a:00e6 Wacom Co., Ltd TPCE6 Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub Bus 001 Device 003: ID 04f2:b217 Chicony Electronics Co., Ltd Lenovo Integrated Camera (0.3MP) Bus 001 Device 006: ID 046d:c05a Logitech, Inc. M90/M100 Optical Mouse Bus 001 Device 008: ID 273f:1007 Bus 001 Device 005: ID 0424:2514 Standard Microsystems Corp. USB 2.0 Hub Bus 001 Device 004: ID 0424:2514 Standard Microsystems Corp. USB 2.0 Hub Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Some of these devices might be integrated in the docking station. One of the USB hubs is the one in my external screen. That does not help much because its ID is not unique. The unnamed device with ID
273f:1007
is only present on the docking station. Therefore I would set the configuration value to273f:1007
.At the office, I have a second docking station. There I have some other device, say ID
1234:1234
. Since this configuration option is a regular expression, I could specify the following:273f:1007|1234:1234
. Then both devices can trigger the docking state.gui.kdialog
- Please see the appropriate section in thinkpad-rotate(1), it has the same option. Default:.
hooks.postdock
- Full path to postdock hook. Default: ~/.config/thinkpad-scripts/hooks/postdock
hooks.predock
- Full path to predock hook. Default: ~/.config/thinkpad-scripts/hooks/predock
logging.syslog
- Whether to log everything to syslog. Default: true
network.disable_wifi
- Whether to set the wifi. Default: true.
network.restart_connection
- If this is set, the given network connection will be restarted on startup. I (Martin Ueding) have seen the issue where my default DHCP connection would not work right away. Restarting that connection helped. Default: true
network.connection_name
- If the connection should be restarted, you can specify which one in case
there is more than one wired connection. The default case is to use the
lexicographically first connection name in the list provided by
nmcli
that contains the case-insensitive string'ethernet'
. screen.internal_regex
- Regular expression to match the
xrandr
name for the internal monitor. Default: LVDS-?1|eDP-?1 screen.primary
- The
xrandr
name for the primary monitor when docked or an empty string to guess a reasonable monitor. Default: (empty string). screen.secondary
- The
xrandr
name for the secondary monitor when docked or an empty string to guess a reasonable monitor. Default: (empty string). screen.set_brightness
- Whether to change the brightness. Default: true.
screen.brightness
- Brightness to set to when docking. Default: 60%.
screen.relative_position
- Where to set the primary monitor relative to the secondary monitor when
docking. Set it to
right-of
orleft-of
or anything else thatxrandr
supports with a--*
argument. Default: right-of. screen.internal_docked_on
- Whether to keep the internal screen on while docking. Default: true
sound.unmute
- Whether to change the volume. Default: true.
sound.dock_loudness
- Volume to set to when docking. Default: 100%.
sound.undock_loudness
- Volume to set to when undocking. Default: 50%.
trigger.dock_triggers
- Whitespace-delimited list of the enabled hardware triggers to execute
docking/undocking. The available triggers are
udev1_on
,udev1_off
,acpi1_on
,acpi1_off
, andacpi2
. Default:udev1_on udev1_off
Hooks¶
There are hooks, called before and after the main script. It gets a single
command line argument, on
or off
.
~/.config/thinkpad-scripts/hooks/predock
~/.config/thinkpad-scripts/hooks/postdock
You can change the path of those hooks in the configuration, see above.
Example¶
You can just call thinkpad-dock
and it will do the right thing probably.
If you want, you can tell the script what to do: When you have it sitting on
the docking station, call thinkpad-dock on
to get the external screen
going. When you are done, call thinkpad-dock off
before you disconnect to
get the internal screen back again.
Epilogue¶
This file is part of thinkpad-scripts by Martin Ueding and Jim Turner.
We hope that this collection of scripts is useful to you. If you experience bugs, find the documentation lacking or have a new kind of hardware that we do not yet support, feel free to open an issue on GitHub or write an email to Martin Ueding.
See also
- GitHub Repository
- project website.
- Hosted documentation (via Read the Docs)