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
| Function | HID++ fn | Signature | Returns |
|---|---|---|---|
get_rgb_zone_presence | 0 | (page: ZonePresencePage) | [u8; 14] |
set_individual_rgb_zones | 1 | (zones: &[RgbZone]) | () |
set_consecutive_rgb_zones | 2 | (first_zone_id: u8, colors: [Rgb; 5]) | () |
set_consecutive_rgb_zones_delta_5bit | 3 | (first_zone_id: u8, packed: [u8; 15]) | () |
set_consecutive_rgb_zones_delta_4bit | 4 | (first_zone_id: u8, packed: [u8; 15]) | () |
set_range_rgb_zones | 5 | (ranges: &[RgbZoneRange]) | () |
set_rgb_zones_single_value | 6 | (color: Rgb, zone_ids: &[u8]) | () |
frame_end | 7 | (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.
| Field | Type | Description |
|---|---|---|
red | u8 | Red channel. |
green | u8 | Green channel. |
blue | u8 | Blue channel. |
RgbZone
RgbZone assigns one Rgb value to one zone.
| Field | Type | Description |
|---|---|---|
zone_id | u8 | Zone ID. IDs 0x00 and 0xff are rejected as end-of-list sentinels. |
color | Rgb | Colour to stage. |
RgbZoneRange
RgbZoneRange assigns one colour to an inclusive range.
| Field | Type | Description |
|---|---|---|
first_zone_id | u8 | First included zone ID. Sentinel IDs are rejected. |
last_zone_id | u8 | Last included zone ID. Sentinel IDs are rejected. |
color | Rgb | Colour to stage across the range. |
ZonePresencePage
ZonePresencePage selects one 112-bit presence bitmap page.
This non-exhaustive enum has these known variants.
| Variant | Value | Description |
|---|---|---|
Zones0To111 | 0 | Zone IDs 0..=111. |
Zones112To223 | 1 | Zone IDs 112..=223. |
Zones224To255 | 2 | Zone IDs 224..=255. |
FramePersistence
FramePersistence selects the storage target for frame_end.
This non-exhaustive enum has these known variants.
| Variant | Value | Description |
|---|---|---|
Volatile | 0 | Apply the frame in RAM only. |
VolatileAndNonVolatile | 1 | Apply 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) | Field | Encoding | Notes |
|---|---|---|---|
| 0–1 | response prefix | returned by the device | OpenLogi does not model these bytes. |
| 2–15 | zone presence bitmap | 14 bytes; LSB-first within each byte | Bit 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) | Field | Encoding | Notes |
|---|---|---|---|
slot × 4 | zone_id | one u8 | Slots 0..=3; sent IDs cannot be 0x00 or 0xff. |
slot × 4 + 1 | red | one u8 | / |
slot × 4 + 2 | green | one u8 | / |
slot × 4 + 3 | blue | one 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) | Field | Encoding | Notes |
|---|---|---|---|
| 0 | first_zone_id | one u8 | Sentinel IDs are rejected. |
1 + 3 × i | red for zone i | one u8 | i is 0..=4. |
2 + 3 × i | green for zone i | one u8 | / |
3 + 3 × i | blue for zone i | one 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) | Field | Encoding | Notes |
|---|---|---|---|
| 0 | first_zone_id | one u8 | Sentinel IDs are rejected. |
| 1–15 | packed | 15 bytes | Eight 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) | Field | Encoding | Notes |
|---|---|---|---|
| 0 | first_zone_id | one u8 | Sentinel IDs are rejected. |
| 1–15 | packed | 15 bytes | Ten 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) | Field | Encoding | Notes |
|---|---|---|---|
slot × 5 | first_zone_id | one u8 | Slots 0..=2; sentinel IDs are rejected. |
slot × 5 + 1 | last_zone_id | one u8 | Inclusive range end; sentinel IDs are rejected. |
slot × 5 + 2 | red | one u8 | / |
slot × 5 + 3 | green | one u8 | / |
slot × 5 + 4 | blue | one u8 | / |
| 15 | padding | 0x00 | The 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) | Field | Encoding | Notes |
|---|---|---|---|
| 0 | red | one u8 | / |
| 1 | green | one u8 | / |
| 2 | blue | one u8 | / |
| 3–15 | zone_ids | up to 13 × u8 | Sent 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) | Field | Encoding | Notes |
|---|---|---|---|
| 0 | persistence | 0 or 1 | FramePersistence value. |
| 1–2 | current_frame | BE u16 | Frame number. |
| 3–4 | frames_till_next_change | BE u16 | Frame count before the next change. |
| 5–15 | padding | 0x00 | OpenLogi 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
}