acpid - ArchWiki

Jump to content
From ArchWiki

Related articles

- ACPI modules
- DSDT

acpid2 is a flexible and extensible daemon for delivering ACPI events. When an event occurs, it executes programs to handle the event. These events are triggered by certain actions, such as:

- Pressing special keys, including the Power/Sleep/Suspend button
- Closing a notebook lid
- (Un)Plugging an AC power adapter from a notebook
- (Un)Plugging phone jack etc.

Note: Desktop environments, such as GNOME, systemd login manager, and some extra key handling daemons may implement their own event handling schemes, independent of acpid. Running more than one system at the same time may lead to unexpected behaviour, such as suspending two times in a row after one sleep button press. You should be aware of this and only activate desirable handlers.

## Installation

Install the acpid package. Then start/enable `acpid.service`.

## Configuration

acpid comes with a number of predefined actions for triggered events, such as what should happen when you press the Power button on your machine. By default, these actions are defined in `/etc/acpi/handler.sh`, which is executed after any ACPI events are detected (as determined by `/etc/acpi/events/anything`).

### Determine the event

Unfortunately, not every computer labels ACPI events in the same way. For example, the Sleep button may be identified on one machine as SLPB and on another as SBTN.

To determine how your buttons or `Fn` shortcuts are recognized, run the following command:

    # journalctl -f

Now press the Power button and/or Sleep button (e.g. `Fn+Esc`) on your machine. The result should look something this:

    logger: ACPI action undefined: PBTN
    logger: ACPI action undefined: SBTN

If that does not work, run:

    # acpi_listen

or with openbsd-netcat:

    $ netcat -U /var/run/acpid.socket

Then press the power button and you will see something like this:

    button/power PBTN 00000000 00000b31

The output of `acpi_listen` is sent to `/etc/acpi/handler.sh` as $1, $2 , $3 & $4 parameters. Example:

    $1 button/power
    $2 PBTN
    $3 00000000
    $4 00000b31

### Define event action

The following is a brief example of one such action. In this case, when the Sleep button is pressed, acpid runs the command `echo -n mem >/sys/power/state` which should place the computer into a sleep (suspend) state:

    button/sleep)
        case "$2" in
            SLPB) echo -n mem >/sys/power/state ;;
    	 *)    logger "ACPI action undefined: $2" ;;
        esac
        ;;

The event may be different on different machines. For example if Sleep button is actually recognized as SBTN, rather than the SLPB label specified in the default `/etc/acpi/handler.sh`. In order for Sleep function to work properly on this machine, we would need to replace SLPB) with SBTN).

Using this information as a base, you can easily customize the `/etc/acpi/handler.sh` file to execute a variety of commands depending on which event is triggered. See the #Tips and tricks section below for other commonly used commands.

Note: Events such as `button/power`, `button/lid`, `button/suspend` and `button/hibernate` are handled by systemd-logind.service(8) by default, see Power management#Power management. If handling these events with acpid, the handling of these events by logind should either be disabled first, or inhibited.

### Alternative configuration

By default, all ACPI events are passed through the `/etc/acpi/handler.sh` script. This is due to the ruleset outlined in `/etc/acpi/events/anything`:

    # Pass all events to our one handler script
    event=.*
    action=/etc/acpi/handler.sh %e

While this works just fine as it is, some users may prefer to define event rules and actions in their own self-contained scripts. The following is an example of how to use an individual event file and corresponding action script:

As root, create the following files:

    /etc/acpi/events/sleep-button

    event=button/sleep.*
    action=/etc/acpi/actions/sleep-button.sh %e

    /etc/acpi/actions/sleep-button.sh

    #!/bin/sh
    case "$3" in
        SLPB) echo -n mem >/sys/power/state ;;
        *)    logger "ACPI action undefined: $3" ;;
    esac

Make the script executable, and reload the `acpid.service` to get acpid to recognize the changes to these files.

Using this method, it is easy to create any number of individual event/action scripts.

## Tips and tricks

Note: Some of the actions described here, such as Wi-Fi toggle and backlight control, may already be managed directly by driver. You should consult documentation of corresponding kernel modules, when this is the case.

### Example events

The following are examples of events that can be used in the `/etc/acpi/handler.sh` script. These examples should be modified so that they apply your specific environment e.g. changing the event variable names interpreted by `acpi_listen`.

To set the laptop screen brightness when plugged in power or not (the numbers might need to be adjusted, see `/sys/class/backlight/acpi_video0/max_brightness`):

    ac_adapter)
        case "$2" in
            AC*|AD*)
                case "$4" in
                    00000000)
                        echo -n 50 > /sys/class/backlight/acpi_video0/brightness
                        ;;
                    00000001)
                        echo -n 100 > /sys/class/backlight/acpi_video0/brightness
                        ;;
                esac

### Enabling volume control

Find out the acpi identity of the volume buttons (see above) and substitute it for the acpi events in the files below.

    /etc/acpi/events/vol-d

    event=button/volumedown
    action=amixer set Master 5-

    /etc/acpi/events/vol-m

    event=button/mute
    action=amixer set Master toggle

    /etc/acpi/events/vol-u

    event=button/volumeup
    action=amixer set Master 5+

Note: These commands may not work as expected with PulseAudio. [1] For full functionality, run commands as the current user while specifying the `XDG_RUNTIME_DIR` environment variable, for example with:

    # sudo -u user XDG_RUNTIME_DIR=/run/user/user_id pactl

Tip: Disable or bind the volume buttons in Xorg to prevent conflicts with other applications. See Xmodmap for details.

See also [2].

### Enabling backlight control

Similar to volume control, acpid also enables you to control screen backlight. To achieve this you write some handler, like this:

    /etc/acpi/handlers/bl

    #!/bin/sh
    bl_dev=/sys/class/backlight/acpi_video0
    step=1

    case $1 in
      -) echo $(($(< $bl_dev/brightness) - $step)) >$bl_dev/brightness;;
      +) echo $(($(< $bl_dev/brightness) + $step)) >$bl_dev/brightness;;
    esac

The event in acpi_listen should be something like:

    video/brightnessdown BRTDN 00000087 00000000
    video/brightnessup BRTUP 00000086 00000000

Connect them to ACPI events:

    /etc/acpi/events/bl_d

    event=video/brightnessdown.*
    action=/etc/acpi/handlers/bl -

    /etc/acpi/events/bl_u

    event=video/brightnessup.*
    action=/etc/acpi/handlers/bl +

### Enabling Wi-Fi toggle

You can also create a simple wireless-power switch by pressing the WLAN button. Example of event:

    /etc/acpi/events/wlan

    event=button/wlan
    action=/etc/acpi/handlers/wlan

and its handler:

    /etc/acpi/handlers/wlan

    #!/bin/sh
    rf=/sys/class/rfkill/rfkill0

    case $(< $rf/state) in
      0) echo 1 >$rf/state;;
      1) echo 0 >$rf/state;;
    esac

### Disabling ordinary key events

Since b336c96 acpid generates events for some ordinary key presses, such as arrow keys. This results in event/handler spam, visible in system logs or top. Events for these buttons can be dropped in the configuration file:

    /etc/acpi/events/buttons

    event=button/(up|down|left|right|kpenter)
    action=<drop>

### Getting user name of the current display

To run commands depending on Xorg, defining the X display as well as the MIT magic cookie file (via XAUTHORITY) is required. Latter is a security credential providing read and write access to the X server, display, and any input devices (see xauth(1)).

See [3] for an example function when using xinitrc.

Note:

- If the LCD backlight is not turned off when the lid is closed, you may do so manually by running `getXuser xset dpms force off` and `getXuser xset dpms force on` respectively on lid close and lid open events. Should the display be blanked, but the backlight left on, instead use vbetool with `vbetool dpms off` and `vbetool dpms on`. See also XScreenSaver#Configuration.
- When using who or w, make sure `/run/utmp` is created at boot-time. See utmp(5) for details.

#### Connect to acpid socket

In addition to rule files, acpid accepts connections on a UNIX domain socket, by default `/var/run/acpid.socket`. User applications may connect to this socket.

    #!/bin/bash
    coproc acpi_listen
    trap 'kill $COPROC_PID' EXIT

    while read -u "${COPROC[0]}" -a event; do
        handler.sh "${event[@]}"
    done

Where `handler.sh` can be a script similar to `/etc/acpi/handler.sh`.

### Disable keyboard and touchpad while laptop lid is closed under Wayland

This example uses inhibited property of input device drivers as a replacement for xinput which does not work under Wayland.

    	button/lid)
    		if echo "$3" | grep -iq "open"; then
    			echo 'LID opened'
    			disabled=0
    		fi
    		if echo "$3" | grep -iq "close"; then
    			echo 'LID closed'
    			disabled=1
    		fi
    		find /sys/devices/platform/i8042/serio* -prune -type d | while IFS= read -r serionumber; do
    			find $serionumber/input/* -prune -type d | while IFS= read -r inputdevicepath; do
    				if grep -q -i -e "keyboard" -e "touchpad" $inputdevicepath/name; then
    					logger "found $(cat $inputdevicepath/name) and set to $disabled"
    					echo $disabled > $inputdevicepath/inhibited
    				fi
    			done
    		done
    	;;

## See also

- acpid homepage
- Gentoo:ACPI#Configuration

Category:

- Power management