0x1B04 · specialKeysMSEButtons
Enumerate programmable controls, change their reporting state, and receive diverted button, pointer, analytics, and raw-wheel events.
specialKeysMSEButtons (0x1b04) describes programmable physical and virtual
controls on mice and keyboards. It enumerates buttons, function keys, and
hotkeys. Host software can divert a control, set persistent diversion, change
its reporting streams, or select a remap target.
OpenLogi registers this feature as ReprogControls5. Its typed Rust wrapper is
ReprogControlsFeature. 0x1b04 is the newer counterpart to
0x1b00 · reprogControls.
Spec: Logitech HID++ 2.0 — specialKeysMseButtons (v2). Cross-checked: Logi Options+ 2.8 (static analysis), Solaar. Used by: Remap buttons.
Function reference
ReprogControlsFeature implements 0x1b04.
Methods
| Function | HID++ fn | Signature | Returns |
|---|---|---|---|
get_count | 0 | () | u8 |
get_cid_info | 1 | (index: u8) | CidInfo |
get_cid_reporting | 2 | (cid: ControlId) | CidReporting |
set_cid_reporting | 3 | (cid: ControlId, change: CidReportingChange) | CidReportingChangeEcho |
get_capabilities | 4 | () | ReprogControlsCapabilities |
reset_all_cid_report_settings | 5 | () | () |
listen | event | () | async_channel::Receiver<ReprogControlsEvent> |
The first six methods are async. They return Result<…, Hidpp20Error>.
listen is the synchronous EmittingFeature trait method.
Types
ControlId, TaskId, and GroupMask
| Type | Inner type | Description |
|---|---|---|
ControlId | u16 | HID++ control ID. |
TaskId | u16 | Default task associated with a control. |
GroupMask | u8 | g1..g8 membership mask from get_cid_info. |
CidInfo
| Field | Type | Description |
|---|---|---|
cid | ControlId | Control ID. |
task_id | TaskId | Default task ID. |
flags | CidFlags | Capability and classification flags. |
position | u8 | Device-reported physical-position value. |
group | u8 | Device-reported group number. |
group_mask | GroupMask | Group-membership mask. |
CidFlags
| Flag | Bit | Description |
|---|---|---|
MOUSE | 1 << 0 | Mouse or pointer control. |
FUNCTION_KEY | 1 << 1 | Keyboard function key. |
HOTKEY | 1 << 2 | Hotkey. |
FN_TOGGLE | 1 << 3 | Fn-toggle control. |
REPROGRAMMABLE | 1 << 4 | Reprogrammable control. |
DIVERTABLE | 1 << 5 | Temporarily divertable control. |
PERSISTENTLY_DIVERTABLE | 1 << 6 | Persistently divertable control. |
VIRTUAL_CONTROL | 1 << 7 | Virtual, not physical, control. |
RAW_XY | 1 << 8 | Supports raw XY reporting. |
FORCE_RAW_XY | 1 << 9 | Supports force-raw-XY reporting. |
ANALYTICS_KEY_EVENTS | 1 << 10 | Supports analytics key events. |
RAW_WHEEL | 1 << 11 | Supports raw-wheel reporting. |
CidFlags::raw() returns the combined u16. The is_* and supports_*
methods expose the corresponding named flags.
CidReporting
| Field | Type | Description |
|---|---|---|
cid | ControlId | Control whose state was read. |
diverted | bool | Temporary diversion state. |
persistently_diverted | bool | Persistent diversion state. |
force_raw_xy | bool | Force-raw-XY state. |
raw_xy | bool | Raw-XY state. |
remap | Option<ControlId> | Target control, or None when the device reports 0x0000. |
analytics_key_events | bool | Analytics-key-event state. |
raw_wheel | bool | Raw-wheel state. |
CidReportingChange
Each Option<bool> changes its setting only when it is Some. None leaves
that setting unchanged.
| Field | Type | Description |
|---|---|---|
diverted | Option<bool> | Temporary-diversion change. |
persistently_diverted | Option<bool> | Persistent-diversion change. |
force_raw_xy | Option<bool> | Force-raw-XY change. |
raw_xy | Option<bool> | Raw-XY change. |
remap | Option<ControlId> | Target control. None sends 0x0000 and keeps the current remap. |
analytics_key_events | Option<bool> | Analytics-key-event change. |
raw_wheel | Option<bool> | Raw-wheel change. |
To clear a remap, set remap: Some(cid) for the control being written. Do not
use None: 0x0000 means keep the prior remap for set_cid_reporting.
CidReportingChangeEcho
| Field | Type | Description |
|---|---|---|
cid | ControlId | Control ID in the response. |
diverted | Option<bool> | Echoed temporary-diversion change. |
persistently_diverted | Option<bool> | Echoed persistent-diversion change. |
force_raw_xy | Option<bool> | Echoed force-raw-XY change. |
raw_xy | Option<bool> | Echoed raw-XY change. |
remap | Option<ControlId> | Echoed remap target, if nonzero. |
analytics_key_events | Option<bool> | Echoed analytics-key-event change. |
raw_wheel | Option<bool> | Echoed raw-wheel change. |
ReprogControlsCapabilities
| Field | Type | Description |
|---|---|---|
reset_all_cid_report_settings | bool | reset_all_cid_report_settings is available. |
Events
ReprogControlsFeature implements EmittingFeature<ReprogControlsEvent>.
| Variant | Event fn | Fields | Description |
|---|---|---|---|
DivertedButtons | 0 | [ControlId; 4] | Current diverted controls. |
DivertedRawMouseXy | 1 | dx: i16, dy: i16 | Raw pointer delta. |
AnalyticsKeyEvents | 2 | [AnalyticsKeyEvent; 5] | Five packed analytics entries. |
DivertedRawWheel | 4 | resolution, periods, delta_vertical | Raw vertical wheel delta. |
AnalyticsKeyEvent contains cid: ControlId and a device-defined event: u8.
RawWheelResolution is Low = 0 or High = 1. periods is U4, an unsigned
four-bit value.
Wire format
The tables use logical HID++ payload bytes. OpenLogi sends 3-byte short requests except for fn 1 and fn 3, which use 16-byte long requests. Readers use an extended 16-byte response view and ignore bytes without a modeled field.
get_count (fn 0)
Request: [0x00, 0x00, 0x00].
| Byte | Field | Notes |
|---|---|---|
| 0 | count | Number of control-table entries. |
| 1–15 | — | No field is parsed by OpenLogi. |
get_cid_info (fn 1)
Request: long payload with index in byte 0. OpenLogi writes 0x00 in bytes
1–15.
| Byte(s) | Field | Notes |
|---|---|---|
| 0–1 | cid | ControlId as BE u16. |
| 2–3 | task_id | TaskId as BE u16. |
| 4 | primary flags | CidFlags bits 0–7. |
| 5 | position | Device-reported position. |
| 6 | group | Device-reported group. |
| 7 | group_mask | GroupMask bits g1..g8. |
| 8 | additional flags | CidFlags bits 8–11. OpenLogi shifts this byte left by 8. |
| 9–15 | — | No documented field. OpenLogi ignores these bytes. |
get_cid_reporting (fn 2)
Request: [cid_hi, cid_lo, 0x00], where cid_hi,cid_lo are the ControlId as
BE u16.
| Byte(s) | Field | Notes |
|---|---|---|
| 0–1 | cid | BE u16. |
| 2 bit 0 | diverted | 1 means temporary diversion. |
| 2 bit 2 | persistently_diverted | 1 means persistent diversion. |
| 2 bit 4 | raw_xy | 1 means raw XY. |
| 2 bit 6 | force_raw_xy | 1 means force raw XY. |
| 3–4 | remap | BE u16 target. 0x0000 means the control maps to itself and becomes None. |
| 5 bit 0 | analytics_key_events | 1 enables analytics events. |
| 5 bit 2 | raw_wheel | 1 enables raw-wheel events. |
| 6–15 | — | No documented field. OpenLogi ignores these bytes. |
set_cid_reporting (fn 3)
OpenLogi sends a 16-byte long request. It sets bytes 6–15 to 0x00.
| Byte(s) | Field | Notes |
|---|---|---|
| 0–1 | cid | BE u16. |
| 2 bit 1 / bit 0 | diverted valid / value | The value changes only when valid is 1. |
| 2 bit 3 / bit 2 | persistently_diverted valid / value | The value changes only when valid is 1. |
| 2 bit 5 / bit 4 | raw_xy valid / value | The value changes only when valid is 1. |
| 2 bit 7 / bit 6 | force_raw_xy valid / value | The value changes only when valid is 1. |
| 3–4 | remap | BE u16. 0x0000 keeps the previous remap. Write this cid to clear a remap. |
| 5 bit 1 / bit 0 | analytics_key_events valid / value | The value changes only when valid is 1. |
| 5 bit 3 / bit 2 | raw_wheel valid / value | The value changes only when valid is 1. |
| 6–15 | — | OpenLogi writes fixed zero padding. |
The response has the same modeled bytes 0–5. CidReportingChangeEcho exposes a
boolean value only when its valid bit is set. It maps a zero remap field to
None and ignores bytes 6–15.
get_capabilities (fn 4)
Request: [0x00, 0x00, 0x00]. This function is available on version 6 devices.
Older firmware can return InvalidFunctionId.
| Byte | Field | Notes |
|---|---|---|
| 0 bit 0 | reset_all_cid_report_settings | 1 permits fn 5. Options+ 2.8. |
| 0 bits 1–7 | — | Unknown bits. OpenLogi ignores them. |
| 1–15 | — | No field is parsed by OpenLogi. |
reset_all_cid_report_settings (fn 5)
Request: [0x00, 0x00, 0x00]. Call this only when fn 4 reports support. It
resets every control's diversion and remap state. OpenLogi returns () and
does not parse a response body.
Events
OpenLogi accepts unsolicited messages only when the software ID is 0. It
does not model the unrecognized bytes shown below.
DivertedButtons (event fn 0)
| Byte(s) | Field | Notes |
|---|---|---|
| 0–1 | slot 0 | BE ControlId; 0x0000 means no control in this slot. |
| 2–3 | slot 1 | BE ControlId. |
| 4–5 | slot 2 | BE ControlId. |
| 6–7 | slot 3 | BE ControlId. |
| 8–15 | — | No documented field. OpenLogi ignores these bytes. |
DivertedRawMouseXy (event fn 1)
| Byte(s) | Field | Notes |
|---|---|---|
| 0–1 | dx | BE i16 horizontal delta. |
| 2–3 | dy | BE i16 vertical delta. |
| 4–15 | — | No documented field. OpenLogi ignores these bytes. |
AnalyticsKeyEvents (event fn 2)
The event contains five 3-byte entries in bytes 0–14.
| Offset | Field | Notes |
|---|---|---|
| 0–1 | cid | BE ControlId. |
| 2 | event | Device-defined event code. |
Byte 15 has no documented field. OpenLogi ignores it.
DivertedRawWheel (event fn 4)
| Byte(s) | Field | Notes |
|---|---|---|
| 0 bits 7–5 | — | No public meaning found. OpenLogi ignores these bits. Options+ 2.8. |
| 0 bit 4 | resolution | 0 = Low; 1 = High. Options+ 2.8. |
| 0 bits 3–0 | periods | U4 period count. Options+ 2.8. |
| 1–2 | delta_vertical | BE i16 vertical delta. Options+ 2.8. |
| 3–15 | — | No documented field. OpenLogi ignores these bytes. |
How OpenLogi uses it
OpenLogi uses 0x1b04 for mouse control capture and keyboard host switching.
It enumerates a control before arming it. It requires the relevant CidFlags,
such as DIVERTABLE, RAW_XY, or RAW_WHEEL.
Before a capture write, OpenLogi reads CidReporting and records it. It writes
only the reporting fields the session owns. It carries the read remap target
through its change, so it does not clear an existing remap.
OpenLogi re-arms captured controls after a reconnect. It restores them on normal stop and rolls them back after an arming failure. A restore failure becomes a pending restore that OpenLogi retries on the current device channel.
Since v0.8.15, a wheel-hold binding enables raw_wheel only for a control with
RAW_WHEEL. Its teardown clears raw_wheel on stop, reconnect failure, and
arming failure. It does not restore a pre-existing raw_wheel: true state. A
control without that flag remains a plain diverted click.
Raw-wheel reports contain no source CID. OpenLogi assigns a report to the earliest pressed wheel-hold control. It drops a report with no held control or an unscalable high-resolution multiplier.
The host-switch session consumes DivertedButtons and AnalyticsKeyEvents.
It does not treat raw XY or raw-wheel events as host changes. OpenLogi does not
call the global fn 5 reset, because that reset can clear settings it does not
own.
Open questions
Logi Options+ 2.8 handles an unmatched fn 3 response with a nonzero software ID as a diverted-key state change. OpenLogi filters nonzero software IDs from its event paths. It therefore does not publish that late or foreign response.
The static evidence does not show how often this response occurs on hardware.
OpenLogi still returns a normal, matched fn 3 response to its caller as
CidReportingChangeEcho. The conditions and frequency need a device trace.
Usage (Rust)
use hidpp::{
device::Device,
feature::{
EmittingFeature,
reprog_controls::{CidReportingChange, ReprogControlsFeature},
},
protocol::v20::Hidpp20Error,
};
async fn divert_first_control(mut device: Device) -> Result<(), Hidpp20Error> {
device.enumerate_features().await?;
let Some(feature) = device.get_feature::<ReprogControlsFeature>() else {
return Ok(());
};
for index in 0..feature.get_count().await? {
let info = feature.get_cid_info(index).await?;
if !info.flags.is_divertable() {
continue;
}
let before = feature.get_cid_reporting(info.cid).await?;
let _events = feature.listen();
feature
.set_cid_reporting(
info.cid,
CidReportingChange {
diverted: Some(true),
..Default::default()
},
)
.await?;
// Restore the reporting bit this example changed before returning.
feature
.set_cid_reporting(
info.cid,
CidReportingChange {
diverted: Some(before.diverted),
..Default::default()
},
)
.await?;
break;
}
Ok(())
}