OpenLogi

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

FunctionHID++ fnSignatureReturns
get_count0()u8
get_cid_info1(index: u8)CidInfo
get_cid_reporting2(cid: ControlId)CidReporting
set_cid_reporting3(cid: ControlId, change: CidReportingChange)CidReportingChangeEcho
get_capabilities4()ReprogControlsCapabilities
reset_all_cid_report_settings5()()
listenevent()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

TypeInner typeDescription
ControlIdu16HID++ control ID.
TaskIdu16Default task associated with a control.
GroupMasku8g1..g8 membership mask from get_cid_info.

CidInfo

FieldTypeDescription
cidControlIdControl ID.
task_idTaskIdDefault task ID.
flagsCidFlagsCapability and classification flags.
positionu8Device-reported physical-position value.
groupu8Device-reported group number.
group_maskGroupMaskGroup-membership mask.

CidFlags

FlagBitDescription
MOUSE1 << 0Mouse or pointer control.
FUNCTION_KEY1 << 1Keyboard function key.
HOTKEY1 << 2Hotkey.
FN_TOGGLE1 << 3Fn-toggle control.
REPROGRAMMABLE1 << 4Reprogrammable control.
DIVERTABLE1 << 5Temporarily divertable control.
PERSISTENTLY_DIVERTABLE1 << 6Persistently divertable control.
VIRTUAL_CONTROL1 << 7Virtual, not physical, control.
RAW_XY1 << 8Supports raw XY reporting.
FORCE_RAW_XY1 << 9Supports force-raw-XY reporting.
ANALYTICS_KEY_EVENTS1 << 10Supports analytics key events.
RAW_WHEEL1 << 11Supports raw-wheel reporting.

CidFlags::raw() returns the combined u16. The is_* and supports_* methods expose the corresponding named flags.

CidReporting

FieldTypeDescription
cidControlIdControl whose state was read.
divertedboolTemporary diversion state.
persistently_divertedboolPersistent diversion state.
force_raw_xyboolForce-raw-XY state.
raw_xyboolRaw-XY state.
remapOption<ControlId>Target control, or None when the device reports 0x0000.
analytics_key_eventsboolAnalytics-key-event state.
raw_wheelboolRaw-wheel state.

CidReportingChange

Each Option<bool> changes its setting only when it is Some. None leaves that setting unchanged.

FieldTypeDescription
divertedOption<bool>Temporary-diversion change.
persistently_divertedOption<bool>Persistent-diversion change.
force_raw_xyOption<bool>Force-raw-XY change.
raw_xyOption<bool>Raw-XY change.
remapOption<ControlId>Target control. None sends 0x0000 and keeps the current remap.
analytics_key_eventsOption<bool>Analytics-key-event change.
raw_wheelOption<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

FieldTypeDescription
cidControlIdControl ID in the response.
divertedOption<bool>Echoed temporary-diversion change.
persistently_divertedOption<bool>Echoed persistent-diversion change.
force_raw_xyOption<bool>Echoed force-raw-XY change.
raw_xyOption<bool>Echoed raw-XY change.
remapOption<ControlId>Echoed remap target, if nonzero.
analytics_key_eventsOption<bool>Echoed analytics-key-event change.
raw_wheelOption<bool>Echoed raw-wheel change.

ReprogControlsCapabilities

FieldTypeDescription
reset_all_cid_report_settingsboolreset_all_cid_report_settings is available.

Events

ReprogControlsFeature implements EmittingFeature<ReprogControlsEvent>.

VariantEvent fnFieldsDescription
DivertedButtons0[ControlId; 4]Current diverted controls.
DivertedRawMouseXy1dx: i16, dy: i16Raw pointer delta.
AnalyticsKeyEvents2[AnalyticsKeyEvent; 5]Five packed analytics entries.
DivertedRawWheel4resolution, periods, delta_verticalRaw 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].

ByteFieldNotes
0countNumber 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)FieldNotes
0–1cidControlId as BE u16.
2–3task_idTaskId as BE u16.
4primary flagsCidFlags bits 0–7.
5positionDevice-reported position.
6groupDevice-reported group.
7group_maskGroupMask bits g1..g8.
8additional flagsCidFlags 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)FieldNotes
0–1cidBE u16.
2 bit 0diverted1 means temporary diversion.
2 bit 2persistently_diverted1 means persistent diversion.
2 bit 4raw_xy1 means raw XY.
2 bit 6force_raw_xy1 means force raw XY.
3–4remapBE u16 target. 0x0000 means the control maps to itself and becomes None.
5 bit 0analytics_key_events1 enables analytics events.
5 bit 2raw_wheel1 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)FieldNotes
0–1cidBE u16.
2 bit 1 / bit 0diverted valid / valueThe value changes only when valid is 1.
2 bit 3 / bit 2persistently_diverted valid / valueThe value changes only when valid is 1.
2 bit 5 / bit 4raw_xy valid / valueThe value changes only when valid is 1.
2 bit 7 / bit 6force_raw_xy valid / valueThe value changes only when valid is 1.
3–4remapBE u16. 0x0000 keeps the previous remap. Write this cid to clear a remap.
5 bit 1 / bit 0analytics_key_events valid / valueThe value changes only when valid is 1.
5 bit 3 / bit 2raw_wheel valid / valueThe 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.

ByteFieldNotes
0 bit 0reset_all_cid_report_settings1 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)FieldNotes
0–1slot 0BE ControlId; 0x0000 means no control in this slot.
2–3slot 1BE ControlId.
4–5slot 2BE ControlId.
6–7slot 3BE ControlId.
8–15—No documented field. OpenLogi ignores these bytes.

DivertedRawMouseXy (event fn 1)

Byte(s)FieldNotes
0–1dxBE i16 horizontal delta.
2–3dyBE 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.

OffsetFieldNotes
0–1cidBE ControlId.
2eventDevice-defined event code.

Byte 15 has no documented field. OpenLogi ignores it.

DivertedRawWheel (event fn 4)

Byte(s)FieldNotes
0 bits 7–5—No public meaning found. OpenLogi ignores these bits. Options+ 2.8.
0 bit 4resolution0 = Low; 1 = High. Options+ 2.8.
0 bits 3–0periodsU4 period count. Options+ 2.8.
1–2delta_verticalBE 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(())
}

On this page