Module write 

HID++ reads and writes per feature — DPI, SmartShift, wheel modes, lighting, backlight, and diagnostics.

Each entry point takes a DeviceRoute and resolves it to an open channel through open_route_channel, so the same call works whether the device is behind a Bolt receiver or attached directly (USB cable / Bluetooth). Each route-addressed call re-enumerates and re-opens, while the corresponding _on entry points reuse a crate::SharedChannel already owned by inventory or a standalone capture session.

Structs

Dpi

A sensor resolution that fits HID++’s unsigned 16-bit DPI field.

DpiCapabilities

Supported DPI values reported by a device’s HID++ AdjustableDpi feature.

DpiInfo

Current DPI plus the supported values reported by the device.

FeatureEntry

Snapshot of one HID++ feature exposed by a device: protocol ID + version. Returned by dump_features for diagnostics.

FirmwareEntityInfo

Firmware fields for one entity whose record the device answered and this parser decoded.

ReprogControlEntry

Snapshot of one HID++ 0x1b04 reprogrammable control. Returned by dump_reprog_controls for diagnostics so new device controls can be identified before OpenLogi maps them to a first-class button.

ScrollWheelMode

Current HID++ 0x2121 wheel reporting mode.

Enums

FirmwareEntity

One firmware entity a device reports through HID++ 0x0003 function 1. Returned by dump_firmware_entities so a device report can name the exact firmware it is running.

HapticWaveform

A haptic waveform ID accepted by playWaveform.

HidppFeatureErrorKind

HID++ feature error kind in a serializable wire-safe form.

HidppOperation

HID++ operation being performed when a device write/read failed.

LightCommand

A semantic command accepted by the standalone-light layer.

LightingMethod

Which HID++ lighting path drives a solid keyboard colour. Auto is what the GUI/agent use; the explicit variants exist for the diag A/B test.

LitraModel

A supported Litra product family variant.

ScrollReportingTarget

Destination for vertical wheel movement reports.

ScrollResolution

Vertical wheel reporting resolution for HID++ 0x2121 HiResWheel.

WriteError

Error returned by HID++ read/write operations.

Constants

LITRA_BEAM_PRODUCT_ID

Litra Beam product ID.

LITRA_GLOW_PRODUCT_ID

Litra Glow product ID.

Functions

apply_litra

Apply a semantic Litra command through a raw HID route.

clear_haptic_feature_cache

Drop the cached haptic feature handle (and with it the Arc<HidppChannel> it pins). MUST be called whenever route resolution fails: the inventory enumerator only reopens a retired node once every clone of its channel has dropped (Arc::strong_count == 1), and a stale cache entry otherwise deadlocks recovery — the node can’t reopen because the cache pins the old channel, and the cache is never invalidated because route lookups fail before any haptic I/O touches it.

commands_for_light_settings

Expand protocol-neutral saved settings into only the controls advertised by a standalone light. Unsupported controls are omitted rather than sent speculatively, which keeps power-only and brightness-only drivers usable.

dump_features

Enumerate every HID++ feature the device on route reports — used by openlogi diag features to confirm which DPI / SmartShift / etc. feature IDs a given peripheral actually exposes (e.g. whether a mouse speaks 0x2201 AdjustableDpi, 0x2202 ExtendedAdjustableDpi, or both — write::dpi drives either).

dump_firmware_entities

Read every firmware entity the device on route reports.

dump_reprog_controls

Enumerate the device’s HID++ 0x1b04 reprogrammable controls. This is a diagnostics-only probe used to discover controls for newly released devices. For example, MX Master 4 has both a Gesture Button and a separate Haptic Sense Panel in the thumb area; this probe lets us identify the panel’s CID and capabilities before wiring it into the capture/remapping model.

encode_litra_command

Encode a semantic command into the exact fixed-width Litra report.

ensure_haptics_armed_on

Ensure the firmware haptic engine is armed: enabled, with a non-zero intensity. Returns true when a repair write was needed.

get_backlight

Read the current backlight state of the keyboard on route.

get_dpi

Read the device’s current DPI on sensor 0 — companion to set_dpi. Used by openlogi diag dpi and any future Settings → Diagnostics surface that wants to display the current value without writing.

get_dpi_info

Read the current DPI and the supported DPI values for sensor 0 in one route/channel session.

get_dpi_info_on

Read current DPI and supported values on an already-open SharedChannel.

get_scroll_wheel_mode

Read the current vertical wheel reporting mode.

get_scroll_wheel_mode_on

Read the current wheel mode on an already-open SharedChannel.

get_smartshift_status

Read the device’s current SmartShift mode + sensitivity — companion to toggle_smartshift.

get_smartshift_status_on

Read SmartShift mode and sensitivity on an already-open SharedChannel.

matches_litra

Whether an HID descriptor identifies a supported Litra interface.

play_haptic

Play a waveform immediately by route.

play_haptic_on

Play a waveform immediately on an open capture channel.

read_battery_raw

Diagnostic read of the device’s raw battery report — the unified 0x1004 fields, or the legacy 0x1000 discharge_level/next_level/status. For openlogi diag battery: surfaces exactly what the firmware reports so a claim like “MX2S shows 0% while charging” can be confirmed against the wire instead of guessed (the GUI only ever shows the mapped value).

set_backlight_enabled

Enable or disable the backlight on route, and return the read-back state.

set_dpi

Set sensor 0’s DPI for the device addressed by route.

set_dpi_on

Write DPI on an already-open SharedChannel — the fast path that skips enumeration and channel setup.

set_fn_lock

Write the keyboard’s Fn-lock state: true = F-row sends F1–F12 directly.

set_fn_lock_on

Write keyboard Fn-lock on an already-open SharedChannel — the fast path that skips enumeration and channel setup.

set_keyboard_color

Set a keyboard to a solid (r, g, b) colour, choosing the HID++ path automatically: the 0x8070 effect engine (which overrides the onboard profile) when present, else the 0x8080 per-key stream. FeatureUnsupported when the device exposes neither.

set_keyboard_color_on

Set a solid keyboard colour on an already-open SharedChannel, using LightingMethod::Auto.

set_keyboard_color_with

set_keyboard_color with an explicit LightingMethod. Auto tries 0x8070 first and falls back to 0x8080 only when the effect engine is absent (a missing-0x8070 FeatureUnsupported); any other error propagates.

set_keyboard_color_with_on

Set a solid keyboard colour on an already-open SharedChannel with an explicit lighting method.

set_scroll_inversion

Write the device’s native vertical-scroll inversion flag while preserving its current resolution.

set_scroll_inversion_on

Write native scroll inversion on an already-open SharedChannel.

set_scroll_resolution

Set only the wheel resolution while preserving the current inversion flag. Reporting is always normalized to native HID.

set_scroll_resolution_on

Set only the wheel resolution on an already-open SharedChannel.

set_scroll_wheel_mode

Set wheel resolution and native inversion together in one HID++ write.

set_scroll_wheel_mode_on

Set wheel resolution and inversion on an already-open SharedChannel.

set_smartshift

Write a full SmartShift configuration to route. The values are volatile device state and should be re-applied after reconnect. Callers that mean to change one field should read the current SmartShiftStatus and update it.

set_smartshift_on

Write a full SmartShift configuration on an already-open SharedChannel — the fast path that skips enumeration and channel setup.

set_smartshift_sensitivity

Set the SmartShift auto-disengage sensitivity on route, preserving the current mode. Returns the read-back status after the write so the caller can display and verify it.

toggle_smartshift

Toggle SmartShift mode (free ↔ ratchet) on route. Reads the current mode first, then writes the opposite — keeps current sensitivity. Returns the new mode written.

toggle_smartshift_on

Toggle SmartShift on an already-open SharedChannel.