hidpp/feature/
reprog_controls.rs

1//! Implements `SpecialKeysMseButtons` / `ReprogControlsV4` (feature `0x1b04`).
2//!
3//! Logitech's v6 document names this feature `SpecialKeysMseButtons`: it
4//! enumerates physical and virtual controls, lets host software divert or remap
5//! them, and emits notifications for diverted buttons, raw XY, analytics key
6//! events, and raw wheel movement.
7
8use openlogi_hidpp_derive::Feature;
9
10use crate::{
11    feature::{EventSource, FeatureEndpoint},
12    protocol::v20::Hidpp20Error,
13};
14
15pub mod control_ids;
16mod event;
17pub mod task_ids;
18
19pub use event::{AnalyticsKeyEvent, RawWheelResolution, ReprogControlsEvent, decode_event};
20
21/// Implements the `SpecialKeysMseButtons` / `0x1b04` feature.
22#[derive(Feature)]
23#[creatable(id = 0x1b04, version = 0)]
24pub struct ReprogControlsFeature {
25    endpoint: FeatureEndpoint,
26    events: EventSource<ReprogControlsEvent>,
27}
28
29impl ReprogControlsFeature {
30    /// Returns the number of rows in the control ID table.
31    pub async fn get_count(&self) -> Result<u8, Hidpp20Error> {
32        Ok(self.endpoint.call(0, [0; 3]).await?.extend_payload()[0])
33    }
34
35    /// Returns one row from the control ID table.
36    pub async fn get_cid_info(&self, index: u8) -> Result<CidInfo, Hidpp20Error> {
37        let mut params = [0u8; 16];
38        params[0] = index;
39        let payload = self.endpoint.call_long(1, params).await?.extend_payload();
40        Ok(CidInfo::from_payload(payload))
41    }
42
43    /// Returns the current reporting/remapping state for `cid`.
44    pub async fn get_cid_reporting(&self, cid: ControlId) -> Result<CidReporting, Hidpp20Error> {
45        let [cid_hi, cid_lo] = cid.0.to_be_bytes();
46        let payload = self
47            .endpoint
48            .call(2, [cid_hi, cid_lo, 0])
49            .await?
50            .extend_payload();
51        Ok(CidReporting::from_payload(payload))
52    }
53
54    /// Applies reporting/remapping changes for `cid`.
55    ///
56    /// Optional boolean fields in [`CidReportingChange`] map to the corresponding
57    /// `*-valid` bit in Logitech's packet. Fields set to `None` are left
58    /// unchanged by the device. Remapping is carried as a value field rather
59    /// than a valid/value pair; `None` sends the documented `0` value.
60    pub async fn set_cid_reporting(
61        &self,
62        cid: ControlId,
63        change: CidReportingChange,
64    ) -> Result<CidReportingChangeEcho, Hidpp20Error> {
65        let payload = self
66            .endpoint
67            .call_long(3, change.to_payload(cid))
68            .await?
69            .extend_payload();
70        Ok(CidReportingChangeEcho::from_payload(payload))
71    }
72
73    /// Returns feature-level capabilities.
74    ///
75    /// This function exists on v6 devices. Older firmware may return
76    /// `InvalidFunctionId`.
77    pub async fn get_capabilities(&self) -> Result<ReprogControlsCapabilities, Hidpp20Error> {
78        let payload = self.endpoint.call(4, [0; 3]).await?.extend_payload();
79        Ok(ReprogControlsCapabilities {
80            reset_all_cid_report_settings: payload[0] & 1 != 0,
81        })
82    }
83
84    /// Resets all diverted or remapped control settings.
85    ///
86    /// This function exists on v6 devices that report
87    /// [`ReprogControlsCapabilities::reset_all_cid_report_settings`].
88    pub async fn reset_all_cid_report_settings(&self) -> Result<(), Hidpp20Error> {
89        self.endpoint.call(5, [0; 3]).await?;
90        Ok(())
91    }
92}
93
94/// A HID++ control ID.
95#[derive(
96    Clone,
97    Copy,
98    Debug,
99    Default,
100    PartialEq,
101    Eq,
102    PartialOrd,
103    Ord,
104    Hash,
105    derive_more::From,
106    derive_more::Into,
107)]
108#[cfg_attr(feature = "serde", derive(serde::Serialize))]
109pub struct ControlId(pub u16);
110
111impl ControlId {
112    fn from_payload(bytes: &[u8]) -> Self {
113        Self(u16_from_be_payload(bytes))
114    }
115}
116
117fn u16_from_be_payload(bytes: &[u8]) -> u16 {
118    u16::from_be_bytes([bytes[0], bytes[1]])
119}
120
121/// A HID++ task ID.
122#[derive(
123    Clone,
124    Copy,
125    Debug,
126    Default,
127    PartialEq,
128    Eq,
129    PartialOrd,
130    Ord,
131    Hash,
132    derive_more::From,
133    derive_more::Into,
134)]
135#[cfg_attr(feature = "serde", derive(serde::Serialize))]
136pub struct TaskId(pub u16);
137
138/// One `getCidInfo` row.
139#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
140#[cfg_attr(feature = "serde", derive(serde::Serialize))]
141pub struct CidInfo {
142    /// Control ID.
143    pub cid: ControlId,
144    /// Default task ID currently associated with the control.
145    pub task_id: TaskId,
146    /// Capability and classification flags.
147    pub flags: CidFlags,
148    /// Physical position value reported by the device.
149    pub position: u8,
150    /// Control group number.
151    pub group: u8,
152    /// Bit mask of groups this control belongs to.
153    pub group_mask: GroupMask,
154}
155
156impl CidInfo {
157    fn from_payload(payload: [u8; 16]) -> Self {
158        Self {
159            cid: ControlId::from_payload(&payload[0..=1]),
160            task_id: TaskId(u16_from_be_payload(&payload[2..=3])),
161            flags: CidFlags::from_bytes(payload[4], payload[8]),
162            position: payload[5],
163            group: payload[6],
164            group_mask: GroupMask(payload[7]),
165        }
166    }
167}
168
169bitflags::bitflags! {
170    /// Capability and classification flags for one control ID.
171    #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
172    #[cfg_attr(feature = "serde", derive(serde::Serialize))]
173    pub struct CidFlags: u16 {
174        /// Control belongs to a mouse/pointer device.
175        const MOUSE = 1 << 0;
176        /// Control is a keyboard function key.
177        const FUNCTION_KEY = 1 << 1;
178        /// Control is a hotkey.
179        const HOTKEY = 1 << 2;
180        /// Control toggles Fn behavior.
181        const FN_TOGGLE = 1 << 3;
182        /// Control can be reprogrammed.
183        const REPROGRAMMABLE = 1 << 4;
184        /// Control can be temporarily diverted to HID++ events.
185        const DIVERTABLE = 1 << 5;
186        /// Control can be persistently diverted.
187        const PERSISTENTLY_DIVERTABLE = 1 << 6;
188        /// Control is virtual rather than a physical input.
189        const VIRTUAL_CONTROL = 1 << 7;
190        /// Control supports raw XY reporting.
191        const RAW_XY = 1 << 8;
192        /// Control supports force raw XY reporting.
193        const FORCE_RAW_XY = 1 << 9;
194        /// Control supports analytics key events.
195        const ANALYTICS_KEY_EVENTS = 1 << 10;
196        /// Control supports raw wheel events.
197        const RAW_WHEEL = 1 << 11;
198    }
199}
200
201impl CidFlags {
202    fn from_bytes(primary: u8, additional: u8) -> Self {
203        Self::from_bits_retain(u16::from(primary) | (u16::from(additional) << 8))
204    }
205
206    /// Raw `flags` value used by older OpenLogi diagnostics: primary flags in
207    /// the low byte, additional flags in the high byte.
208    #[must_use]
209    pub fn raw(self) -> u16 {
210        self.bits()
211    }
212
213    /// Whether this is a mouse control.
214    #[must_use]
215    pub fn is_mouse(self) -> bool {
216        self.contains(Self::MOUSE)
217    }
218
219    /// Whether this control can be temporarily diverted to HID++ events.
220    #[must_use]
221    pub fn is_divertable(self) -> bool {
222        self.contains(Self::DIVERTABLE)
223    }
224
225    /// Whether this control can be persistently diverted.
226    #[must_use]
227    pub fn is_persistently_divertable(self) -> bool {
228        self.contains(Self::PERSISTENTLY_DIVERTABLE)
229    }
230
231    /// Whether this is a virtual control.
232    #[must_use]
233    pub fn is_virtual_control(self) -> bool {
234        self.contains(Self::VIRTUAL_CONTROL)
235    }
236
237    /// Whether this control can report raw XY movement while held.
238    #[must_use]
239    pub fn supports_raw_xy(self) -> bool {
240        self.contains(Self::RAW_XY)
241    }
242
243    /// Whether this control can report force raw XY movement while held.
244    #[must_use]
245    pub fn supports_force_raw_xy(self) -> bool {
246        self.contains(Self::FORCE_RAW_XY)
247    }
248
249    /// Whether this control can report analytics key events.
250    #[must_use]
251    pub fn supports_analytics_key_events(self) -> bool {
252        self.contains(Self::ANALYTICS_KEY_EVENTS)
253    }
254
255    /// Whether this control can report raw wheel events.
256    #[must_use]
257    pub fn supports_raw_wheel(self) -> bool {
258        self.contains(Self::RAW_WHEEL)
259    }
260}
261
262/// Group mask `g1..g8` from `getCidInfo`.
263#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
264#[cfg_attr(feature = "serde", derive(serde::Serialize))]
265pub struct GroupMask(pub u8);
266
267/// Current reporting/remapping state returned by `getCidReporting`.
268#[expect(
269    clippy::struct_excessive_bools,
270    reason = "each field is an independent wire flag from getCidReporting, not a state machine"
271)]
272#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
273#[cfg_attr(feature = "serde", derive(serde::Serialize))]
274pub struct CidReporting {
275    /// Control ID whose reporting state was read.
276    pub cid: ControlId,
277    /// Whether temporary diversion is enabled.
278    pub diverted: bool,
279    /// Whether persistent diversion is enabled.
280    pub persistently_diverted: bool,
281    /// Whether force raw XY reporting is enabled.
282    pub force_raw_xy: bool,
283    /// Whether raw XY reporting is enabled.
284    pub raw_xy: bool,
285    /// Optional remapping target control ID.
286    pub remap: Option<ControlId>,
287    /// Whether analytics key events are enabled.
288    pub analytics_key_events: bool,
289    /// Whether raw wheel reporting is enabled.
290    pub raw_wheel: bool,
291}
292
293impl CidReporting {
294    fn from_payload(payload: [u8; 16]) -> Self {
295        let remap = ControlId::from_payload(&payload[3..=4]);
296        Self {
297            cid: ControlId::from_payload(&payload[0..=1]),
298            diverted: payload[2] & (1 << 0) != 0,
299            persistently_diverted: payload[2] & (1 << 2) != 0,
300            raw_xy: payload[2] & (1 << 4) != 0,
301            force_raw_xy: payload[2] & (1 << 6) != 0,
302            remap: (remap.0 != 0).then_some(remap),
303            analytics_key_events: payload[5] & (1 << 0) != 0,
304            raw_wheel: payload[5] & (1 << 2) != 0,
305        }
306    }
307}
308
309/// Changes for `setCidReporting`.
310///
311/// For boolean fields, `None` means "leave unchanged". Remapping is encoded as
312/// the packet's value field and defaults to the documented `0` value.
313#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
314#[cfg_attr(feature = "serde", derive(serde::Serialize))]
315pub struct CidReportingChange {
316    /// New temporary diversion state, or `None` to leave unchanged.
317    pub diverted: Option<bool>,
318    /// New persistent diversion state, or `None` to leave unchanged.
319    pub persistently_diverted: Option<bool>,
320    /// New force raw XY state, or `None` to leave unchanged.
321    pub force_raw_xy: Option<bool>,
322    /// New raw XY state, or `None` to leave unchanged.
323    pub raw_xy: Option<bool>,
324    /// Remaps to another control ID. `None` sends the documented `0` value,
325    /// which represents no persistent remapping.
326    pub remap: Option<ControlId>,
327    /// New analytics key event state, or `None` to leave unchanged.
328    pub analytics_key_events: Option<bool>,
329    /// New raw wheel state, or `None` to leave unchanged.
330    pub raw_wheel: Option<bool>,
331}
332
333impl CidReportingChange {
334    fn to_payload(self, cid: ControlId) -> [u8; 16] {
335        let mut payload = [0u8; 16];
336        let [cid_hi, cid_lo] = cid.0.to_be_bytes();
337        payload[0] = cid_hi;
338        payload[1] = cid_lo;
339
340        if let Some(value) = self.diverted {
341            payload[2] |= 1 << 1;
342            payload[2] |= u8::from(value);
343        }
344        if let Some(value) = self.persistently_diverted {
345            payload[2] |= 1 << 3;
346            payload[2] |= u8::from(value) << 2;
347        }
348        if let Some(value) = self.raw_xy {
349            payload[2] |= 1 << 5;
350            payload[2] |= u8::from(value) << 4;
351        }
352        if let Some(value) = self.force_raw_xy {
353            payload[2] |= 1 << 7;
354            payload[2] |= u8::from(value) << 6;
355        }
356        if let Some(remap) = self.remap {
357            let [remap_hi, remap_lo] = remap.0.to_be_bytes();
358            payload[3] = remap_hi;
359            payload[4] = remap_lo;
360        }
361        if let Some(value) = self.analytics_key_events {
362            payload[5] |= 1 << 1;
363            payload[5] |= u8::from(value);
364        }
365        if let Some(value) = self.raw_wheel {
366            payload[5] |= 1 << 3;
367            payload[5] |= u8::from(value) << 2;
368        }
369
370        payload
371    }
372}
373
374/// Echo returned by `setCidReporting`.
375#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
376#[cfg_attr(feature = "serde", derive(serde::Serialize))]
377pub struct CidReportingChangeEcho {
378    /// Control ID whose reporting state was changed.
379    pub cid: ControlId,
380    /// Echoed temporary diversion state when changed.
381    pub diverted: Option<bool>,
382    /// Echoed persistent diversion state when changed.
383    pub persistently_diverted: Option<bool>,
384    /// Echoed force raw XY state when changed.
385    pub force_raw_xy: Option<bool>,
386    /// Echoed raw XY state when changed.
387    pub raw_xy: Option<bool>,
388    /// Echoed remapping target when present.
389    pub remap: Option<ControlId>,
390    /// Echoed analytics key event state when changed.
391    pub analytics_key_events: Option<bool>,
392    /// Echoed raw wheel state when changed.
393    pub raw_wheel: Option<bool>,
394}
395
396impl CidReportingChangeEcho {
397    fn from_payload(payload: [u8; 16]) -> Self {
398        let remap = ControlId::from_payload(&payload[3..=4]);
399        Self {
400            cid: ControlId::from_payload(&payload[0..=1]),
401            diverted: (payload[2] & (1 << 1) != 0).then_some(payload[2] & (1 << 0) != 0),
402            persistently_diverted: (payload[2] & (1 << 3) != 0)
403                .then_some(payload[2] & (1 << 2) != 0),
404            raw_xy: (payload[2] & (1 << 5) != 0).then_some(payload[2] & (1 << 4) != 0),
405            force_raw_xy: (payload[2] & (1 << 7) != 0).then_some(payload[2] & (1 << 6) != 0),
406            remap: (remap.0 != 0).then_some(remap),
407            analytics_key_events: (payload[5] & (1 << 1) != 0)
408                .then_some(payload[5] & (1 << 0) != 0),
409            raw_wheel: (payload[5] & (1 << 3) != 0).then_some(payload[5] & (1 << 2) != 0),
410        }
411    }
412}
413
414/// Feature-level capabilities returned by `getCapabilities` on v6 devices.
415#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
416#[cfg_attr(feature = "serde", derive(serde::Serialize))]
417pub struct ReprogControlsCapabilities {
418    /// Whether `resetAllCidReportSettings` is supported.
419    pub reset_all_cid_report_settings: bool,
420}
421
422#[cfg(test)]
423mod tests;
hidpp/feature/reprog_controls.rs

hidpp/feature/
reprog_controls.rs
