OpenLogi

0x1982 · backlight

Keyboard backlight configuration, live status, and change events for OpenLogi-supported white-backlight keyboards.

0x1982 controls a keyboard's white, level-adjustable backlight. OpenLogi implements a version-3 typed wrapper and a device-layer control path. The path exposes on/off, automatic brightness, a held brightness level, and battery saving when the keyboard advertises each control.

Spec: No public Logitech specification. Layout reverse-engineered from Logi Options+ 2.8 (static analysis). Cross-checked: Solaar. Used by: Keyboard lighting and On-screen notices.

Function reference

BacklightFeature implements HID++ 0x1982 from version 3. Every asynchronous method returns Result<…, Hidpp20Error>.

Methods

FunctionHID++ fnSignatureReturns
get_backlight_config0(&self)BacklightConfig
set_backlight_config1(&self, config: SetBacklightConfig)()
get_backlight_info2(&self)BacklightInfo
set_backlight_effect3(&self, effect: BacklightEffect)()
EmittingFeature::listenevent(&self)async_channel::Receiver<BacklightEvent>

Types

BacklightConfig

get_backlight_config returns this persistent configuration.

FieldTypeDescription
enabledboolWhether the backlight system is enabled.
optionsBacklightOptionsEnabled flags, capability flags, and retained unknown bits.
modeBacklightModeThe decoded two-bit mode.
effect_listBacklightEffectListThe effects advertised by the keyboard.
current_levelu8The stored manual level.
duration_hands_outu16First fade-out duration, in 5-second units.
duration_hands_inu16Second fade-out duration, in 5-second units.
duration_poweredu16Third fade-out duration, in 5-second units.
duration_not_poweredu16Fourth fade-out duration, in 5-second units. Options+ 2.8 calls it “not powered”; its trigger is unverified.

SetBacklightConfig

set_backlight_config persistently writes this configuration.

FieldTypeDescription
enabledboolThe requested master switch state.
optionsBacklightOptionsOnly WOW, CROWN, and PWR_SAVE are sent.
modeBacklightModeThe mode encoded into request bits 3–4.
effectOption<BacklightEffect>None sends 0xff and leaves the effect unchanged.
current_levelu8The requested manual level.
duration_hands_outu16First fade-out duration, in 5-second units.
duration_hands_inu16Second fade-out duration, in 5-second units.
duration_poweredu16Third fade-out duration, in 5-second units.
duration_not_poweredu16Fourth fade-out duration, in 5-second units.

BacklightInfo

get_backlight_info returns live state and out-of-box durations.

FieldTypeDescription
nb_levelsu8Number of selectable levels, including level 0.
current_levelu8The currently shown level.
statusBacklightStatusThe current operating state.
effectBacklightEffectThe currently applied effect.
oob_duration_hands_outu16First out-of-box fade-out duration, in 5-second units.
oob_duration_hands_inu16Second out-of-box fade-out duration, in 5-second units.
oob_duration_poweredu16Third out-of-box fade-out duration, in 5-second units.
oob_duration_not_poweredu16Fourth out-of-box fade-out duration, in 5-second units.

BacklightMode

VariantValueDescription
None0No selected mode.
Automatic1The ambient-light sensor selects the level.
TemporaryManual2The keyboard's backlight keys select a temporary level.
PermanentManual3Software selects and holds a level.

BacklightMode is #[non_exhaustive]. The low-level setter accepts every listed variant. OpenLogi's device layer does not write TemporaryManual; it substitutes Automatic before a device-layer write.

BacklightEffect

VariantValueDescription
Static0Static effect.
None1None effect.
Breathing2Breathing effect.
Contrast3Contrast effect.
Reaction4Reaction effect.
Random5Random effect.
Waves6Waves effect.

BacklightEffect is #[non_exhaustive].

BacklightStatus

VariantValueDescription
DisabledBySoftware0Software disabled the backlight.
DisabledByCriticalBattery1The battery is critically low.
AlsAutomatic2The ambient-light sensor controls the level.
AlsSaturated3The sensor reports enough ambient light to keep the LEDs off.
TemporaryManual4The keyboard backlight keys set the level.
PermanentManual5Software set the level.

BacklightStatus is #[non_exhaustive].

BacklightOptions

The wrapper retains unknown bits when it reads this u16 bitfield. A configuration write sends only the three writable low bits.

FlagBitDescription
WOW0Enable the WOW power-on effect.
CROWN1Enable the CROWN touch effect.
PWR_SAVE2Enable low-battery backlight saving.
WOW_SUPPORTED8The keyboard advertises WOW support.
CROWN_SUPPORTED9The keyboard advertises CROWN support.
PWR_SAVE_SUPPORTED10The keyboard advertises battery-saving support.
AUTO_MODE_SUPPORTED11The keyboard advertises automatic-mode support.
TEMP_MANUAL_SUPPORTED12The keyboard advertises temporary-manual support.
PERM_MANUAL_SUPPORTED13The keyboard advertises permanent-manual support.

BacklightEffectList

This u16 bitfield retains unknown bits when it is read.

FlagBitDescription
STATIC0Static effect.
NONE1None effect.
BREATHING2Breathing effect.
CONTRAST3Contrast effect.
REACTION4Reaction effect.
RANDOM5Random effect.
WAVES6Waves effect.

Events

BacklightFeature implements EmittingFeature<BacklightEvent>. The event source accepts unsolicited reports at function 0 only.

VariantPayloadDescription
InfoChangedBacklightInfoUpdateA backlight status, level, or effect update.

BacklightInfoUpdate has nb_levels: u8, current_level: u8, status: BacklightStatus, and effect: BacklightEffect.

Wire format

Getter requests use a 3-byte short payload of zeroes. set_backlight_config uses a 16-byte long payload. Every multi-byte field below is LE.

OpenLogi requires a long reply for functions 0 and 2. It rejects a short reply rather than zero-filling a configuration that can later be written back. It awaits but ignores response payloads for functions 1 and 3.

get_backlight_config (fn 0)

Request: [0x00, 0x00, 0x00].

ByteFieldNotes
0enabledBit 0 is the master switch.
1–2options and modeLE u16. Bits 0–2 are writable options. OpenLogi decodes bits 3–4 as mode. Bit 5 is unresolved.
3–4effect_listLE u16 BacklightEffectList.
5current_levelStored manual level.
6–7duration_hands_outLE u16, in 5-second units.
8–9duration_hands_inLE u16, in 5-second units.
10–11duration_poweredLE u16, in 5-second units.
12–13duration_not_poweredLE u16, in 5-second units. Options+ 2.8.
14–15unknownNot modeled or read by OpenLogi.

set_backlight_config (fn 1)

The request is a 16-byte long payload.

ByteFieldNotes
0enabled0 disables and 1 enables.
1options and mode(options & 0x07) | (mode << 3). Only WOW, CROWN, and PWR_SAVE are written. Bit 5 is written as zero.
2effectEffect value, or 0xff for None.
3current_levelRequested manual level.
4–5duration_hands_outLE u16, in 5-second units.
6–7duration_hands_inLE u16, in 5-second units.
8–9duration_poweredLE u16, in 5-second units.
10–11duration_not_poweredLE u16, in 5-second units. Options+ 2.8.
12–15paddingOpenLogi writes zero. The available evidence assigns no meaning.

get_backlight_info (fn 2)

Request: [0x00, 0x00, 0x00].

ByteFieldNotes
0nb_levelsNumber of selectable levels, including 0.
1current_levelCurrent level.
2statusBacklightStatus value.
3effectBacklightEffect value.
4–5oob_duration_hands_outLE u16, in 5-second units.
6–7oob_duration_hands_inLE u16, in 5-second units.
8–9oob_duration_poweredLE u16, in 5-second units.
10–11oob_duration_not_poweredLE u16, in 5-second units. Options+ 2.8.
12–15unknownNot modeled or read by OpenLogi.

set_backlight_effect (fn 3)

Request: [effect, 0x00, 0x00]. Byte 0 is a BacklightEffect value. The effect is temporary and stored in RAM, not persistent storage.

Event: backlightInfoEvent (fn 0)

OpenLogi decodes event function 0 as BacklightEvent::InfoChanged. The available evidence establishes the first four payload bytes. OpenLogi ignores the remainder.

ByteFieldNotes
0nb_levelsNumber of selectable levels.
1current_levelCurrent level after the update.
2statusBacklightStatus value.
3effectBacklightEffect value.
4–15unknownOpenLogi ignores these bytes.

How OpenLogi uses it

OpenLogi reads configuration and live information before it shows the Backlight card or accepts a change. It derives automatic brightness from automatic and permanent-manual capability bits. It enables level selection only at feature version 3 or later, with more than one level. It enables battery saving only when PWR_SAVE_SUPPORTED is set.

Each accepted change uses whole-configuration read-modify-write. OpenLogi preserves the effect with 0xff, all four durations, and other options read from the keyboard. Since v0.8.14, this includes duration_not_powered and rejects short configuration and information replies. It reads back the configuration and information after a write, then rejects a change that the keyboard did not apply.

When automatic brightness is turned off, OpenLogi holds the level from the live information reply. A device-layer on/off or battery-saving write maps TemporaryManual to Automatic. The configuration is in keyboard non-volatile memory, so OpenLogi has no exit-time restore step.

An inventory-owned listener recognizes function-0 broadcasts. It increments the keyboard settings revision for a refresh and forwards the current level to the on-screen indicator. The indicator is visible for 1,500 ms; see On-screen notices.

Open questions

Options+ 2.8 treats option-byte bits 3–5 as a three-bit mode. Solaar and OpenLogi decode bits 3–4 only. OpenLogi retains bit 5 in BacklightOptions after reading, but writes it as zero. No hardware capture or public feature specification decides which interpretation is correct.

Options+ 2.8 calls the fourth duration “not powered.” The byte ownership is verified, but the condition that applies this duration is not hardware-verified. The available evidence also does not establish the layouts of feature versions 0–2.

Usage (Rust)

use hidpp::{
    feature::backlight::{BacklightFeature, SetBacklightConfig},
    protocol::v20::Hidpp20Error,
};

async fn enable(feature: &BacklightFeature) -> Result<(), Hidpp20Error> {
    let config = feature.get_backlight_config().await?;

    feature
        .set_backlight_config(SetBacklightConfig {
            enabled: true,
            options: config.options,
            mode: config.mode,
            effect: None,
            current_level: config.current_level,
            duration_hands_out: config.duration_hands_out,
            duration_hands_in: config.duration_hands_in,
            duration_powered: config.duration_powered,
            duration_not_powered: config.duration_not_powered,
        })
        .await
}

On this page