🔌 HID++ Protocol

Note

For how this protocol layer fits into the overall system, see Architecture.

📦 Report Format

📄 Short Report (7 bytes)

Byte: [0] [1] [2] [3] [4..6]
 reportId deviceIndex featureIndex funcId|swId params (3 bytes)
 0x10

📄 Long Report (20 bytes)

Byte: [0] [1] [2] [3] [4..19]
 reportId deviceIndex featureIndex funcId|swId params (16 bytes)
 0x11

📋 Field Details

🔢 Byte[3] Encoding

Byte[3] = (functionId << 4) | softwareId

Tip

Example: functionId=2, softwareId=5 -> byte[3] = 0x25

❌ Error Report

Byte: [0] [1] [2] [3] [4] [5] [6]
 0x11 deviceIndex 0xFF featureIndex funcId errorCode 0x00

💻 Logitune Implementation

struct Report {
 uint8_t reportId{};
 uint8_t deviceIndex{};
 uint8_t featureIndex{};
 uint8_t functionId{}; // upper 4 bits of byte[3]
 uint8_t softwareId{}; // lower 4 bits of byte[3]
 std::array<uint8_t, 16> params{};
 int paramLength{};
 std::vector<uint8_t> serialize() const;
 static std::optional<Report> parse(std::span<const uint8_t> data);
 bool isError() const;
 ErrorCode errorCode() const;
};

🔍 Feature Discovery

🏠 Root Feature (0x0000)

Request: featureIndex=0x00, functionId=0, params=[featureId_hi, featureId_lo]
Response: params[0] = featureIndex (device-assigned), params[1] = featureType

🔄 Enumeration Flow

Note

The feature table is stored as std::unordered_map<FeatureId, uint8_t>. All subsequent calls use FeatureDispatcher::call() or callAsync(), which look up the feature index automatically.

🔧 Key Features

🔋 Battery Unified (0x1004)

// params[0] = battery level (0-100)
// params[1] = next level (predictive)
// params[2] = status: 0=discharging, 1-3=charging, 4=charged

Tip

The device sends battery notifications when the level changes or charging state changes. Same format as GetStatus response.

🔀 ReprogControlsV4 (0x1b04)

Bit 0: divert (1 = send to software, 0 = native)
Bit 1: dvalid (1 = divert bit is valid)
Bit 2: rawXY (1 = also send raw XY deltas)
Bit 3: rvalid (1 = rawXY bit is valid)

// From hidpp/features/ReprogControls.cpp
auto ReprogControls::buildSetDivert(uint16_t controlId, bool divert, bool rawXY)
 -> std::array<uint8_t, 4>
{
 uint8_t flags = 0x02; // dvalid=1
 if (divert) flags |= 0x01;
 if (rawXY) flags |= 0x0C; // rawXY=1, rvalid=1
 return {
 static_cast<uint8_t>(controlId >> 8),
 static_cast<uint8_t>(controlId & 0xFF),
 flags,
 0x00
 };
}

Important

The release event sends CID=0 (all buttons released), not the CID of the released button. This is important for gesture resolution — the gesture completes when controlId == 0.

⚙️ SmartShift (0x2110)

Tip

autoDisengage: Threshold (1-255) at which the wheel switches from ratchet to freespin during fast scrolling. Higher = more force needed to trigger freespin.

📜 HiResWheel (0x2121)

Bit 0: target (0=HID, 1=HID++)
Bit 1: resolution (0=low-res, 1=hi-res)
Bit 2: invert (0=standard, 1=inverted/natural)
Bit 3: analytics (reserved)

Note

Logitune reads the full mode byte and only modifies bits 1 (hiRes) and 2 (invert), preserving the rest.

🔄 ThumbWheel (0x2150)

params[0-1]: nativeResolution (uint16, big-endian)
params[2-3]: divertedResolution (uint16, big-endian)
params[4]: bit 0 = defaultDirection (0=positive when left, 1=positive when right)

params[0]: divert (0x00=native, 0x01=diverted to software)
params[1]: invert (0x00=normal, 0x01=inverted direction)

params[0-1]: rotation delta (int16, signed, big-endian)

🧭 Direction Normalization

// In AppController::onThumbWheelRotation:
int normalized = delta * m_deviceManager.thumbWheelDefaultDirection();
// defaultDirection=0 -> thumbWheelDefaultDirection=-1
// Multiplying by -1 makes clockwise = positive

🎚️ AdjustableDPI (0x2201)

Note

The MX Master 3S has one sensor (index 0) with range 200-8000 and step 50.

🔌 ChangeHost (0x1814)

🏷️ DeviceName (0x0005)

Tip

The device name is read in 13-byte chunks. For the MX Master 3S, the name is "MX Master 3S" (12 bytes, one chunk).

📡 Bolt Receiver Protocol

🔗 DeviceConnection Notifications (Register 0x41)

Byte: [0] [1] [2] [3] [4] [5] [6]
 0x10 deviceIndex 0x41 ?? flags ?? ??

Bit 6: link (0 = established, 1 = not established)

🔄 Handling in Logitune

📡 Receiver Slot Probing

// QSocketNotifier on receiver fd
// Any HID++ traffic from device index 1-6 means a device appeared
if (bytes.size() >= 3 && bytes[1] >= 1 && bytes[1] <= 6) {
 // Device arrived — disconnect current transport, probe receiver again
}

🔗 softwareId for Async Response Matching

❓ The Problem

Caution

Example bug: Thumb wheel SetReporting (function 0x02) sends a response with featureIndex matching ThumbWheel. If softwareId is 0, this looks like a thumb wheel rotation notification with delta = 256 (the SetReporting confirmation bytes interpreted as rotation). This was the "delta=256 bug".

✅ The Solution

uint8_t FeatureDispatcher::nextSoftwareId() {
 uint8_t id = m_nextSwId;
 m_nextSwId = (m_nextSwId % 15) + 1; // rotate 1-15
 return id;
}

if (report.softwareId != 0) {
 if (m_features)
 m_features->handleResponse(report);
 return; // Not a notification — don't process as input event
}

bool FeatureDispatcher::handleResponse(const Report &report) {
 auto it = m_pendingCallbacks.find(report.softwareId);
 if (it != m_pendingCallbacks.end()) {
 if (it->second)
 it->second(report);
 m_pendingCallbacks.erase(it);
 return true;
 }
 return false;
}

🛡️ Error Handling and Retry

📡 Transport Layer

📨 CommandQueue Layer

⚠️ Common Error Scenarios

📚 References

🔧 Useful Commands for Protocol Debugging

# Watch raw HID++ traffic
sudo cat /dev/hidrawN | xxd
# Run Logitune with full protocol logging
./build/src/app/logitune --debug 2>&1 | grep lcHidpp
# Identify hidraw interfaces for a device
ls -la /sys/class/hidraw/*/device/
# Read report descriptor (check for HID++ report IDs)
xxd /sys/class/hidraw/hidrawN/device/report_descriptor
# Look for 0x85 0x11 (long report) or 0x85 0x10 (short report)