0x1982 · backlight

Keyboard backlight control, implemented at version 3. get_backlight_config (function 0) reads the full persistent configuration: enabled state, active BacklightMode, supported and enabled BacklightOptions, supported effects, manual brightness level (0–7), and three fade-out durations in 5-second units (hands-out, hands-in, externally-powered). set_backlight_config (function 1) writes those values back to non-volatile memory. get_backlight_info (function 2) returns live status plus out-of-box (factory-default) durations. set_backlight_effect (function 3) applies an effect temporarily, stored in RAM only, not persisted.

• BacklightMode — None (no mode selected, wire value 0), Automatic (level follows the ambient-light sensor), TemporaryManual (adjusted by the physical backlight keys; cannot be set by software), PermanentManual (set by software).
• BacklightEffect — Static, None, Breathing, Contrast, Reaction, Random, Waves; the BacklightEffectList bitfield reports which effects the device supports.
• BacklightOptions — writable flags (WOW, CROWN, PWR_SAVE) plus read-only capability bits that report which modes and options the device supports.
• BacklightStatus (from get_backlight_info) — DisabledBySoftware, DisabledByCriticalBattery, AlsAutomatic, AlsSaturated, TemporaryManual, PermanentManual.
• BacklightEvent::InfoChanged — pushed whenever the user adjusts the backlight; carries BacklightInfoUpdate (nb_levels, current_level, status, effect).

Spec: Logitech HID++ 2.0 — backlight. Used by: Typed wrapper in openlogi-hidpp.

Function reference

The BacklightFeature wrapper (0x1982) exposes:

Methods

All async methods return Result<…, Hidpp20Error>. listen is synchronous and returns a channel receiver.

Types

BacklightConfig

Configuration returned by get_backlight_config.

SetBacklightConfig

Configuration written by set_backlight_config.

BacklightInfo

Live status and factory defaults returned by get_backlight_info.

BacklightMode

The backlight level-adjustment mode.

BacklightEffect

A predefined backlight effect.

BacklightStatus

The current backlight operational status.

BacklightOptions

Backlight options and device capability bits from get_backlight_config. Low bits are active options; high bits are read-only capability flags. The 2-bit mode field is exposed separately as BacklightMode.

BacklightEffectList

Bitmask of predefined effects the device supports, from get_backlight_config.

Events

The feature implements EmittingFeature<BacklightEvent>; call listen() to receive a Receiver<BacklightEvent>.

BacklightInfoUpdate

Payload carried by BacklightEvent::InfoChanged.

Wire format

Getter requests carry a 3-byte zero payload; the setter uses a 16-byte long payload. All multi-byte fields are little-endian. All methods return Result<_, Hidpp20Error>.

get_backlight_config (fn 0)

Request: [0x00, 0x00, 0x00] (no parameters)

Response (extend_payload(), 16 bytes):

set_backlight_config (fn 1)

Request (call_long, 16-byte payload):

Response: no meaningful return bytes (acknowledgement only).

get_backlight_info (fn 2)

Request: [0x00, 0x00, 0x00] (no parameters)

Response (extend_payload(), 16 bytes):

set_backlight_effect (fn 3)

Request: [effect, 0x00, 0x00] — byte 0 = BacklightEffect value.

Response: no meaningful return bytes.

Event: backlightInfoEvent (fn 0, sub-id 0)

Emitted by the device whenever the user adjusts the backlight. The 16-byte event payload is parsed as BacklightInfoUpdate:

Usage (Rust)

use hidpp::{
    device::Device,
    feature::backlight::{BacklightEffect, BacklightFeature, BacklightMode, SetBacklightConfig},
};

// mut device: Device, already created via Device::new(channel, index)
device.enumerate_features().await?;
if let Some(feat) = device.get_feature::<BacklightFeature>() {
    // Read the current persistent configuration.
    let config = feat.get_backlight_config().await?;
    println!("enabled={}, level={}", config.enabled, config.current_level);

    // Write a new configuration: enable at level 4, permanent-manual mode.
    feat.set_backlight_config(SetBacklightConfig {
        enabled: true,
        options: config.options,
        mode: BacklightMode::PermanentManual,
        effect: Some(BacklightEffect::Breathing),
        current_level: 4,
        duration_hands_out: config.duration_hands_out,
        duration_hands_in: config.duration_hands_in,
        duration_powered: config.duration_powered,
    })
    .await?;

    // Apply an effect temporarily (RAM only, not persisted).
    feat.set_backlight_effect(BacklightEffect::Static).await?;

    // Listen for hardware-generated backlight changes.
    let rx = feat.listen();
    if let Ok(event) = rx.recv().await {
        println!("backlight event: {:?}", event);
    }
}