Crate openlogi_device 

OpenLogi’s HID++ device layer: everything that knows Logitech’s protocol and nothing about a host.

backend::HidBackend is the seam. Above it sits this crate — enumeration and probing, the write layer, capture sessions, pairing. Below it sits one implementation per host HID API: openlogi-hid over async-hid, a scripted device tree in tests, WebHID under wasm if that is ever built.

Nothing here opens a device by itself; everything that needs one is handed a backend. That is what makes the layer reusable, and it is checked rather than trusted — CI’s wasm (portable crates) job builds this crate for a target with no OS underneath it, so a dependency that assumes one fails there and nowhere else.

Re-exports

pub use backend::BackendError;

pub use backend::HidBackend;

pub use backend::HotplugEvent;

pub use backend::HotplugStream;

pub use backend::NodeId;

pub use backend::NodeInfo;

pub use backend::RawWriter;

pub use backlight::BacklightMode;

pub use backlight::BacklightState;

pub use backlight::BacklightStatus;

pub use inventory::hotplug::watch_hotplug;

pub use inventory::standalone::enumerate_standalone;

pub use inventory::Enumerator;

pub use inventory::InventoryError;

pub use inventory::enumerate;

pub use pairing::DiscoveredDevice;

pub use pairing::PairingCommand;

pub use pairing::PairingEvent;

pub use pairing::PairingReceiver;

pub use pairing::ReceiverFamily;

pub use pairing::list_pairing_receivers;

pub use pairing::run_pairing;

pub use pairing::unpair;

pub use session::gesture::CaptureChannel;

pub use session::gesture::CaptureStop;

pub use session::gesture::CapturedInput;

pub use session::gesture::GestureError;

pub use session::gesture::run_capture_session;

pub use session::gesture::run_capture_session_with_stop_reason;

pub use session::host_switch::HostSwitchError;

pub use session::host_switch::HostSwitchStopReason;

pub use session::host_switch::run_host_switch_session;

pub use session::host_switch::switch_linked_hosts;

pub use session::keyboard::KEYBOARD_KEY_CIDS;

pub use session::keyboard::run_keyboard_capture_session;

pub use session::keyboard::run_keyboard_capture_session_with_registry;

pub use write::FeatureEntry;

pub use write::FirmwareEntity;

pub use write::FirmwareEntityInfo;

pub use write::LITRA_BEAM_PRODUCT_ID;

pub use write::LITRA_GLOW_PRODUCT_ID;

pub use write::LightingMethod;

pub use write::LitraModel;

pub use write::ReprogControlEntry;

pub use write::ScrollReportingTarget;

pub use write::ScrollWheelMode;

pub use write::apply_litra;

pub use write::clear_haptic_feature_cache;

pub use write::dump_features;

pub use write::dump_firmware_entities;

pub use write::dump_reprog_controls;

pub use write::encode_litra_command;

pub use write::ensure_haptics_armed_on;

pub use write::get_backlight;

pub use write::get_dpi;

pub use write::get_dpi_info;

pub use write::get_dpi_info_on;

pub use write::get_scroll_wheel_mode;

pub use write::get_scroll_wheel_mode_on;

pub use write::get_smartshift_status;

pub use write::get_smartshift_status_on;

pub use write::matches_litra;

pub use write::play_haptic;

pub use write::play_haptic_on;

pub use write::read_battery_raw;

pub use write::set_backlight_enabled;

pub use write::set_dpi;

pub use write::set_dpi_on;

pub use write::set_fn_lock;

pub use write::set_fn_lock_on;

pub use write::set_keyboard_color;

pub use write::set_keyboard_color_on;

pub use write::set_keyboard_color_with;

pub use write::set_keyboard_color_with_on;

pub use write::set_scroll_inversion;

pub use write::set_scroll_inversion_on;

pub use write::set_scroll_resolution;

pub use write::set_scroll_resolution_on;

pub use write::set_scroll_wheel_mode;

pub use write::set_scroll_wheel_mode_on;

pub use write::set_smartshift;

pub use write::set_smartshift_on;

pub use write::set_smartshift_sensitivity;

pub use write::toggle_smartshift;

pub use write::toggle_smartshift_on;

Modules

backend

The contract between OpenLogi’s HID++ layer and the HID stack beneath it.

backlight

HID++ Backlight (feature 0x1982) — keyboard backlight control.

inventory

Enumerate connected HID++ receivers and their paired devices.

pairing

Wireless device pairing for Logi Bolt and Unifying receivers.

reprog_controls

HID++ ReprogControlsV4 (feature 0x1b04) — temporary control diversion and raw-XY reporting, the mechanism behind MX-line reprogrammable controls.

session

Long-running device sessions.

smartshift

HID++ SmartShift Enhanced (feature 0x2111) — wheel ratchet ↔ free-spin control with sensitivity threshold.

thumbwheel

HID++ Thumbwheel (feature 0x2150) — divert the MX-line horizontal thumb wheel so its rotation and single-tap gesture arrive as HID++ events instead of native HID scroll.

write

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

Structs

ChannelPool

Reuses one open HID++ channel for routes on the same receiver.

ChannelRegistry

Channels already opened and owned by the persistent inventory enumerator.

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.

SharedChannel

An open HID++ channel to a device, shared so route-addressed reads and writes can reuse an inventory- or capture-owned connection instead of re-enumerating and opening a fresh channel each time (which costs ~100ms+).

SmartShiftStatus

Snapshot returned from OpenLogi’s SmartShift read helpers.

SmartShiftThreshold

A SmartShift auto-disengage speed threshold in firmware units of 0.25 turn/s.

TunableTorque

A non-zero tunable-torque level reported by SmartShift Enhanced.

Enums

Click

A single click in a pointer passkey sequence.

DeviceRoute

How to reach a controllable HID++ device.

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.

PairingError

Errors raised by pairing operations.

PasskeyMethod

How the user authenticates the device during Bolt pairing.

ReceiverSelector

Selects which receiver a pairing operation targets.

ScrollResolution

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

SmartShiftAutoDisengage

SmartShift’s auto-disengage behavior.

SmartShiftMode

SmartShift mode values understood by the firmware. Free = free-spin, Ratchet = clicky / smartshift-off. The discriminant is the wire byte; reserved values (0 / 3 / future) fail TryFrom and callers fall back to whatever they consider sane.

WriteError

Error returned by HID++ read/write operations.

Constants

BOLT_PIDS

USB product IDs that identify Logi Bolt receivers.

DIRECT_DEVICE_INDEX

HID++ device index that addresses a directly-attached device’s own features (USB-cable or Bluetooth, no receiver indirection).

LIGHTSPEED_PIDS

USB product IDs that identify Logitech Lightspeed receivers — the receivers bundled with G-series wireless devices. 0xc539 ships with the G502 LIGHTSPEED and the G Pro Wireless — its USB product string is literally LIGHTSPEED Receiver; 0xc53f is the nano receiver of wireless mice such as the G305; 0xc547 ships with newer G-series devices such as the G915 keyboard and the G502 X LIGHTSPEED; 0xc54d ships with the PRO X SUPERLIGHT 2 DEX. They speak the same HID++ 1.0 receiver register protocol as Unifying, so they are enumerated, routed, and paired through the Unifying code path; only the user-facing receiver name (see receiver_display_name) differs.

LOGITECH_VENDOR_ID

Logitech’s USB/Bluetooth vendor ID. u16 because that is the width of the field itself; readers whose API hands back a wider integer widen at the comparison.

UNIFYING_PIDS

USB product IDs that identify Logi Unifying receivers. Used by callers that need to construct the correct DeviceRoute variant from a raw inventory.

Functions

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.

receiver_display_name

Human-readable name for a receiver identified by product_id, used to label it in the inventory. Lightspeed receivers share the Unifying protocol path but are surfaced under their own name.

speaks_unifying_protocol

Whether product_id is a receiver that speaks the Unifying HID++ 1.0 register protocol — a Unifying receiver proper, or a protocol-compatible Lightspeed receiver. Such receivers are addressed with DeviceRoute::Unifying.