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
| Function | HID++ fn | Signature | Returns |
|---|---|---|---|
get_sensor_count | 0 | () | u8 |
get_sensor_capabilities | 1 | (sensor_index: u8) | SensorCapabilitiesInfo |
get_sensor_dpi_ranges | 2 | (sensor_index: u8, direction: DpiDirection) | Vec<DpiRange> |
get_sensor_dpi_list | 3 | (sensor_index: u8, direction: DpiDirection) | Vec<u16> |
get_sensor_lod_list | 4 | (sensor_index: u8, dpi_level_count: u8) | Vec<Lod> |
get_sensor_dpi_parameters | 5 | (sensor_index: u8) | DpiParameters |
set_sensor_dpi_parameters | 6 | (sensor_index: u8, params: SetDpiParameters) | () |
show_sensor_dpi_status | 7 | (sensor_index: u8, params: ShowDpiStatus) | () |
get_dpi_calibration_info | 8 | (sensor_index: u8) | DpiCalibrationInfo |
start_dpi_calibration | 9 | (sensor_index: u8, params: StartDpiCalibration) | () |
set_dpi_calibration | 10 | (sensor_index: u8, direction: DpiDirection, correction: DpiCalibrationCorrection) | () |
listen | event | () | Receiver<ExtendedDpiEvent> |
Types
DpiDirection
| Variant | Value | Description |
|---|---|---|
X | 0 | Horizontal axis. |
Y | 1 | Vertical axis. |
Lod
LOD is the height above the surface where a sensor stops tracking motion.
| Variant | Value | Description |
|---|---|---|
NotSupported | 0 | The sensor has no LOD control. |
Low | 1 | Low lift-off distance. |
Medium | 2 | Medium lift-off distance. |
High | 3 | High lift-off distance. |
LedHoldType
| Variant | Value | Description |
|---|---|---|
TimerBased | 0 | Turn the LED off after a device-defined timeout. |
EventBased | 1 | Turn the LED off after a device-defined event. |
SwControlOn | 2 | Turn the LED on under software control. |
SwControlOff | 3 | Turn the LED off under software control. |
CalibrationType
| Variant | Value | Description |
|---|---|---|
Hardware | 0 | The sensor firmware computes calibration. |
Software | 1 | Host software computes calibration. |
SensorCapabilities
| Flag | Bit | Description |
|---|---|---|
DPI_Y | 1 << 0 | The sensor supports independent Y-axis DPI. |
LOD | 1 << 1 | The sensor supports LOD control. |
CALIBRATION | 1 << 2 | The sensor supports calibration. |
PROFILE | 1 << 3 | The 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
| Field | Type | Description |
|---|---|---|
sensor_index | u8 | Sensor index from the reply. |
dpi_level_count | u8 | Selectable DPI level count. 0 means unmanaged levels. |
capabilities | SensorCapabilities | Capability bits for this sensor. |
DpiRange
| Variant | Description |
|---|---|
Fixed(u16) | One selectable DPI value. |
Stepped | An inclusive DPI range with public from: u16, to: u16, and step: u16 fields. |
Adjacent stepped ranges can share an endpoint.
DpiParameters
| Field | Type | Description |
|---|---|---|
sensor_index | u8 | Sensor index. |
dpi_x | u16 | Current X-axis DPI. |
default_dpi_x | u16 | Default X-axis DPI. |
dpi_y | u16 | Current Y-axis DPI, or 0 without DPI_Y. |
default_dpi_y | u16 | Default Y-axis DPI, or 0 without DPI_Y. |
lod | Lod | Current lift-off distance. |
SetDpiParameters
| Field | Type | Description |
|---|---|---|
dpi_x | u16 | New X-axis DPI. The protocol range is 1..=57343. |
dpi_y | u16 | New Y-axis DPI, or 0 without DPI_Y. |
lod | Lod | New 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
| Field | Type | Description |
|---|---|---|
dpi_level | u8 | Level to display. The protocol range is 1..=dpi_level_count. |
led_hold_type | LedHoldType | How the LED remains on. |
button_num | u8 | HID button number that started the change. It starts at 1. |
DpiCalibrationInfo
| Field | Type | Description |
|---|---|---|
sensor_index | u8 | Sensor index. |
mouse_width | u8 | Device width in millimetres. |
mouse_length | u16 | Device length in millimetres. |
calib_dpi_x | u16 | X-axis DPI for calibration. |
calib_dpi_y | u16 | Y-axis DPI for calibration, or 0 without DPI_Y. |
StartDpiCalibration
| Field | Type | Description |
|---|---|---|
direction | DpiDirection | Axis to calibrate. |
expected_count | u16 | Expected movement in pixels. Software calibration ignores it. |
calib_type | CalibrationType | Where calibration runs. |
start_timeout | u8 | Start timeout in seconds. The protocol allows at most 60. |
hw_process_timeout | u8 | Hardware process timeout in seconds. The protocol allows at most 60. |
sw_process_timeout | u8 | Software process timeout in seconds. The protocol allows at most 60. |
DpiCalibrationCorrection
| Variant | Description |
|---|---|
Adjust(i16) | Scale resolution by (1024 + value) / 1024. Values from -1023 through 1023 are valid. |
RevertToOob | Restore the out-of-box profile setting. Its wire value is 0x0000. |
RevertToProfile | Restore 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.
| Field | Type | Description |
|---|---|---|
sensor_index | u8 | Sensor that changed. |
dpi_x | u16 | New X-axis DPI. |
dpi_y | u16 | New Y-axis DPI, or 0 without DPI_Y. |
lod | Option<Lod> | New LOD. An unknown wire value becomes None. |
DpiCalibrationCompleted
ExtendedDpiEvent::CalibrationCompleted reports a calibration completion or timeout.
| Field | Type | Description |
|---|---|---|
sensor_index | u8 | Sensor that was calibrated. |
direction | Option<DpiDirection> | Calibrated axis. An unknown wire value becomes None. |
correction | i16 | BE correction. i16::MIN means sensor-level failure. |
delta | i16 | BE 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].
| Byte | Field | Notes |
|---|---|---|
| 0 | sensor_count | Number of motion sensors. |
| 1–15 | / | OpenLogi ignores these bytes. |
get_sensor_capabilities (fn 1)
Request: [sensor_index, 0x00, 0x00].
| Byte | Field | Notes |
|---|---|---|
| 0 | echoed sensor_index | OpenLogi requires a match. A mismatch returns Hidpp20Error::UnsupportedResponse. |
| 1 | dpi_level_count | 0 means unmanaged levels. |
| 2 | capabilities | Bits 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.
| Bytes | Field | Notes |
|---|---|---|
| 0 | echoed sensor_index | OpenLogi requires a match. |
| 1 | echoed direction | OpenLogi requires a match. |
| 2 | echoed page | OpenLogi requires a match. |
| 3–15 | range stream | Thirteen 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].
| Bytes | Field | Notes |
|---|---|---|
| 0 | echoed sensor_index | OpenLogi requires a match. |
| 1 | echoed direction | OpenLogi requires a match. |
| 2–15 | DPI words | Up 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].
| Bytes | Field | Notes |
|---|---|---|
| 0 | echoed sensor_index | OpenLogi requires a match. |
| 1 onward | LOD entries | One 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].
| Bytes | Field | Notes |
|---|---|---|
| 0 | echoed sensor_index | OpenLogi requires a match. |
| 1–2 | dpi_x | BE u16. |
| 3–4 | default_dpi_x | BE u16. |
| 5–6 | dpi_y | BE u16. It is 0 without DPI_Y. |
| 7–8 | default_dpi_y | BE u16. It is 0 without DPI_Y. |
| 9 | lod | Lod 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)
| Bytes | Field | Notes |
|---|---|---|
| 0 | sensor_index | Target sensor. |
| 1–2 | dpi_x | BE u16. |
| 3–4 | dpi_y | BE u16. The protocol requires zero without DPI_Y. |
| 5 | lod | Lod 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)
| Bytes | Field | Notes |
|---|---|---|
| 0 | sensor_index | Target sensor. |
| 1 | dpi_level | Displayed DPI level. |
| 2 | led_hold_type | 0 through 3 map to LedHoldType. |
| 3 | button_num | HID 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].
| Bytes | Field | Notes |
|---|---|---|
| 0 | echoed sensor_index | OpenLogi requires a match. |
| 1 | mouse_width | Device width in millimetres. |
| 2–3 | mouse_length | BE u16 device length in millimetres. |
| 4–5 | calib_dpi_x | BE u16. |
| 6–7 | calib_dpi_y | BE 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)
| Bytes | Field | Notes |
|---|---|---|
| 0 | sensor_index | Target sensor. |
| 1 | direction | 0 for X or 1 for Y. |
| 2–3 | expected_count | BE u16. Software calibration ignores it. |
| 4 | calib_type | 0 for hardware or 1 for software. |
| 5 | start_timeout | Seconds. The protocol allows at most 60. |
| 6 | hw_process_timeout | Seconds. The protocol allows at most 60. |
| 7 | sw_process_timeout | Seconds. 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)
| Bytes | Field | Notes |
|---|---|---|
| 0 | sensor_index | Target sensor. |
| 1 | direction | 0 for X or 1 for Y. |
| 2–3 | correction | BE 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)
| Bytes | Field | Notes |
|---|---|---|
| 0 | sensor_index | Sensor that changed. |
| 1–2 | dpi_x | BE u16. |
| 3–4 | dpi_y | BE u16. It is 0 without DPI_Y. |
| 5 | lod | Lod value. An unknown value becomes None. |
CalibrationCompleted (sub-id 1)
| Bytes | Field | Notes |
|---|---|---|
| 0 | sensor_index | Sensor that completed calibration. |
| 1 | direction | 0 for X or 1 for Y. An unknown value becomes None. |
| 2–3 | correction | BE signed i16. 0x8000 is the failure sentinel. |
| 4–5 | delta | BE 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(())
}