0x1982 · backlight

键盘背光控制，实现版本为 3。get_backlight_config（function 0）读取完整的持久化配置——启用状态、当前 BacklightMode、已启用与支持的 BacklightOptions、支持的特效、手动亮度级别（0–7），以及三段以 5 秒为单位的淡出时长（无手检测、手在检测区、外接电源）。set_backlight_config（function 1）将这些值写入非易失性存储。get_backlight_info（function 2）返回实时状态及出厂默认时长。set_backlight_effect（function 3）临时应用一种特效——仅存于 RAM，不持久化。

• BacklightMode —— None（未选择模式，线值为 0）、Automatic（亮度跟随环境光传感器）、TemporaryManual（由物理背光键调节，软件无法设置）、PermanentManual（由软件设置）。
• BacklightEffect —— Static、None、Breathing、Contrast、Reaction、Random、Waves；BacklightEffectList 位字段报告设备所支持的特效。
• BacklightOptions —— 可写选项标志（WOW、CROWN、PWR_SAVE）及只读能力位（报告设备支持的模式与选项）。
• BacklightStatus（来自 get_backlight_info）—— DisabledBySoftware、DisabledByCriticalBattery、AlsAutomatic、AlsSaturated、TemporaryManual、PermanentManual。
• BacklightEvent::InfoChanged —— 用户调整背光时推送；携带 BacklightInfoUpdate（nb_levels、current_level、status、effect）。

规格： Logitech HID++ 2.0 —— backlight。用于： 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);
    }
}