OpenLogi

0x1990 · illumination

Device illumination control for power, brightness, colour temperature, selectable levels, and a version-1 effective brightness limit.

Controls a device light through independent brightness and colour-temperature controls. OpenLogi uses this feature for Litra Glow and Litra Beam lights that answer HID++ 0x1990; see Litra lights.

Spec: Logitech HID++ 2.0 — illumination. Cross-checked: Logi Options+ 2.8 (static analysis). Used by: Litra lights.

Function reference

IlluminationFeature (0x1990) exposes the following methods.

Methods

FunctionHID++ fnSignatureReturns
get_illumination0()IlluminationState
set_illumination1(state: IlluminationState)()
get_brightness_info2()ControlInfo
get_brightness3()u16
set_brightness4(brightness: u16)()
get_brightness_levels5(start_index: u8)LevelConfig
set_brightness_levels6(levels: &SetLevels)()
get_color_temperature_info7()ControlInfo
get_color_temperature8()u16
set_color_temperature9(color_temperature: u16)()
get_color_temperature_levels10(start_index: u8)LevelConfig
set_color_temperature_levels11(levels: &SetLevels)()
get_brightness_effective_max12()u16
listenevent()Receiver<IlluminationEvent>

All methods except listen are async and return Result<…, Hidpp20Error>. listen is provided by EmittingFeature.

Types

ControlCapabilities

ControlInfo::capabilities describes one control. Unknown bits are retained.

FlagBitDescription
HAS_EVENTS0The control sends change notifications.
HAS_LINEAR_LEVELS1The control supports a linear level table.
HAS_NON_LINEAR_LEVELS2The control supports an explicit level table.
HAS_DYNAMIC_MAXIMUM3Brightness can have a dynamic effective maximum.

ControlInfo

Values are lumens for brightness and kelvin for colour temperature.

FieldTypeDescription
capabilitiesControlCapabilitiesControl capability bits.
minu16Lowest accepted value. A control with min == max has one setting.
maxu16Highest accepted value.
resolutionu16Valid values follow (value - min) % resolution == 0.
max_levelsu8Maximum non-linear levels. 0 means unsupported.

LevelConfig

A getter returns one linear table or one non-linear page.

VariantFieldsDescription
Linearmin: u16, max: u16, step: u16Inclusive range with even spacing.
NonLinearstart_index: u8, level_count: u8, values: Vec<u16>A page of 0–7 explicit values and the total table size.

SetLevels

A setter accepts a reset, a linear table, or the whole non-linear table.

VariantFieldsDescription
Reset—Restores factory level configuration.
Linearmin: u16, max: u16, step: u16Writes a linear table.
NonLinearvalues: Vec<u16>Writes 1–15 values. OpenLogi splits more than seven values into pages.

SetLevels::NonLinear validates the count. It does not validate order, range, or spacing.

IlluminationState

VariantValueDescription
Off0Illumination is off.
On1Illumination is on.

BrightnessClampedSource

VariantValueDescription
Unknown0The source is unknown.
HidPlusPlus1A HID++ brightness request caused the clamp.
Button2A hardware button caused the clamp.
Other(u8)other valuesAn unmodelled source byte.

Events

VariantPayloadDescription
IlluminationChangedIlluminationStateThe light changed on or off.
BrightnessChangedu16Brightness changed in lumens.
ColorTemperatureChangedu16Colour temperature changed in kelvin.
BrightnessEffectiveMaxChangedu16Effective maximum changed in lumens. 0 means no limit.
BrightnessClampedsource, brightnessBrightness was limited to the effective maximum.

The last two events are version-1 protocol additions.

Wire format

Short requests have a three-byte payload. All multi-byte fields are BE. get_*_info requires a long reply of at least eight payload bytes. Each get_*_levels call requires the full 16-byte long payload. OpenLogi rejects short replies for those functions.

get_illumination (fn 0)

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

ByteFieldNotes
0stateBit 0: 0 = Off; 1 = On.

set_illumination (fn 1)

Request: [state, 0x00, 0x00], where state is 0 or 1.

The response is an acknowledgement. OpenLogi does not inspect a response payload.

get_brightness_info (fn 2) and get_color_temperature_info (fn 7)

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

BytesFieldNotes
0capabilitiesControlCapabilities bitfield.
1–2minBE u16.
3–4maxBE u16.
5–6resolutionBE u16.
7max_levelsLow nibble only.

get_brightness (fn 3), get_color_temperature (fn 8), and get_brightness_effective_max (fn 12)

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

BytesFieldNotes
0–1valueBE u16; for fn 12, 0 means no effective limit.

Function 12 is a version-1 function. It applies only when brightness advertises HAS_DYNAMIC_MAXIMUM.

set_brightness (fn 4) and set_color_temperature (fn 9)

Request: [value_hi, value_lo, 0x00], where the value is a BE u16.

The response is an acknowledgement. OpenLogi does not inspect a response payload.

get_brightness_levels (fn 5) and get_color_temperature_levels (fn 10)

Request: [start_index << 4, 0x00, 0x00]. start_index must be at most 0x0f.

BytesFieldNotes
0flagsBit 0 selects a linear table. Bits 7–5 give a non-linear page count.
1page informationBits 7–4 are start_index. Bits 3–0 are total level_count.
2–3min or value 0BE u16. Linear tables use min.
4–5max or value 1BE u16. Linear tables use max.
6–7step or value 2BE u16. Linear tables use step.
8–15values 3–6Non-linear values only, as BE u16 pairs.

set_brightness_levels (fn 6) and set_color_temperature_levels (fn 11)

OpenLogi sends each payload as a 16-byte long request.

VariantByte 0Byte 1Bytes 2–7Notes
Reset0x020x00zeroesBit 1 requests reset. Other bytes are ignored.
Linear0x010x00min, max, and step as BE u16Bit 0 selects a linear table.
NonLinearpage value count in bits 7–5page start index and full table countup to seven BE u16 valuesOne request is sent per page.

The non-linear full table count is derived from values.len(). It cannot disagree with a page count.

Events

Sub-idEventPayload
0IlluminationChangedByte 0, bit 0 is the state.
1BrightnessChangedBytes 0–1: BE brightness in lumens.
2ColorTemperatureChangedBytes 0–1: BE colour temperature in kelvin.
3BrightnessEffectiveMaxChangedBytes 0–1: BE maximum in lumens.
4BrightnessClampedByte 0 is source; bytes 1–2 are BE clamped brightness.

How OpenLogi uses it

The Litra driver resolves 0x1990 from the light node's root feature. Resolution and the first state read have a one-second deadline. It reads brightness and temperature information, power, and supported values.

The driver calls fn 12 only when the resolved feature version is at least 1 and brightness has HAS_DYNAMIC_MAXIMUM. A nonzero limit below the static maximum becomes the reported brightness limit. A limit of 0 or at least the static maximum has no effect.

Before a Litra write, OpenLogi reads the current state. It sends power, brightness, or temperature only when that control differs. It then reads the written control back. The agent keeps a live HID++ link, re-reads on notifications, and publishes changes made on the light.

The agent reapplies saved light settings after a reconnect, a save, and camera-use transitions. The Litra lights page describes the user-facing behaviour. This reference documents the HID++ path only.

The generic IlluminationFeature does not retain the negotiated feature version. Its fn-12 method remains callable without an internal version or capability check. The Litra device path applies both checks.

Open questions

Logi Options+ static analysis confirms five illumination event payload shapes. It does not recover the event sub-id jump-table order. OpenLogi maps sub-ids 0–4 in the order shown above. A hardware capture should confirm that mapping.

Usage (Rust)

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

// `device` is already created for a HID++ channel and device index.
device.enumerate_features().await?;
if let Some(feature) = device.get_feature::<IlluminationFeature>() {
    let info = feature.get_brightness_info().await?;
    if info.capabilities.contains(ControlCapabilities::HAS_DYNAMIC_MAXIMUM) {
        // The caller must also know that the negotiated feature version is at least 1.
        let limit = feature.get_brightness_effective_max().await?;
        println!("effective limit: {limit}");
    }

    feature.set_illumination(IlluminationState::On).await?;
    let events = feature.listen();
    while let Ok(event) = events.recv().await {
        println!("{event:?}");
    }
}

On this page