0x1990 · illumination

Controls the illumination light of a device, with independent brightness (in Lumens) and color_temperature (in Kelvin) axes. Both axes share the same shape: an info query (get_{brightness,color_temperature}_info → ControlInfo), a current-value getter/setter, and a paginated level-list getter/setter. get_illumination / set_illumination toggle the light on or off as a whole.

Feature version 1 adds get_brightness_effective_max — a dynamic ceiling that may be lower than the static maximum — plus two events: BrightnessEffectiveMaxChanged and BrightnessClamped (carrying a BrightnessClampedSource that identifies whether a HID++ request or a hardware button triggered the clamp).

• ControlInfo — capabilities flags (HAS_EVENTS, HAS_LINEAR_LEVELS, HAS_NON_LINEAR_LEVELS, HAS_DYNAMIC_MAXIMUM), min, max, resolution, max_levels.
• LevelConfig — Linear { min, max, step } or NonLinear { start_index, level_count, values }.
• IlluminationState — On / Off.
• Events — IlluminationChanged, BrightnessChanged, ColorTemperatureChanged, BrightnessEffectiveMaxChanged, BrightnessClamped.

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

Function reference

The IlluminationFeature wrapper (0x1990) exposes:

Methods

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

Types

ControlCapabilities

Capabilities of an illumination control (brightness or color temperature), from get_brightness_info / get_color_temperature_info.

ControlInfo

Capabilities and range of an illumination control. Values are in Lumens for brightness and Kelvin for color temperature.

LevelConfig

The level configuration of an illumination control, returned by get_brightness_levels and get_color_temperature_levels.

SetLevels

A level configuration to write with set_brightness_levels / set_color_temperature_levels.

IlluminationState

On/off state of the illumination.

BrightnessClampedSource

What caused a brightness clamp event.

Events

IlluminationFeature implements EmittingFeature<IlluminationEvent> and broadcasts variants via listen():

Wire format

Requests use a 3-byte short payload unless noted; responses are parsed from the 16-byte extended payload. All multi-byte fields are big-endian.

get_illumination (fn 0)

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

Response (byte → field):

set_illumination (fn 1)

Request: [state, 0x00, 0x00] — state is IlluminationState as u8 (0 = Off, 1 = On).

Response: empty (acknowledgement only).

get_brightness_info (fn 2) / get_color_temperature_info (fn 7)

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

Response (byte → field):

get_brightness (fn 3) / get_color_temperature (fn 8) / get_brightness_effective_max (fn 12)

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

Response (byte → field):

set_brightness (fn 4) / set_color_temperature (fn 9)

Request: [value_hi, value_lo, 0x00] — big-endian u16.

Response: empty.

get_brightness_levels (fn 5) / get_color_temperature_levels (fn 10)

Request: [start_index << 4, 0x00, 0x00] — start_index in the high nibble of byte 0 (must be ≤ 0x0f).

Response (byte → field):

set_brightness_levels (fn 6) / set_color_temperature_levels (fn 11)

Uses call_long with a 16-byte payload from SetLevels::to_payload():

Events

Events are received as unsolicited messages; the sub-id (low nibble of the message's function byte) selects the event:

Usage (Rust)

use hidpp::{device::Device, feature::illumination::{IlluminationFeature, IlluminationState, SetLevels}};

// device: &mut Device, already created via Device::new(channel, index)
device.enumerate_features().await?;
if let Some(feat) = device.get_feature::<IlluminationFeature>() {
    // Turn illumination on
    feat.set_illumination(IlluminationState::On).await?;

    // Read brightness range, then set to halfway point
    let info = feat.get_brightness_info().await?;
    let mid = info.min + (info.max - info.min) / 2;
    feat.set_brightness(mid).await?;

    // Subscribe to events
    let rx = feat.listen();
    while let Ok(event) = rx.recv().await {
        println!("{event:?}");
    }
}