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
| Function | HID++ fn | Signature | Returns |
|---|---|---|---|
get_backlight_config | 0 | (&self) | BacklightConfig |
set_backlight_config | 1 | (&self, config: SetBacklightConfig) | () |
get_backlight_info | 2 | (&self) | BacklightInfo |
set_backlight_effect | 3 | (&self, effect: BacklightEffect) | () |
EmittingFeature::listen | event | (&self) | async_channel::Receiver<BacklightEvent> |
Types
BacklightConfig
get_backlight_config returns this persistent configuration.
| Field | Type | Description |
|---|---|---|
enabled | bool | Whether the backlight system is enabled. |
options | BacklightOptions | Enabled flags, capability flags, and retained unknown bits. |
mode | BacklightMode | The decoded two-bit mode. |
effect_list | BacklightEffectList | The effects advertised by the keyboard. |
current_level | u8 | The stored manual level. |
duration_hands_out | u16 | First fade-out duration, in 5-second units. |
duration_hands_in | u16 | Second fade-out duration, in 5-second units. |
duration_powered | u16 | Third fade-out duration, in 5-second units. |
duration_not_powered | u16 | Fourth 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.
| Field | Type | Description |
|---|---|---|
enabled | bool | The requested master switch state. |
options | BacklightOptions | Only WOW, CROWN, and PWR_SAVE are sent. |
mode | BacklightMode | The mode encoded into request bits 3–4. |
effect | Option<BacklightEffect> | None sends 0xff and leaves the effect unchanged. |
current_level | u8 | The requested manual level. |
duration_hands_out | u16 | First fade-out duration, in 5-second units. |
duration_hands_in | u16 | Second fade-out duration, in 5-second units. |
duration_powered | u16 | Third fade-out duration, in 5-second units. |
duration_not_powered | u16 | Fourth fade-out duration, in 5-second units. |
BacklightInfo
get_backlight_info returns live state and out-of-box durations.
| Field | Type | Description |
|---|---|---|
nb_levels | u8 | Number of selectable levels, including level 0. |
current_level | u8 | The currently shown level. |
status | BacklightStatus | The current operating state. |
effect | BacklightEffect | The currently applied effect. |
oob_duration_hands_out | u16 | First out-of-box fade-out duration, in 5-second units. |
oob_duration_hands_in | u16 | Second out-of-box fade-out duration, in 5-second units. |
oob_duration_powered | u16 | Third out-of-box fade-out duration, in 5-second units. |
oob_duration_not_powered | u16 | Fourth out-of-box fade-out duration, in 5-second units. |
BacklightMode
| Variant | Value | Description |
|---|---|---|
None | 0 | No selected mode. |
Automatic | 1 | The ambient-light sensor selects the level. |
TemporaryManual | 2 | The keyboard's backlight keys select a temporary level. |
PermanentManual | 3 | Software 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
| Variant | Value | Description |
|---|---|---|
Static | 0 | Static effect. |
None | 1 | None effect. |
Breathing | 2 | Breathing effect. |
Contrast | 3 | Contrast effect. |
Reaction | 4 | Reaction effect. |
Random | 5 | Random effect. |
Waves | 6 | Waves effect. |
BacklightEffect is #[non_exhaustive].
BacklightStatus
| Variant | Value | Description |
|---|---|---|
DisabledBySoftware | 0 | Software disabled the backlight. |
DisabledByCriticalBattery | 1 | The battery is critically low. |
AlsAutomatic | 2 | The ambient-light sensor controls the level. |
AlsSaturated | 3 | The sensor reports enough ambient light to keep the LEDs off. |
TemporaryManual | 4 | The keyboard backlight keys set the level. |
PermanentManual | 5 | Software 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.
| Flag | Bit | Description |
|---|---|---|
WOW | 0 | Enable the WOW power-on effect. |
CROWN | 1 | Enable the CROWN touch effect. |
PWR_SAVE | 2 | Enable low-battery backlight saving. |
WOW_SUPPORTED | 8 | The keyboard advertises WOW support. |
CROWN_SUPPORTED | 9 | The keyboard advertises CROWN support. |
PWR_SAVE_SUPPORTED | 10 | The keyboard advertises battery-saving support. |
AUTO_MODE_SUPPORTED | 11 | The keyboard advertises automatic-mode support. |
TEMP_MANUAL_SUPPORTED | 12 | The keyboard advertises temporary-manual support. |
PERM_MANUAL_SUPPORTED | 13 | The keyboard advertises permanent-manual support. |
BacklightEffectList
This u16 bitfield retains unknown bits when it is read.
| Flag | Bit | Description |
|---|---|---|
STATIC | 0 | Static effect. |
NONE | 1 | None effect. |
BREATHING | 2 | Breathing effect. |
CONTRAST | 3 | Contrast effect. |
REACTION | 4 | Reaction effect. |
RANDOM | 5 | Random effect. |
WAVES | 6 | Waves effect. |
Events
BacklightFeature implements EmittingFeature<BacklightEvent>. The event source accepts unsolicited reports at function 0 only.
| Variant | Payload | Description |
|---|---|---|
InfoChanged | BacklightInfoUpdate | A 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].
| Byte | Field | Notes |
|---|---|---|
| 0 | enabled | Bit 0 is the master switch. |
| 1–2 | options and mode | LE u16. Bits 0–2 are writable options. OpenLogi decodes bits 3–4 as mode. Bit 5 is unresolved. |
| 3–4 | effect_list | LE u16 BacklightEffectList. |
| 5 | current_level | Stored manual level. |
| 6–7 | duration_hands_out | LE u16, in 5-second units. |
| 8–9 | duration_hands_in | LE u16, in 5-second units. |
| 10–11 | duration_powered | LE u16, in 5-second units. |
| 12–13 | duration_not_powered | LE u16, in 5-second units. Options+ 2.8. |
| 14–15 | unknown | Not modeled or read by OpenLogi. |
set_backlight_config (fn 1)
The request is a 16-byte long payload.
| Byte | Field | Notes |
|---|---|---|
| 0 | enabled | 0 disables and 1 enables. |
| 1 | options and mode | (options & 0x07) | (mode << 3). Only WOW, CROWN, and PWR_SAVE are written. Bit 5 is written as zero. |
| 2 | effect | Effect value, or 0xff for None. |
| 3 | current_level | Requested manual level. |
| 4–5 | duration_hands_out | LE u16, in 5-second units. |
| 6–7 | duration_hands_in | LE u16, in 5-second units. |
| 8–9 | duration_powered | LE u16, in 5-second units. |
| 10–11 | duration_not_powered | LE u16, in 5-second units. Options+ 2.8. |
| 12–15 | padding | OpenLogi writes zero. The available evidence assigns no meaning. |
get_backlight_info (fn 2)
Request: [0x00, 0x00, 0x00].
| Byte | Field | Notes |
|---|---|---|
| 0 | nb_levels | Number of selectable levels, including 0. |
| 1 | current_level | Current level. |
| 2 | status | BacklightStatus value. |
| 3 | effect | BacklightEffect value. |
| 4–5 | oob_duration_hands_out | LE u16, in 5-second units. |
| 6–7 | oob_duration_hands_in | LE u16, in 5-second units. |
| 8–9 | oob_duration_powered | LE u16, in 5-second units. |
| 10–11 | oob_duration_not_powered | LE u16, in 5-second units. Options+ 2.8. |
| 12–15 | unknown | Not 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.
| Byte | Field | Notes |
|---|---|---|
| 0 | nb_levels | Number of selectable levels. |
| 1 | current_level | Current level after the update. |
| 2 | status | BacklightStatus value. |
| 3 | effect | BacklightEffect value. |
| 4–15 | unknown | OpenLogi 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
}