Dockutils

From openSUSE

Introduction

Dockutils is a collection of scripts providing an infrastructure to easily trigger actions on docking/undocking requests for different laptops and vendors.

It should serve three general purposes:

• Provide infrastructure to do userspace stuff that has to be done on dock and undock
• Provide easy to use infrastructure for hardware vendors, distributors or users to get proper docking station support or to do just anything they like on dock/undock, for instance starting a special tool or just displaying a message on the desktop. More on how to do this, see below.
• Provide infrastructure for nasty and ugly workarounds either because of broken hardware, bugs or just because of a lack of support in the kernel

The framework

docker

Dockutils comes along with a script called docker. It is a command line tool to trigger dock/undock requests manually. For instance, you just have to call 'docker dock' or 'docker undock'. However, ideally everything should just work automatically without any user interaction.

dockhandler

This is the central point from where every hook is called. Either the command line tool docker or an acpi event coming from the acpid daemon will execute this script. This in turn will run the hooks for your laptop model. Each hook gets called with one parameter. Either 'dock' or 'undock', depending on the event, of course ;-)

Additionally, there will be an exported variable $MODEL which contains a descriptive string about your laptop, so that one can match against it.

Dockutils is whitelist based. That means, it only does things automatically for laptop models it knows about

hooks

Below /usr/lib/dockutils, there is a directory structure containing the different hooks for different vendor laptops. Some laptops from a specific vendor may have some things in common which have to be done on every dock/undock. One example for those laptops is the directory hooks/thinkpad which should only contain hooks for this vendor. For other notebooks which don't have anything common, place a hook into the hooks/misc directory. All hooks are prefixed with a number. On docking they are run in descending order, on undocking in reverse order (ascending).

Example hook located in /usr/lib/dockutils/misc/, maybe called 50examplehook:

#!/bin/bash
# This is an example hook

# $MODEL is exported to every hook and is read out from dmidecode output
[ "$MODEL" == "Thinkpad X60" ] && exit 0;

if [ "$1" = "dock" ]; then
    # do something  on docking
    echo docking

elif [ "$1" = "undock" ]; then
    # do something on undock
    echo undocking
fi

exit 0

How to contribute

submitting hooks

If you have a notebook with a docking station and you are knowing some quirks to get working docking support for it, please feel free to create a hook and send it to me (holger at homac dot de). I will most likely include it. However, if it's just a nasty workaround for a bug somewhere, please additionally create a bugreport[1] so that the real issue get fixed and I am able to remove the hook as soon as possible. And if I notice that it's just a workaround for a deeper problem, I will most likely ask you for a pointer to your report ;-)

project page

For latest and greatest sourcecode, check out the code from svn. Look at the the project page[2] on sourceforge how to do this.