Skip to main content

Power and the lid

COMPOSITOR.power asks systemd-logind to suspend, hibernate and the like, tells the config when the system comes back, and lets the config handle the laptop lid instead of logind. Only the TTY backend talks to logind; in a nested session these calls do nothing.

Who handles the lid​

logind reads the lid switch itself and acts on it as logind.conf says (HandleLidSwitch=suspend by default). ShojiWM hears of the lid through libinput at the same moment, in no defined order. So a config that only listens to onLidSwitch cannot keep logind from suspending, and may not run before it does.

To decide what the lid does, the config takes it from logind:

COMPOSITOR.power.takeOver({lid: true});

ShojiWM then holds a handle-lid-switch inhibitor, logind leaves the lid alone, and closing it does nothing until the config does something. The inhibitor is a file descriptor: if ShojiWM goes away, logind has the lid back at once. Declare it again on every reload, as a config does everything in its setup: a reloaded config that does not, or that fails to load, gives the lid back to logind.

The default config's lid policy​

The default config takes the lid and sets what closing it does the way Windows and KDE Plasma do, once for battery and once for external power. It is ordinary config code, bindLidPolicy in packages/config/src/lid-policy.ts, so copy or change it as you like:

bindLidPolicy({
onBattery: 'logind',
onExternalPower: 'logind',
});

"logind" does what logind.conf says in the situation (HandleLidSwitch, HandleLidSwitchExternalPower, and HandleLidSwitchDocked while another display is on), so out of the box the lid behaves as before. Set an action to choose yourself:

bindLidPolicy({
onBattery: 'hibernate',
onExternalPower: 'suspend',
onSleep: async () => {
// Bring up the screen locker before the machine sleeps.
},
onResume: ({lidClosed}) => {
// Back from a suspend or hibernation.
},
});
OptionDefaultMeaning
onBattery"logind"What closing the lid does on battery.
onExternalPower"logind"What closing the lid does on external power.
onSleepnoneCalled before the policy puts the machine to sleep (suspend, hibernate, hybrid-sleep, suspend-then-hibernate, sleep) with {action, externalPower, externalDisplay}. A returned promise is waited for, at most sleepCallbackTimeoutMs; if it throws, the machine sleeps anyway.
onResumenoneCalled after every resume, whoever started the sleep, with {lidClosed}.
internalPanelOfftrueSwitch the built-in panel off (DPMS) while the lid is closed and another display is on, and back on when the lid opens or that display goes.
holdoffMs30000For this long after the policy starts and after a resume, closing the lid does nothing (logind's HoldoffTimeoutSec).
sleepCallbackTimeoutMs5000The longest wait for onSleep (logind's InhibitDelayMaxSec).

An action is a logind action, "ignore", "logind", or a function that receives {externalPower, externalDisplay} and decides itself. "Another display" is any enabled output that is not a built-in panel (eDP, LVDS, DSI) or a headless output. Unplugging the last other display while the lid is shut runs the action for the new situation, as logind does. bindLidPolicy returns a function that gives the lid back.

Broken lid switches​

Some laptops' lid switches stick at "closed". A policy that suspends whenever the switch says closed would put such a machine to sleep right after boot, and again right after every resume. The policy only runs an action when the lid moves:

  • A lid that is closed when the switch comes up (at startup, or back from another VT) or when a reloaded config starts does nothing: the lid event arrives with initial: true. Only the built-in panel follows it, so a laptop booted shut on a dock keeps its panel dark.
  • A resume restarts the holdoff, and a lid that still reads closed after it runs nothing until it moves again.
  • libinput reports the lid open as soon as a key on the built-in keyboard is pressed, so a stuck switch recovers when someone types.

For a machine libinput does not know about, a local quirk tells libinput not to trust the switch's state at startup (unreliable), or to write "open" back to the kernel on the first key press (write_open), which also corrects logind:

# /etc/libinput/local-overrides.quirks
[My laptop's lid switch]
MatchName=*Lid Switch*
MatchDMIModalias=dmi:*svnVENDOR:pnMODEL:*
AttrLidSwitchReliability=write_open

Power actions​

COMPOSITOR.power.suspend();
COMPOSITOR.power.hibernate();
COMPOSITOR.power.perform('suspend-then-hibernate');

perform takes logind's action names: suspend, hibernate, hybrid-sleep, suspend-then-hibernate, sleep (whichever sleep logind is set up for, or a suspend before systemd 256), lock (asks every session's screen locker to lock, as loginctl lock-sessions), poweroff, reboot and halt. They are not interactive: when polkit would ask for a password, logind refuses and the refusal is logged.

State and resume​

COMPOSITOR.power.onStateChange(({externalPower, logindLidActions}) => {
console.log(externalPower ? 'on the charger' : 'on battery', logindLidActions);
});
COMPOSITOR.power.onResume(({lidClosed}) => {
// Back from a suspend or hibernation, whoever started it.
});

COMPOSITOR.power.state holds the latest state: externalPower (whether the machine runs on external power, decided as systemd does: an adapter online, or no adapter at all) and logindLidActions (logind's three lid settings). Either is undefined until known. The state arrives on a scheduler tick, like the lid, and before the lid event of the same tick.

onResume fires after every resume. lidClosed is what the lid switch reported last, which a stuck switch may still say is closed. Whether the resume or the lid opening comes first is not defined, so make both handlers bring things to the current state rather than depend on the order.

In a Rust config​

The same API, in COMPOSITOR.power:

COMPOSITOR.power.take_over(PowerTakeOverOptions { lid: true });
COMPOSITOR.power.on_resume(|resume| println!("resumed, lid {:?}", resume.lid_closed));
let power = COMPOSITOR.power.state(); // a signal

take_over, suspend, hibernate and perform match the TypeScript methods, and state() is a signal holding the latest state (None before the first report). Events are delivered at once rather than on a scheduler tick.

The Rust example config has the same lid policy in src/shojiwm_rs/examples/default_config/lid_policy.rs, with on_battery, on_external_power, on_sleep and on_resume. A Rust config runs synchronously, so on_sleep returns before the machine sleeps rather than being waited for.