0x1B04 · specialKeysMSEButtons

SpecialKeysMSEButtons (also called ReprogControlsV4) enumerates every physical and virtual control on a device — buttons, function keys, and hotkeys — and lets host software divert or remap them. getCount reports the number of entries in the control table; getCidInfo returns one row at a time, including the control's default TaskId, its CidFlags capability bits, and its group membership. getCidReporting / setCidReporting read and write the active reporting state for a given ControlId.

When a control is diverted the device stops sending its default HID report and emits HID++ events instead. Four event kinds are defined:

• DivertedButtons — up to four simultaneously pressed diverted controls.
• DivertedRawMouseXy — raw dx/dy pointer delta while a diverted control is held.
• AnalyticsKeyEvents — batch of up to five AnalyticsKeyEvent entries (CID + device-defined event code).
• DivertedRawWheel — raw vertical wheel delta with RawWheelResolution (Low/High) and a period count.

getCapabilities (v6 devices) exposes whether resetAllCidReportSettings is supported, which clears all diversion and remapping in one call.

Spec: Logitech HID++ 2.0 — specialKeysMSEButtons / ReprogControlsV4. Used by: Gesture Button diversion, button remapping in openlogi-hid.

Function reference

The ReprogControlsFeature wrapper (0x1b04) exposes:

Methods

All methods are async and return Result<…, Hidpp20Error>. listen is synchronous and returns an async_channel::Receiver<ReprogControlsEvent> directly.

Types

ControlId

A HID++ control ID (newtype wrapper around u16).

TaskId

A HID++ task ID (newtype wrapper around u16); represents the behaviour a control performs.

CidInfo

One getCidInfo row.

CidFlags

Capability and classification flags for one control ID (bitflags).

GroupMask

Group mask g1..g8 from getCidInfo (newtype wrapper around u8).

CidReporting

Current reporting/remapping state returned by getCidReporting.

CidReportingChange

Changes for setCidReporting. For boolean fields, None means "leave unchanged".

CidReportingChangeEcho

Echo returned by setCidReporting.

ReprogControlsCapabilities

Feature-level capabilities returned by getCapabilities on v6 devices.

Events

ReprogControlsFeature implements EmittingFeature<ReprogControlsEvent>; call listen() to receive a channel of ReprogControlsEvent values.

ReprogControlsEvent

Event emitted by 0x1b04.

AnalyticsKeyEvent

One analytics key event entry.

U4

An unsigned 4-bit value (nibble) encoded as a byte; used for the periods field in DivertedRawWheel.

RawWheelResolution

Raw wheel movement resolution.

Wire format

Getter requests carry a short 3-byte payload; getCidInfo and setCidReporting use a long 16-byte request payload and always return a long 16-byte response payload. All other responses are also read from the 16-byte long payload via extend_payload().

get_count (fn 0)

Request: [0x00, 0x00, 0x00]

Response (byte → field):

get_cid_info (fn 1)

Request (16-byte long payload):

Response (16-byte long payload → CidInfo):

get_cid_reporting (fn 2)

Request: [cid_hi, cid_lo, 0x00] (big-endian ControlId)

Response (16-byte long payload → CidReporting):

set_cid_reporting (fn 3)

Request (16-byte long payload built by CidReportingChange::to_payload):

Response echoes the same layout as the request; each value field is only valid when its corresponding valid bit is set (see CidReportingChangeEcho).

get_capabilities (fn 4)

Request: [0x00, 0x00, 0x00]

Response (byte → field):

reset_all_cid_report_settings (fn 5)

Request: [0x00, 0x00, 0x00]

Response carries no defined fields; success is indicated by the absence of a Hidpp20Error.

Events

Events arrive as unsolicited long messages (function_id in the sub-ID nibble, software_id nibble = 0).

DivertedButtons (event fn 0)

DivertedRawMouseXy (event fn 1)

AnalyticsKeyEvents (event fn 2)

Five packed 3-byte entries (bytes 0–14); each entry:

DivertedRawWheel (event fn 4)

Usage (Rust)

use hidpp::{device::Device, feature::reprog_controls::{ReprogControlsFeature, CidReportingChange}};

// device: &mut Device, already created via Device::new(channel, index)
device.enumerate_features().await?;
if let Some(feat) = device.get_feature::<ReprogControlsFeature>() {
    // How many controls does this device expose?
    let count = feat.get_count().await?;
    for i in 0..count {
        let info = feat.get_cid_info(i).await?;
        println!("CID {:04x}  divertable={}", info.cid.0, info.flags.is_divertable());
    }

    // Temporarily divert the first divertable control and stream its events.
    let info = feat.get_cid_info(0).await?;
    if info.flags.is_divertable() {
        let change = CidReportingChange::temporary_diversion(true, false);
        feat.set_cid_reporting(info.cid, change).await?;

        let rx = feat.listen();
        if let Ok(event) = rx.recv().await {
            println!("event: {:?}", event);
        }

        // Un-divert before exit.
        feat.set_cid_reporting(info.cid, CidReportingChange::temporary_diversion(false, false)).await?;
    }
}