OpenLogi

0x4521 · disableKeys

Read a keyboard's fixed disabled-key mask and replace the complete mask for supported lock and system keys.

DisableKeys controls a fixed set of lock and system keys. It reads the supported and active masks, then replaces the complete active mask.

Spec: Logitech HID++ 2.0 — disableKeys. Cross-checked: Logi Options+ 2.8 (static analysis), Solaar. Used by: Device inventory change hints since #1940. Agent, configuration, and GUI controls since #993.

Function reference

DisableKeysFeature is creatable for feature version 0.

Methods

FunctionHID++ fnSignatureReturns
get_capabilities0()DisableableKeys
get_disabled_keys1()DisableableKeys
set_disabled_keys2(keys: DisableableKeys)DisableableKeys

Every method is async and returns Result<…, Hidpp20Error>.

Types

DisableableKeys

DisableableKeys is a retained u8 bitfield. OpenLogi uses it for both supported and currently disabled keys.

FieldBitDescription
CAPS_LOCK1 << 0Caps Lock.
NUM_LOCK1 << 1Num Lock.
SCROLL_LOCK1 << 2Scroll Lock.
INSERT1 << 3Insert.
WINDOWS1 << 4Windows or Start key.

Events

OpenLogi exposes no event type or listen() method for 0x4521.

EventPayloadDescription
Disabled-key changeDisableableKeysLogi Options+ 2.8 treats byte 0 as the new mask. Options+ 2.8

Wire format

The three functions use 3-byte short requests. OpenLogi normalizes each reply to 16 bytes and reads only byte 0.

get_capabilities (fn 0)

Request: 0x00, 0x00, 0x00.

ByteFieldNotes
0keysDisableableKeys bitmap of keys software may disable.
1–15—OpenLogi ignores these bytes.

get_disabled_keys (fn 1)

Request: 0x00, 0x00, 0x00.

ByteFieldNotes
0keysActive disabled-key bitmap.
1–15—OpenLogi ignores these bytes.

set_disabled_keys (fn 2)

Request:

ByteFieldNotes
0keysComplete replacement bitmap. 0x00 re-enables every supported key.
1–2—Padding. OpenLogi sends 0x00.

Response:

ByteFieldNotes
0keysThe device echo parsed as DisableableKeys.
1–15—OpenLogi ignores these bytes.

Disabled-key change report (fn 2)

Logi Options+ 2.8 handles a nonempty asynchronous report at function 2. It interprets byte 0 as the new disabled-key bitmap.

ByteFieldNotes
0keysNew DisableableKeys bitmap. Options+ 2.8
1–15—Layout beyond byte 0 is not established.

How OpenLogi uses it

OpenLogi v0.8.15 exposed only the typed wrapper. PR #1940 added inventory subscription to unsolicited function-2 reports. The report increments settings_revision and requests authoritative reconciliation. OpenLogi treats the payload as a change hint, not a decoded mask.

set_disabled_keys is a whole-set replacement, not a per-key patch. A caller that changes one key should read the current mask, modify it, write the complete mask, and inspect the returned mask.

PR #993 added agent-owned reads and writes plus a capability-gated GUI card. Its device writer rejects unknown requested bits and unsupported known bits. It preserves advertised unknown disabled bits, then confirms the complete supported mask by reading the device again.

The app persists only confirmed known keys. An uncertain write invalidates the displayed snapshot until a fresh read succeeds. The agent schedules the latest confirmed policy without overtaking a newer request. Configured policy is reapplied after discovery, reconnect, and wake with bounded confirmation retries. See Disabled keys configuration for user behavior.

Open questions

Logi Options+ 2.8 handles an asynchronous function-2 report, but no public specification or hardware capture confirms the full report layout. OpenLogi therefore re-reads the setting instead of trusting the payload. The #993 integration was not revalidated on physical hardware after its October 23 recovery update.

Usage (Rust)

use hidpp::{
    device::Device,
    feature::disable_keys::{DisableKeysFeature, DisableableKeys},
};

// `device` is a discovered HID++ device.
device.enumerate_features().await?;
if let Some(feature) = device.get_feature::<DisableKeysFeature>() {
    let current = feature.get_disabled_keys().await?;
    let wanted = current | DisableableKeys::CAPS_LOCK;
    let accepted = feature.set_disabled_keys(wanted).await?;

    println!("accepted disabled-key mask: {accepted:?}");
}

On this page