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 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::CaptureChannelSlot;

pub use session::gesture::CaptureError;

pub use session::gesture::CaptureHost;

pub use session::gesture::CaptureSessionFailure;

pub use session::gesture::CaptureSessionOutcome;

pub use session::gesture::CaptureSessionStop;

pub use session::gesture::CapturedInput;

pub use session::gesture::PendingCaptureRestore;

pub use session::gesture::run_capture_session;

pub use session::host_switch::HostSwitchError;

pub use session::host_switch::HostSwitchRestoreOutcome;

pub use session::host_switch::HostSwitchSessionFailure;

pub use session::host_switch::HostSwitchSessionOutcome;

pub use session::host_switch::HostSwitchStopReason;

pub use session::host_switch::PendingHostSwitchRestore;

pub use session::host_switch::run_host_switch_session;

pub use session::host_switch::switch_linked_hosts;

pub use session::keyboard::RESERVED_KEYBOARD_CONTROLS;

pub use session::keyboard::is_reserved_keyboard_control;

pub use session::keyboard::run_keyboard_capture_session;

pub use write::FeatureEntry;

pub use write::FirmwareEntity;

pub use write::FirmwareEntityInfo;

pub use write::HostOs;

pub use write::LightingMethod;

pub use write::OsLayoutOutcome;

pub use write::OsVersion;

pub use write::ReprogControlEntry;

pub use write::apply_litra;

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_backlight_on;

pub use write::get_dpi;

pub use write::get_dpi_info;

pub use write::get_dpi_info_on;

pub use write::get_easy_switch_hosts;

pub use write::get_easy_switch_hosts_on;

pub use write::get_fn_lock;

pub use write::get_fn_lock_on;

pub use write::get_report_rate_info;

pub use write::get_report_rate_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::keep_os_layout_on;

pub use write::litra_model_for_route;

pub use write::play_haptic;

pub use write::play_haptic_on;

pub use write::read_battery_raw;

pub use write::rename_easy_switch_host;

pub use write::rename_easy_switch_host_on;

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_report_rate;

pub use write::set_report_rate_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;

pub use write::update_backlight;

pub use write::update_backlight_on;

Modules

backend

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

backlight

Compatibility re-exports for semantic keyboard-backlight types.

host_lock

Advisory locks shared by every OpenLogi process on the host.

inventory

Enumerate connected HID++ receivers and their paired devices.

pairing

Wireless device pairing for Logi Bolt and Unifying receivers.

replay

Strict cassette replay over the production device-layer contracts.

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

BacklightControls

What software may change on a keyboard backlight beyond turning it on or off, from the 0x1982 capability bits and feature version.

BacklightState

Snapshot of a keyboard’s backlight, merged from the 0x1982 getBacklightConfig and getBacklightInfo responses.

ChannelPool

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

ChannelRegistry

Channels already opened and owned by the persistent inventory enumerator.

DeviceIoGate

Cheaply cloneable read capability for device-I/O producers.

DeviceIoSignal

Non-blocking producer owned by the host lifecycle observer.

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.

EasySwitchHosts

The Easy-Switch channels of a multi-host device, read from 0x1815.

EasySwitchSlot

One Easy-Switch channel of a multi-host device.

FnLockState

What a keyboard reports about its Fn-lock: whether a bare F-key currently sends F1–F12 (fn_lock), and what it does out of the box.

HostOsInfo

The OS and version the computer on a slot recorded in the device.

IoSuspended

The gate’s refusal while host device I/O is suspended.

LitraDescriptor

A known Litra raw-HID identity and its static product metadata.

OsMask

Operating systems covered by a platform descriptor.

ReceiverDescriptor

A known receiver’s USB identity and the behavior OpenLogi assigns to it.

ReportRate

How often a device sends movement reports, in whole hertz.

ReportRateInfo

A device’s report rate and the rates it lets software choose.

ScrollWheelMode

Current HID++ 0x2121 wheel reporting mode.

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 SmartShift Enhanced tunable-torque level, in percent of the wheel’s maximum force.

WeakSharedChannel

A SharedChannel that does not keep its connection open. Two handles are equal when they name the same connection to the same route, so a replug or another device answering on the route compares unequal.

Enums

BacklightChange

One change to a keyboard backlight, written to the keyboard’s own memory.

BacklightMode

How the firmware decides the backlight brightness level.

BacklightStatus

Why the backlight is in its current state, as reported by the device.

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.

HostConnection

How a host slot reaches its computer.

HostOsKind

An operating system a host slot can record.

LightCommand

A semantic command accepted by the standalone-light layer.

LitraModel

A supported Litra product model.

PairingError

Errors raised by pairing operations.

PasskeyMethod

How the user authenticates the device during Bolt pairing.

ReceiverBrand

Logitech receiver product family, independent of its wire protocol.

ReceiverProtocol

Receiver protocol implementation used to enumerate and address devices.

ReceiverSelector

Selects which receiver a pairing operation targets.

ScrollReportingTarget

Destination for vertical wheel movement reports.

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

DIRECT_DEVICE_INDEX

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

LITRA_BEAM_PRODUCT_ID

Litra Beam product ID.

LITRA_GLOW_PRODUCT_ID

Litra Glow product ID.

LOGITECH_VENDOR_ID

Logitech’s USB/Bluetooth vendor ID.

RECEIVERS

All receiver identities supported by OpenLogi.

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.

device_io_channel

Create an initially-open device-I/O gate.

find_litra

Finds a Litra descriptor by its complete writable raw-HID identity.

find_receiver

Finds the descriptor for an exact USB vendor/product identity.

matches_litra

Whether an HID descriptor identifies a supported Litra interface.

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 Nano or Lightspeed receiver. Such receivers are addressed with DeviceRoute::Unifying.