OpenLogi

0x8081 · perKeyLighting

Per-key RGB lighting control that stages zone updates through seven HID++ functions and commits a frame with optional non-volatile persistence.

0x8081 is the zone-addressed successor to 0x8080 for keyboards with addressable LEDs. It stages zone colours, then commits the complete frame with frame_end.

Spec: No public Logitech specification. Layout reverse-engineered from Logi Options+ 2.8 (static analysis). Cross-checked: Solaar. Used by: Keyboard lighting.

Function reference

PerKeyLightingFeature implements 0x8081 from feature version 0. All methods are async and return Result<…, Hidpp20Error>.

Methods

FunctionHID++ fnSignatureReturns
get_rgb_zone_presence0(page: ZonePresencePage)[u8; 14]
set_individual_rgb_zones1(zones: &[RgbZone])()
set_consecutive_rgb_zones2(first_zone_id: u8, colors: [Rgb; 5])()
set_consecutive_rgb_zones_delta_5bit3(first_zone_id: u8, packed: [u8; 15])()
set_consecutive_rgb_zones_delta_4bit4(first_zone_id: u8, packed: [u8; 15])()
set_range_rgb_zones5(ranges: &[RgbZoneRange])()
set_rgb_zones_single_value6(color: Rgb, zone_ids: &[u8])()
frame_end7(persistence: FramePersistence, current_frame: u16, frames_till_next_change: u16)()

The individual, range, and single-value setters transmit at most 4, 3, and 13 slice entries. They ignore entries after those limits.

Types

Rgb

Rgb holds one 8-bit value for each colour channel.

FieldTypeDescription
redu8Red channel.
greenu8Green channel.
blueu8Blue channel.

RgbZone

RgbZone assigns one Rgb value to one zone.

FieldTypeDescription
zone_idu8Zone ID. IDs 0x00 and 0xff are rejected as end-of-list sentinels.
colorRgbColour to stage.

RgbZoneRange

RgbZoneRange assigns one colour to an inclusive range.

FieldTypeDescription
first_zone_idu8First included zone ID. Sentinel IDs are rejected.
last_zone_idu8Last included zone ID. Sentinel IDs are rejected.
colorRgbColour to stage across the range.

ZonePresencePage

ZonePresencePage selects one 112-bit presence bitmap page. This non-exhaustive enum has these known variants.

VariantValueDescription
Zones0To1110Zone IDs 0..=111.
Zones112To2231Zone IDs 112..=223.
Zones224To2552Zone IDs 224..=255.

FramePersistence

FramePersistence selects the storage target for frame_end. This non-exhaustive enum has these known variants.

VariantValueDescription
Volatile0Apply the frame in RAM only.
VolatileAndNonVolatile1Apply the frame in RAM and store it in EEPROM.

Events

OpenLogi defines no 0x8081 feature event type. frame_end is a request, not a device event.

Wire format

Function 0 sends a three-byte short payload. Functions 1 through 7 send 16-byte long payloads.

Setter responses repeat accepted request parameters. OpenLogi requires a long response and checks the zone-ID echo for functions 1 through 6.

get_rgb_zone_presence (fn 0)

Request payload: [0x00, page, 0x00]. Byte 0 selects zone-presence information, byte 1 selects the page, and byte 2 is zero padding.

Byte(s)FieldEncodingNotes
0–1response prefixreturned by the deviceOpenLogi does not model these bytes.
2–15zone presence bitmap14 bytes; LSB-first within each byteBit i names zone page_base + i. Options+ 2.8

set_individual_rgb_zones (fn 1)

The request has four four-byte slots. OpenLogi zeroes unused slots.

Byte(s)FieldEncodingNotes
slot × 4zone_idone u8Slots 0..=3; sent IDs cannot be 0x00 or 0xff.
slot × 4 + 1redone u8/
slot × 4 + 2greenone u8/
slot × 4 + 3blueone u8/

The response must be long. OpenLogi verifies every sent zone_id at offsets 0, 4, 8, and 12.

set_consecutive_rgb_zones (fn 2)

The request sets exactly five consecutive zones in full 24-bit RGB.

Byte(s)FieldEncodingNotes
0first_zone_idone u8Sentinel IDs are rejected.
1 + 3 × ired for zone ione u8i is 0..=4.
2 + 3 × igreen for zone ione u8/
3 + 3 × iblue for zone ione u8/

The response must be long. OpenLogi verifies the echoed first_zone_id at byte 0.

set_consecutive_rgb_zones_delta_5bit (fn 3)

The request encodes eight consecutive zones as signed 5-bit channel deltas. The deltas are packed MSB-first by zone and then by channel.

Byte(s)FieldEncodingNotes
0first_zone_idone u8Sentinel IDs are rejected.
1–15packed15 bytesEight groups of three signed 5-bit deltas. OpenLogi transmits these bytes unchanged.

The response must be long. OpenLogi verifies the echoed first_zone_id at byte 0.

set_consecutive_rgb_zones_delta_4bit (fn 4)

The request encodes ten consecutive zones as signed 4-bit channel deltas. The deltas use the high nibble before the low nibble.

Byte(s)FieldEncodingNotes
0first_zone_idone u8Sentinel IDs are rejected.
1–15packed15 bytesTen groups of three signed 4-bit deltas. OpenLogi transmits these bytes unchanged.

The response must be long. OpenLogi verifies the echoed first_zone_id at byte 0.

set_range_rgb_zones (fn 5)

The request has three five-byte range slots. OpenLogi zeroes unused slots.

Byte(s)FieldEncodingNotes
slot × 5first_zone_idone u8Slots 0..=2; sentinel IDs are rejected.
slot × 5 + 1last_zone_idone u8Inclusive range end; sentinel IDs are rejected.
slot × 5 + 2redone u8/
slot × 5 + 3greenone u8/
slot × 5 + 4blueone u8/
15padding0x00The three slots occupy bytes 0–14.

The response must be long. OpenLogi verifies only the first sent first_zone_id at byte 0.

set_rgb_zones_single_value (fn 6)

The request applies one colour to up to 13 selected zones. OpenLogi zeroes unused zone-ID bytes.

Byte(s)FieldEncodingNotes
0redone u8/
1greenone u8/
2blueone u8/
3–15zone_idsup to 13 × u8Sent IDs cannot be 0x00 or 0xff.

The response must be long. OpenLogi verifies the first sent zone_id at byte 3.

frame_end (fn 7)

frame_end commits all staged zone updates. Set both counters to zero for a one-shot update.

Byte(s)FieldEncodingNotes
0persistence0 or 1FramePersistence value.
1–2current_frameBE u16Frame number.
3–4frames_till_next_changeBE u16Frame count before the next change.
5–15padding0x00OpenLogi writes zeroes.

OpenLogi waits for a matching response to function 7. It does not inspect the response payload.

How OpenLogi uses it

LightingMethod::Auto reaches 0x8081 after 0x8070 and 0x8071 fail to provide a complete solid-colour path. LightingMethod::PerKeyV2 selects this path directly.

OpenLogi queries all three presence pages before any write. It skips sentinel IDs 0x00 and 0xff, plus page-three padding above 0xff.

The device writer sends one function-6 request per 13 present zones. It writes the same colour to every present zone and then calls function 7 with Volatile, 0, and 0.

Any failed subwrite prevents frame_end. If 0x8081 is absent or reports no usable zones, Auto falls back to raw 0x8080.

When 0x8071 is present, OpenLogi reads the software-control state before it mutates the device. It claims ALL_CLUSTERS, paints available Static effects as a base, sends the 0x8081 frame, and replays it once after a fresh claim.

A failed write restores the earlier software-control flags. A successful agent write retains its lease and returns control when the agent exits.

A device with 0x8081 but no 0x8071 receives the frame without a software-control claim. The user-facing setting is Keyboard lighting.

The typed wrapper exposes all six zone setters. The production device path uses only set_rgb_zones_single_value, so it provides a whole-keyboard solid colour rather than a user-visible per-zone map.

Open questions

No hardware capture verifies which devices require 0x8071 software control and Static effects for visible 0x8081 paint. Solaar treats per-key paint as a Static sub-mode, while OpenLogi uses that sequence only when 0x8071 exists.

Options+ 2.8 static analysis supports zone echoes for functions 1 through 6. The full multi-range reply contract remains unverified, so OpenLogi checks only the first range start for function 5.

Options+ 2.8 does not inspect the function-7 response payload. OpenLogi likewise accepts any matching function-7 response, pending hardware verification.

Usage (Rust)

use hidpp::{
    device::Device,
    feature::per_key_lighting::{
        FramePersistence, PerKeyLightingFeature, Rgb, RgbZone, ZonePresencePage,
    },
    protocol::v20::Hidpp20Error,
};

async fn stage_two_zones(device: &mut Device) -> Result<(), Hidpp20Error> {
    device.enumerate_features().await?;
    let Some(feature) = device.get_feature::<PerKeyLightingFeature>() else {
        return Ok(());
    };

    let _presence = feature
        .get_rgb_zone_presence(ZonePresencePage::Zones0To111)
        .await?;

    feature
        .set_individual_rgb_zones(&[
            RgbZone {
                zone_id: 1,
                color: Rgb {
                    red: 0xff,
                    green: 0x00,
                    blue: 0x00,
                },
            },
            RgbZone {
                zone_id: 2,
                color: Rgb {
                    red: 0x00,
                    green: 0x00,
                    blue: 0xff,
                },
            },
        ])
        .await?;

    feature.frame_end(FramePersistence::Volatile, 0, 0).await
}

On this page