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
| Function | HID++ fn | Signature | Returns |
|---|---|---|---|
get_capabilities | 0 | () | DisableableKeys |
get_disabled_keys | 1 | () | DisableableKeys |
set_disabled_keys | 2 | (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.
| Field | Bit | Description |
|---|---|---|
CAPS_LOCK | 1 << 0 | Caps Lock. |
NUM_LOCK | 1 << 1 | Num Lock. |
SCROLL_LOCK | 1 << 2 | Scroll Lock. |
INSERT | 1 << 3 | Insert. |
WINDOWS | 1 << 4 | Windows or Start key. |
Events
OpenLogi exposes no event type or listen() method for 0x4521.
| Event | Payload | Description |
|---|---|---|
| Disabled-key change | DisableableKeys | Logi 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.
| Byte | Field | Notes |
|---|---|---|
| 0 | keys | DisableableKeys bitmap of keys software may disable. |
| 1–15 | — | OpenLogi ignores these bytes. |
get_disabled_keys (fn 1)
Request: 0x00, 0x00, 0x00.
| Byte | Field | Notes |
|---|---|---|
| 0 | keys | Active disabled-key bitmap. |
| 1–15 | — | OpenLogi ignores these bytes. |
set_disabled_keys (fn 2)
Request:
| Byte | Field | Notes |
|---|---|---|
| 0 | keys | Complete replacement bitmap. 0x00 re-enables every supported key. |
| 1–2 | — | Padding. OpenLogi sends 0x00. |
Response:
| Byte | Field | Notes |
|---|---|---|
| 0 | keys | The 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.
| Byte | Field | Notes |
|---|---|---|
| 0 | keys | New 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:?}");
}