OpenLogi

0x2202 · extendedAdjustableDpi

Extended per-sensor DPI control — X/Y resolution, lift-off distance, DPI-status LED control, and calibration.

0x2202 controls DPI parameters for each motion sensor. It adds optional X/Y DPI, lift-off distance (LOD), DPI-status LED control, profiles, and calibration to 0x2201 adjustableDpi.

Spec: Logitech HID++ 2.0 — x2202 extendedAdjustableDpi. Cross-checked: Logi Options+ 2.8 (static analysis), Solaar. Used by: DPI.

Function reference

ExtendedDpiFeature is the OpenLogi wrapper for 0x2202. Its asynchronous methods return Result<T, Hidpp20Error>. listen is synchronous and returns an async_channel::Receiver<ExtendedDpiEvent>.

Methods

FunctionHID++ fnSignatureReturns
get_sensor_count0()u8
get_sensor_capabilities1(sensor_index: u8)SensorCapabilitiesInfo
get_sensor_dpi_ranges2(sensor_index: u8, direction: DpiDirection)Vec<DpiRange>
get_sensor_dpi_list3(sensor_index: u8, direction: DpiDirection)Vec<u16>
get_sensor_lod_list4(sensor_index: u8, dpi_level_count: u8)Vec<Lod>
get_sensor_dpi_parameters5(sensor_index: u8)DpiParameters
set_sensor_dpi_parameters6(sensor_index: u8, params: SetDpiParameters)()
show_sensor_dpi_status7(sensor_index: u8, params: ShowDpiStatus)()
get_dpi_calibration_info8(sensor_index: u8)DpiCalibrationInfo
start_dpi_calibration9(sensor_index: u8, params: StartDpiCalibration)()
set_dpi_calibration10(sensor_index: u8, direction: DpiDirection, correction: DpiCalibrationCorrection)()
listenevent()Receiver<ExtendedDpiEvent>

Types

DpiDirection

VariantValueDescription
X0Horizontal axis.
Y1Vertical axis.

Lod

LOD is the height above the surface where a sensor stops tracking motion.

VariantValueDescription
NotSupported0The sensor has no LOD control.
Low1Low lift-off distance.
Medium2Medium lift-off distance.
High3High lift-off distance.

LedHoldType

VariantValueDescription
TimerBased0Turn the LED off after a device-defined timeout.
EventBased1Turn the LED off after a device-defined event.
SwControlOn2Turn the LED on under software control.
SwControlOff3Turn the LED off under software control.

CalibrationType

VariantValueDescription
Hardware0The sensor firmware computes calibration.
Software1Host software computes calibration.

SensorCapabilities

FlagBitDescription
DPI_Y1 << 0The sensor supports independent Y-axis DPI.
LOD1 << 1The sensor supports LOD control.
CALIBRATION1 << 2The sensor supports calibration.
PROFILE1 << 3The sensor supports DPI profiles.

get_sensor_capabilities retains unknown capability bits. SetDpiParameters::for_sensor uses only DPI_Y and LOD to prepare a write.

SensorCapabilitiesInfo

FieldTypeDescription
sensor_indexu8Sensor index from the reply.
dpi_level_countu8Selectable DPI level count. 0 means unmanaged levels.
capabilitiesSensorCapabilitiesCapability bits for this sensor.

DpiRange

VariantDescription
Fixed(u16)One selectable DPI value.
SteppedAn inclusive DPI range with public from: u16, to: u16, and step: u16 fields.

Adjacent stepped ranges can share an endpoint.

DpiParameters

FieldTypeDescription
sensor_indexu8Sensor index.
dpi_xu16Current X-axis DPI.
default_dpi_xu16Default X-axis DPI.
dpi_yu16Current Y-axis DPI, or 0 without DPI_Y.
default_dpi_yu16Default Y-axis DPI, or 0 without DPI_Y.
lodLodCurrent lift-off distance.

SetDpiParameters

FieldTypeDescription
dpi_xu16New X-axis DPI. The protocol range is 1..=57343.
dpi_yu16New Y-axis DPI, or 0 without DPI_Y.
lodLodNew lift-off distance.

SetDpiParameters::for_sensor(capabilities, dpi_x, dpi_y, lod) returns values that send Y only with DPI_Y and LOD only with LOD. The raw setter does not perform a capability or DPI-range check.

ShowDpiStatus

FieldTypeDescription
dpi_levelu8Level to display. The protocol range is 1..=dpi_level_count.
led_hold_typeLedHoldTypeHow the LED remains on.
button_numu8HID button number that started the change. It starts at 1.

DpiCalibrationInfo

FieldTypeDescription
sensor_indexu8Sensor index.
mouse_widthu8Device width in millimetres.
mouse_lengthu16Device length in millimetres.
calib_dpi_xu16X-axis DPI for calibration.
calib_dpi_yu16Y-axis DPI for calibration, or 0 without DPI_Y.

StartDpiCalibration

FieldTypeDescription
directionDpiDirectionAxis to calibrate.
expected_countu16Expected movement in pixels. Software calibration ignores it.
calib_typeCalibrationTypeWhere calibration runs.
start_timeoutu8Start timeout in seconds. The protocol allows at most 60.
hw_process_timeoutu8Hardware process timeout in seconds. The protocol allows at most 60.
sw_process_timeoutu8Software process timeout in seconds. The protocol allows at most 60.

DpiCalibrationCorrection

VariantDescription
Adjust(i16)Scale resolution by (1024 + value) / 1024. Values from -1023 through 1023 are valid.
RevertToOobRestore the out-of-box profile setting. Its wire value is 0x0000.
RevertToProfileRestore the current profile setting. Its wire value is 0x8000.

Adjust(0) has the same wire value as RevertToOob. Out-of-range adjustments return Hidpp20Error::Feature(ErrorType::InvalidArgument).

Events

ExtendedDpiFeature implements EmittingFeature<ExtendedDpiEvent>. Call listen() before the device sends an unsolicited report.

DpiParametersChanged

ExtendedDpiEvent::ParametersChanged reports a device-originated DPI parameter change.

FieldTypeDescription
sensor_indexu8Sensor that changed.
dpi_xu16New X-axis DPI.
dpi_yu16New Y-axis DPI, or 0 without DPI_Y.
lodOption<Lod>New LOD. An unknown wire value becomes None.

DpiCalibrationCompleted

ExtendedDpiEvent::CalibrationCompleted reports a calibration completion or timeout.

FieldTypeDescription
sensor_indexu8Sensor that was calibrated.
directionOption<DpiDirection>Calibrated axis. An unknown wire value becomes None.
correctioni16BE correction. i16::MIN means sensor-level failure.
deltai16BE perpendicular-axis displacement in pixels.

Use DpiCalibrationCompleted::failed() to test the i16::MIN failure sentinel.

Wire format

Functions 0–5 and 8 use short three-byte requests. Functions 6, 7, 9, and 10 use long 16-byte requests. OpenLogi zero-pads every unspecified byte in a long request. Every multi-byte field below uses BE byte order.

get_sensor_count (fn 0)

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

ByteFieldNotes
0sensor_countNumber of motion sensors.
1–15/OpenLogi ignores these bytes.

get_sensor_capabilities (fn 1)

Request: [sensor_index, 0x00, 0x00].

ByteFieldNotes
0echoed sensor_indexOpenLogi requires a match. A mismatch returns Hidpp20Error::UnsupportedResponse.
1dpi_level_count0 means unmanaged levels.
2capabilitiesBits 0–3 are DPI_Y, LOD, CALIBRATION, and PROFILE. Unknown bits are retained.
3–15/OpenLogi ignores these bytes.

get_sensor_dpi_ranges (fn 2)

Request: [sensor_index, direction, page]. direction is 0 for X and 1 for Y. page starts at 0.

BytesFieldNotes
0echoed sensor_indexOpenLogi requires a match.
1echoed directionOpenLogi requires a match.
2echoed pageOpenLogi requires a match.
3–15range streamThirteen stream bytes. A BE word can cross a page boundary.

A literal word has top three bits other than 0b111. A word with top three bits 0b111 carries the positive step between its surrounding literal endpoints. 0x0000 ends the complete stream. OpenLogi fetches no more than 16 pages, ignores bytes after the first terminator, and rejects malformed ranges or an unterminated stream.

get_sensor_dpi_list (fn 3)

Request: [sensor_index, direction, 0x00].

BytesFieldNotes
0echoed sensor_indexOpenLogi requires a match.
1echoed directionOpenLogi requires a match.
2–15DPI wordsUp to seven BE u16 entries. 0x0000 ends the list.

This function is meaningful only with SensorCapabilities::PROFILE. A full list can omit the terminator. OpenLogi preserves the listed order and duplicate values.

get_sensor_lod_list (fn 4)

Request: [sensor_index, 0x00, 0x00].

BytesFieldNotes
0echoed sensor_indexOpenLogi requires a match.
1 onwardLOD entriesOne byte per DPI level: 0, 1, 2, or 3 maps to Lod.

The caller supplies dpi_level_count, normally from fn 1. The list has no terminator. OpenLogi reads exactly that many entries and rejects an unknown LOD or an impossible length. It ignores the remaining payload bytes.

get_sensor_dpi_parameters (fn 5)

Request: [sensor_index, 0x00, 0x00].

BytesFieldNotes
0echoed sensor_indexOpenLogi requires a match.
1–2dpi_xBE u16.
3–4default_dpi_xBE u16.
5–6dpi_yBE u16. It is 0 without DPI_Y.
7–8default_dpi_yBE u16. It is 0 without DPI_Y.
9lodLod value. OpenLogi rejects an unknown value.
10–15/OpenLogi ignores these bytes.

OpenLogi requires a long reply for this function. A short reply returns Hidpp20Error::UnsupportedResponse.

set_sensor_dpi_parameters (fn 6)

BytesFieldNotes
0sensor_indexTarget sensor.
1–2dpi_xBE u16.
3–4dpi_yBE u16. The protocol requires zero without DPI_Y.
5lodLod value. The protocol requires zero without LOD.
6–15/OpenLogi writes zero.

OpenLogi requires the reply to echo sensor_index at byte 0. SetDpiParameters::for_sensor produces the required zero values for unsupported Y and LOD fields.

show_sensor_dpi_status (fn 7)

BytesFieldNotes
0sensor_indexTarget sensor.
1dpi_levelDisplayed DPI level.
2led_hold_type0 through 3 map to LedHoldType.
3button_numHID button number.
4–15/OpenLogi writes zero.

This function is valid only in host mode. OpenLogi requires the reply to echo sensor_index at byte 0.

get_dpi_calibration_info (fn 8)

Request: [sensor_index, 0x00, 0x00].

BytesFieldNotes
0echoed sensor_indexOpenLogi requires a match.
1mouse_widthDevice width in millimetres.
2–3mouse_lengthBE u16 device length in millimetres.
4–5calib_dpi_xBE u16.
6–7calib_dpi_yBE u16. It is 0 without DPI_Y.
8–15/OpenLogi ignores these bytes.

OpenLogi requires a long reply for this function. A short reply returns Hidpp20Error::UnsupportedResponse.

start_dpi_calibration (fn 9)

BytesFieldNotes
0sensor_indexTarget sensor.
1direction0 for X or 1 for Y.
2–3expected_countBE u16. Software calibration ignores it.
4calib_type0 for hardware or 1 for software.
5start_timeoutSeconds. The protocol allows at most 60.
6hw_process_timeoutSeconds. The protocol allows at most 60.
7sw_process_timeoutSeconds. The protocol allows at most 60.
8–15/OpenLogi writes zero.

This function requires SensorCapabilities::CALIBRATION. The device reports its result with the CalibrationCompleted event. Software calibration then uses fn 10 to apply a correction. OpenLogi requires the reply to echo sensor_index at byte 0.

set_dpi_calibration (fn 10)

BytesFieldNotes
0sensor_indexTarget sensor.
1direction0 for X or 1 for Y.
2–3correctionBE signed i16. 0x0000 is out-of-box. 0x8000 is profile restore.
4–15/OpenLogi writes zero.

OpenLogi validates the Adjust range before it sends this request. It requires the reply to echo sensor_index at byte 0.

Events

Unsolicited reports use sub-id 0 or 1. OpenLogi decodes the first six payload bytes. It ignores bytes 6–15.

ParametersChanged (sub-id 0)

BytesFieldNotes
0sensor_indexSensor that changed.
1–2dpi_xBE u16.
3–4dpi_yBE u16. It is 0 without DPI_Y.
5lodLod value. An unknown value becomes None.

CalibrationCompleted (sub-id 1)

BytesFieldNotes
0sensor_indexSensor that completed calibration.
1direction0 for X or 1 for Y. An unknown value becomes None.
2–3correctionBE signed i16. 0x8000 is the failure sentinel.
4–5deltaBE signed i16 perpendicular-axis displacement in pixels.

Unknown event sub-ids produce no ExtendedDpiEvent.

How OpenLogi uses it

The device layer uses 0x2202 only when the device does not expose 0x2201. It operates sensor 0. It reads fn 5 for X DPI and fn 2 for the X-axis range. It does not use the profile list, LOD list, LED, or calibration functions.

Before a DPI write, OpenLogi flattens the device-reported X ranges and rejects a value outside that list with WriteError::DpiUnsupported. It reads the sensor capabilities and current parameters. SetDpiParameters::for_sensor writes Y equal to X only with DPI_Y. It preserves the current LOD only with LOD; otherwise it writes zero. The fn 6 acknowledgment must echo the sensor.

OpenLogi reads back X DPI after each acknowledged write and retries once. A second different value returns WriteError::DpiNotApplied. A failed read-back leaves the acknowledged write in place. The desktop saves the request before its asynchronous write, so a rejected or unapplied write can remain in desktop state until a later live read.

Since v0.8.14, the inventory listener recognizes an unsolicited fn 0 DPI-parameter broadcast. It increments the device settings revision, so clients re-read the authoritative setting. The listener does not decode the event payload or persist the device-originated value. It ignores fn 1 calibration-completed broadcasts.

The agent re-applies saved DPI after reconnect because the sensor setting is volatile. OpenLogi has no feature-specific reset on exit. The user-facing control is the DPI page.

Usage (Rust)

use hidpp::{
    device::Device,
    feature::{
        EmittingFeature,
        extended_dpi::{DpiDirection, ExtendedDpiFeature, SetDpiParameters},
    },
    protocol::v20::Hidpp20Error,
};

async fn inspect_extended_dpi(device: &mut Device) -> Result<(), Hidpp20Error> {
    device.enumerate_features().await?;
    if let Some(feature) = device.get_feature::<ExtendedDpiFeature>() {
        let capabilities = feature.get_sensor_capabilities(0).await?;
        let ranges = feature.get_sensor_dpi_ranges(0, DpiDirection::X).await?;
        let current = feature.get_sensor_dpi_parameters(0).await?;

        println!("X ranges: {ranges:?}");
        let write = SetDpiParameters::for_sensor(
            capabilities.capabilities,
            1600,
            1600,
            current.lod,
        );
        feature.set_sensor_dpi_parameters(0, write).await?;

        let events = feature.listen();
        if let Ok(event) = events.recv().await {
            println!("DPI event: {event:?}");
        }
    }

    Ok(())
}

On this page