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
| Function | HID++ fn | Signature | Returns |
|---|---|---|---|
get_illumination | 0 | () | IlluminationState |
set_illumination | 1 | (state: IlluminationState) | () |
get_brightness_info | 2 | () | ControlInfo |
get_brightness | 3 | () | u16 |
set_brightness | 4 | (brightness: u16) | () |
get_brightness_levels | 5 | (start_index: u8) | LevelConfig |
set_brightness_levels | 6 | (levels: &SetLevels) | () |
get_color_temperature_info | 7 | () | ControlInfo |
get_color_temperature | 8 | () | u16 |
set_color_temperature | 9 | (color_temperature: u16) | () |
get_color_temperature_levels | 10 | (start_index: u8) | LevelConfig |
set_color_temperature_levels | 11 | (levels: &SetLevels) | () |
get_brightness_effective_max | 12 | () | u16 |
listen | event | () | 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.
| Flag | Bit | Description |
|---|---|---|
HAS_EVENTS | 0 | The control sends change notifications. |
HAS_LINEAR_LEVELS | 1 | The control supports a linear level table. |
HAS_NON_LINEAR_LEVELS | 2 | The control supports an explicit level table. |
HAS_DYNAMIC_MAXIMUM | 3 | Brightness can have a dynamic effective maximum. |
ControlInfo
Values are lumens for brightness and kelvin for colour temperature.
| Field | Type | Description |
|---|---|---|
capabilities | ControlCapabilities | Control capability bits. |
min | u16 | Lowest accepted value. A control with min == max has one setting. |
max | u16 | Highest accepted value. |
resolution | u16 | Valid values follow (value - min) % resolution == 0. |
max_levels | u8 | Maximum non-linear levels. 0 means unsupported. |
LevelConfig
A getter returns one linear table or one non-linear page.
| Variant | Fields | Description |
|---|---|---|
Linear | min: u16, max: u16, step: u16 | Inclusive range with even spacing. |
NonLinear | start_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.
| Variant | Fields | Description |
|---|---|---|
Reset | — | Restores factory level configuration. |
Linear | min: u16, max: u16, step: u16 | Writes a linear table. |
NonLinear | values: 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
| Variant | Value | Description |
|---|---|---|
Off | 0 | Illumination is off. |
On | 1 | Illumination is on. |
BrightnessClampedSource
| Variant | Value | Description |
|---|---|---|
Unknown | 0 | The source is unknown. |
HidPlusPlus | 1 | A HID++ brightness request caused the clamp. |
Button | 2 | A hardware button caused the clamp. |
Other(u8) | other values | An unmodelled source byte. |
Events
| Variant | Payload | Description |
|---|---|---|
IlluminationChanged | IlluminationState | The light changed on or off. |
BrightnessChanged | u16 | Brightness changed in lumens. |
ColorTemperatureChanged | u16 | Colour temperature changed in kelvin. |
BrightnessEffectiveMaxChanged | u16 | Effective maximum changed in lumens. 0 means no limit. |
BrightnessClamped | source, brightness | Brightness 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]
| Byte | Field | Notes |
|---|---|---|
| 0 | state | Bit 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]
| Bytes | Field | Notes |
|---|---|---|
| 0 | capabilities | ControlCapabilities bitfield. |
| 1–2 | min | BE u16. |
| 3–4 | max | BE u16. |
| 5–6 | resolution | BE u16. |
| 7 | max_levels | Low nibble only. |
get_brightness (fn 3), get_color_temperature (fn 8), and get_brightness_effective_max (fn 12)
Request: [0x00, 0x00, 0x00]
| Bytes | Field | Notes |
|---|---|---|
| 0–1 | value | BE 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.
| Bytes | Field | Notes |
|---|---|---|
| 0 | flags | Bit 0 selects a linear table. Bits 7–5 give a non-linear page count. |
| 1 | page information | Bits 7–4 are start_index. Bits 3–0 are total level_count. |
| 2–3 | min or value 0 | BE u16. Linear tables use min. |
| 4–5 | max or value 1 | BE u16. Linear tables use max. |
| 6–7 | step or value 2 | BE u16. Linear tables use step. |
| 8–15 | values 3–6 | Non-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.
| Variant | Byte 0 | Byte 1 | Bytes 2–7 | Notes |
|---|---|---|---|---|
Reset | 0x02 | 0x00 | zeroes | Bit 1 requests reset. Other bytes are ignored. |
Linear | 0x01 | 0x00 | min, max, and step as BE u16 | Bit 0 selects a linear table. |
NonLinear | page value count in bits 7–5 | page start index and full table count | up to seven BE u16 values | One 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-id | Event | Payload |
|---|---|---|
| 0 | IlluminationChanged | Byte 0, bit 0 is the state. |
| 1 | BrightnessChanged | Bytes 0–1: BE brightness in lumens. |
| 2 | ColorTemperatureChanged | Bytes 0–1: BE colour temperature in kelvin. |
| 3 | BrightnessEffectiveMaxChanged | Bytes 0–1: BE maximum in lumens. |
| 4 | BrightnessClamped | Byte 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:?}");
}
}