OpenLogi

0x19b0 · hapticFeedback

Device-wide haptic configuration, capability-gated waveform playback, and readiness checks for the MX Master 4 Actions Ring.

Controls a device haptic actuator. It reports waveform support, device-wide haptic flags, intensity, and readiness. OpenLogi uses two typed waveforms for the Actions Ring on the MX Master 4.

Spec: No public Logitech specification. Layout reverse-engineered from Logi Options+ 2.8 (static analysis). Cross-checked: Solaar. Used by: Actions Ring on the MX Master 4.

Function reference

HapticFeedbackFeature (0x19b0) exposes the following methods.

Methods

FunctionHID++ fnSignatureReturns
get_capabilities0()HapticCapabilities
get_configuration1()HapticConfiguration
set_configuration2(flags: HapticConfigFlags, intensity: HapticIntensity)HapticConfiguration
get_haptic_status3()HapticStatus
play4(waveform: HapticWaveform)()

All methods are async and return Result<…, Hidpp20Error>.

Types

SupportedWaveforms

This mask retains unknown bits. supports checks bit N for waveform ID N. OpenLogi names only the two waveforms it uses.

FlagBitDescription
DAMP_STATE_CHANGE1Confirmation pulse after an action runs.
SUBTLE_COLLISION4Light boundary pulse for a slot change.

HapticWaveform

VariantValueDescription
DampStateChange1Confirmation pulse.
SubtleCollision4Boundary pulse.

HapticConfigFlags

HapticConfigFlags retains unknown bits. Build a write from get_configuration() so unmodelled flags survive.

FlagBitDescription
ENABLED0Firmware haptic playback is enabled.
POWER_SAVE1Battery-saving haptics setting. Options+ controls it independently.

HapticConfiguration

FieldTypeDescription
flagsHapticConfigFlagsReported flag byte, including retained unknown bits.
intensityHapticIntensityCurrent intensity percentage.
level_countu8Low nibble of response byte 2.
level_stepu8High nibble of response byte 2.

HapticIntensity

HapticIntensity::new(value) accepts 0–100. It returns None for a larger value. get() returns the percentage sent on the wire.

HapticStatus

HapticStatus wraps the raw status byte from fn 3. is_ready() is true only for 0. Other values remain raw because their meanings are not established.

Events

HapticFeedbackFeature does not implement EmittingFeature. OpenLogi exposes no haptic report events.

Wire format

All implemented requests use a three-byte short payload. The waveform mask is a BE u32. The exact meaning of capability bytes 0–3 and the complete level-format definition remain unverified.

get_capabilities (fn 0)

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

BytesFieldNotes
0–3unknown_prefixMeaning is unverified.
4–7waveformsBE u32; bit N advertises waveform ID N.

get_configuration (fn 1)

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

ByteFieldNotes
0flagsBit 0 is ENABLED; bit 1 is POWER_SAVE; higher bits are retained. Options+ 2.8
1intensityPercentage from 0 through 100.
2level formatHigh nibble is level_step; low nibble is level_count. Full semantics are unverified.

set_configuration (fn 2)

Request: [flags, intensity, 0x00].

The response has the fn-1 configuration layout. OpenLogi decodes and returns it. The response is device state, not an assumed request echo.

get_haptic_status (fn 3)

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

ByteFieldNotes
0status0 is ready. Any nonzero value is not ready. Options+ 2.8

play (fn 4)

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

Byte 0 is the waveform ID. Options+ 2.8 uses byte 1 to request a waveform-information report. OpenLogi writes 0 because it does not receive that report. The response is an acknowledgement.

stopHapticWaveForm (fn 5)

Logi Options+ 2.8 calls fn 5 to stop a waveform after it checks playing state. OpenLogi does not expose this function. Its request and response layout are not verified.

getPlayingWaveForm (fn 6)

Logi Options+ 2.8 calls fn 6 before it decides to stop a waveform. OpenLogi does not expose this function. Its request and response layout are not verified.

Reports

Options+ 2.8 static analysis identifies two unsolicited report layouts. OpenLogi does not parse either report.

Sub-idPayloadNotes
0Byte 0 is haptic status.Options+ 2.8
1Two bytes.Waveform-information fields are unverified. Options+ 2.8

How OpenLogi uses it

At an Actions Ring session start, OpenLogi resolves 0x19b0, reads the capability mask, and reads haptic status. The status read has a 250 ms deadline. A timeout or read error leaves status unknown and permits playback.

OpenLogi rejects a play before transmission when the mask lacks the waveform. It also rejects a play when a successfully read status is nonzero. The two Actions Ring waveforms are SubtleCollision for slot changes and DampStateChange for activation.

The arming path reads the configuration. If ENABLED is clear and intensity is nonzero, it changes only that bit and writes the complete flag byte. It preserves POWER_SAVE, unknown flag bits, and intensity. It accepts the repair only when the returned configuration has ENABLED set.

A zero intensity means user-off. Since v0.8.14, OpenLogi does not replace it with 25. Actions Ring cancellation cancels the ring session only. OpenLogi has no fn-5 stop operation or report listener.

Open questions

Options+ treats global haptics and each event source as playback conditions. OpenLogi can re-enable the device-wide ENABLED bit when an Actions Ring starts. Evidence from an earlier implementation says power transitions can clear that bit. Hardware testing has not shown whether it is only a transient arm state.

OpenLogi does not restore ENABLED when the session closes. It preserves every other configuration bit and the intensity. The product policy remains open: skip feedback when haptics are disabled, or use a session-scoped override with restore.

The complete byte-2 level format, fn-5 and fn-6 layouts, and waveform-information report fields require hardware capture. The protocol persistence boundary for the configuration flags also remains unverified.

Usage (Rust)

use hidpp::{
    device::Device,
    feature::{
        haptic_feedback::{
            HapticConfigFlags, HapticFeedbackFeature, HapticWaveform,
        },
    },
};

// `device` is already created for a HID++ channel and device index.
device.enumerate_features().await?;
if let Some(feature) = device.get_feature::<HapticFeedbackFeature>() {
    let capabilities = feature.get_capabilities().await?;
    let status = feature.get_haptic_status().await?;

    if capabilities.waveforms.supports(HapticWaveform::SubtleCollision)
        && status.is_ready()
    {
        let configuration = feature.get_configuration().await?;
        let applied = feature
            .set_configuration(
                configuration.flags | HapticConfigFlags::ENABLED,
                configuration.intensity,
            )
            .await?;
        if applied.flags.contains(HapticConfigFlags::ENABLED) {
            feature.play(HapticWaveform::SubtleCollision).await?;
        }
    }
}

On this page