Adding a Device

Mina Maher edited this page Apr 12, 2026 · 8 revisions

Adding a Device

This guide walks through adding support for a new Logitech HID++ 2.0 device to Logitune. We use the MX Master 3S descriptor as the reference implementation and work through a hypothetical "MX Anywhere 3S" as a complete example.

Prerequisites

Before starting, you need:

The device's Product ID (PID) — from lsusb, /sys/class/hidraw/*/device/, or Solaar
The device's Control IDs (CIDs) — from ReprogControlsV4 feature enumeration
The device's DPI range — from AdjustableDPI feature
The device's supported features — from feature enumeration
Device images — front, side, and back photos/renders (PNG)

Step 1: Understand the IDevice Interface

Every device descriptor implements IDevice (defined in src/core/interfaces/IDevice.h):

class IDevice {
public:
 virtual ~IDevice() = default;
 virtual QString deviceName() const = 0;
 virtual std::vector<uint16_t> productIds() const = 0;
 virtual bool matchesPid(uint16_t pid) const = 0;
 virtual QList<ControlDescriptor> controls() const = 0;
 virtual QList<HotspotDescriptor> buttonHotspots() const = 0;
 virtual QList<HotspotDescriptor> scrollHotspots() const = 0;
 virtual FeatureSupport features() const = 0;
 virtual QString frontImagePath() const = 0;
 virtual QString sideImagePath() const = 0;
 virtual QString backImagePath() const = 0;
 virtual QMap<QString, ButtonAction> defaultGestures() const = 0;
 virtual int minDpi() const = 0;
 virtual int maxDpi() const = 0;
 virtual int dpiStep() const = 0;
 virtual QList<EasySwitchSlotPosition> easySwitchSlotPositions() const = 0;
};

Key Structs

ControlDescriptor — describes a button or control:

struct ControlDescriptor {
 uint16_t controlId; // HID++ CID (e.g., 0x0050 for left click)
 int buttonIndex; // 0-based index into Profile::buttons array
 QString defaultName; // Display name (e.g., "Left click")
 QString defaultActionType; // "default", "gesture-trigger", "smartshift-toggle"
 bool configurable; // Can the user reassign this button?
};

HotspotDescriptor — positions interactive dots on the device render:

struct HotspotDescriptor {
 int buttonIndex; // Matches ControlDescriptor::buttonIndex, or negative for scroll zones
 double xPct; // X position as fraction of image width (0.0 - 1.0)
 double yPct; // Y position as fraction of image height (0.0 - 1.0)
 QString side; // "left" or "right" — which side of the hotspot the label appears
 double labelOffsetYPct; // Vertical offset for the label (prevents overlap)
};

FeatureSupport — which HID++ features the device supports:

struct FeatureSupport {
 bool battery = false;
 bool adjustableDpi = false;
 bool smartShift = false;
 bool hiResWheel = false;
 bool thumbWheel = false;
 bool reprogControls = false;
 bool gestureV2 = false;
};

Note: You don't need to specify which variant of a feature your device uses. For example, set battery = true regardless of whether the device uses Battery Unified (0x1004) or Battery Status (0x1000). DeviceManager auto-detects the variant at runtime via capability dispatch tables (see src/core/hidpp/capabilities/). Same applies to SmartShift V1 vs Enhanced.

Step 2: Find the Device's PIDs and Features

Using hidraw tools

List Logitech hidraw devices:

# Find all Logitech hidraw devices
for f in /sys/class/hidraw/hidraw*/device/; do
 vendor=$(cat "$f/../../modalias" 2>/dev/null | grep -oP '(?<=v0000046D)p[0-9A-F]+' | sed 's/p/0x/')
 if [ -n "$vendor" ]; then
 echo "$(basename $(dirname $f)): PID=$vendor"
 fi
done

Using Solaar

Solaar's command-line interface provides detailed device info:

solaar show
# Look for "Product ID", "Serial Number", and "Features"
solaar config <device-name>
# Shows current settings

Using logiops / libratbag

# logiops debug output shows feature enumeration
sudo logiops -v debug
# ratbagctl for device capabilities
ratbagctl list
ratbagctl <device> info

Manual HID++ enumeration

You can use the Logitune debug log to enumerate features. Connect the new device and run:

./build/src/app/logitune --debug 2>&1 | grep -E "(feature|PID|CID|DPI)"

The log output will show all discovered features and their indices.

Step 3: Create the Descriptor

Create two files in src/core/devices/:

Header: `MxAnywhere3sDescriptor.h`

#pragma once
#include "interfaces/IDevice.h"
namespace logitune {
class MxAnywhere3sDescriptor : public IDevice {
public:
 QString deviceName() const override;
 std::vector<uint16_t> productIds() const override;
 bool matchesPid(uint16_t pid) const override;
 QList<ControlDescriptor> controls() const override;
 QList<HotspotDescriptor> buttonHotspots() const override;
 QList<HotspotDescriptor> scrollHotspots() const override;
 FeatureSupport features() const override;
 QString frontImagePath() const override;
 QString sideImagePath() const override;
 QString backImagePath() const override;
 QMap<QString, ButtonAction> defaultGestures() const override;
 int minDpi() const override;
 int maxDpi() const override;
 int dpiStep() const override;
 QList<EasySwitchSlotPosition> easySwitchSlotPositions() const override;
};
} // namespace logitune

Implementation: `MxAnywhere3sDescriptor.cpp`

#include "MxAnywhere3sDescriptor.h"
namespace logitune {
QString MxAnywhere3sDescriptor::deviceName() const
{
 return QStringLiteral("MX Anywhere 3S");
}
std::vector<uint16_t> MxAnywhere3sDescriptor::productIds() const
{
 // Include all known PIDs: Bolt receiver PID, Bluetooth PID, USB PID
 return { 0xb037 }; // Example PID — replace with actual
}
bool MxAnywhere3sDescriptor::matchesPid(uint16_t pid) const
{
 for (auto id : productIds()) {
 if (id == pid)
 return true;
 }
 return false;
}
QList<ControlDescriptor> MxAnywhere3sDescriptor::controls() const
{
 return {
 // CID, index, name, defaultAction, configurable
 { 0x0050, 0, QStringLiteral("Left click"), QStringLiteral("default"), false },
 { 0x0051, 1, QStringLiteral("Right click"), QStringLiteral("default"), false },
 { 0x0052, 2, QStringLiteral("Middle click"), QStringLiteral("default"), true },
 { 0x0053, 3, QStringLiteral("Back"), QStringLiteral("default"), true },
 { 0x0056, 4, QStringLiteral("Forward"), QStringLiteral("default"), true },
 // The MX Anywhere 3S has no gesture button or thumb wheel — adjust accordingly
 { 0x00C4, 5, QStringLiteral("Shift wheel mode"), QStringLiteral("smartshift-toggle"),true },
 };
}
QList<HotspotDescriptor> MxAnywhere3sDescriptor::buttonHotspots() const
{
 // Position hotspots relative to the device image
 // Use an image editor to find x/y percentages
 return {
 { 2, 0.65, 0.20, QStringLiteral("right"), 0.0 }, // Middle click
 { 5, 0.75, 0.38, QStringLiteral("right"), 0.0 }, // Shift wheel mode
 { 4, 0.30, 0.40, QStringLiteral("left"), 0.0 }, // Forward
 { 3, 0.40, 0.55, QStringLiteral("left"), 0.0 }, // Back
 };
}
QList<HotspotDescriptor> MxAnywhere3sDescriptor::scrollHotspots() const
{
 return {
 { -1, 0.68, 0.18, QStringLiteral("right"), 0.0 }, // Main wheel
 };
}
FeatureSupport MxAnywhere3sDescriptor::features() const
{
 FeatureSupport f;
 f.battery = true;
 f.adjustableDpi = true;
 f.smartShift = true;
 f.hiResWheel = true;
 f.thumbWheel = false; // MX Anywhere 3S has no thumb wheel
 f.reprogControls = true;
 f.gestureV2 = false;
 return f;
}
QString MxAnywhere3sDescriptor::frontImagePath() const
{
 return QStringLiteral("qrc:/Logitune/qml/assets/mx-anywhere-3s.png");
}
QString MxAnywhere3sDescriptor::sideImagePath() const
{
 return QStringLiteral("qrc:/Logitune/qml/assets/mx-anywhere-3s-side.png");
}
QString MxAnywhere3sDescriptor::backImagePath() const
{
 return QStringLiteral("qrc:/Logitune/qml/assets/mx-anywhere-3s-back.png");
}
QMap<QString, ButtonAction> MxAnywhere3sDescriptor::defaultGestures() const
{
 // No gesture button on MX Anywhere 3S — return empty
 return {};
}
int MxAnywhere3sDescriptor::minDpi() const { return 200; }
int MxAnywhere3sDescriptor::maxDpi() const { return 8000; }
int MxAnywhere3sDescriptor::dpiStep() const { return 50; }
QList<EasySwitchSlotPosition> MxMaster3sDescriptor::easySwitchSlotPositions() const
{
 return {
 { 0.325, 0.658 }, // 1
 { 0.384, 0.642 }, // 2
 { 0.443, 0.643 }, // 3
 };
}
} // namespace logitune

Step 4: Add Device Images

Place device images in src/app/qml/assets/:

mx-anywhere-3s.png — front view (used as the main device render on the Buttons page)
mx-anywhere-3s-side.png — side view
mx-anywhere-3s-back.png — back view

Then register them in src/app/CMakeLists.txt under the RESOURCES section of qt_add_qml_module:

RESOURCES
 qml/assets/mx-master-3s.png
 qml/assets/mx-master-3s-back.png
 qml/assets/mx-master-3s-side.png
 qml/assets/mx-anywhere-3s.png # Add these
 qml/assets/mx-anywhere-3s-side.png
 qml/assets/mx-anywhere-3s-back.png

Image Guidelines

Format: PNG with transparency
Resolution: High enough for 2x display scaling (~800px wide is good)
Orientation: Front view should show the device from the right side, angled slightly
Background: Transparent

Step 5: Position Hotspots

Hotspot positions are defined as fractions of the image dimensions (0.0 to 1.0). To find the right positions:

Open the front image in an image editor
Note the pixel coordinates of each button/control center
Divide by image width/height to get the percentage

For each hotspot, decide:

side: "left" or "right" — which side of the dot the label line extends to
labelOffsetYPct: If two hotspots are close vertically, offset one label to prevent overlap

The MX Master 3S example:

QList<HotspotDescriptor> MxMaster3sDescriptor::buttonHotspots() const
{
 return {
 { 2, 0.71, 0.15, QStringLiteral("right"), 0.0 }, // Middle click
 { 6, 0.81, 0.34, QStringLiteral("right"), 0.0 }, // Shift wheel mode
 { 7, 0.55, 0.515, QStringLiteral("right"), 0.0 }, // Thumb wheel
 { 4, 0.35, 0.43, QStringLiteral("left"), 0.0 }, // Forward
 { 3, 0.45, 0.60, QStringLiteral("left"), 0.20 }, // Back (offset label)
 { 5, 0.08, 0.58, QStringLiteral("left"), 0.0 }, // Gesture button
 };
}

Scroll hotspots use negative buttonIndex values to indicate they are not buttons:

-1 — main scroll wheel
-2 — thumb wheel (horizontal)
-3 — scroll wheel side (mode switch area)

Step 6: Register in DeviceRegistry

Edit src/core/DeviceRegistry.cpp:

#include "DeviceRegistry.h"
#include "devices/MxMaster3sDescriptor.h"
#include "devices/MxAnywhere3sDescriptor.h" // Add this
namespace logitune {
DeviceRegistry::DeviceRegistry() {
 registerDevice(std::make_unique<MxMaster3sDescriptor>());
 registerDevice(std::make_unique<MxAnywhere3sDescriptor>()); // Add this
}
// ... rest unchanged

Step 7: Add to CMakeLists.txt

Edit src/core/CMakeLists.txt to include the new descriptor source:

target_sources(logitune-core PRIVATE
 # ... existing files ...
 devices/MxMaster3sDescriptor.cpp
 devices/MxAnywhere3sDescriptor.cpp # Add this
)

Step 8: Testing

Unit Test

Create a test to verify the descriptor returns valid data:

// In tests/test_device_registry.cpp
static const DeviceSpec kDevices[] = {
 ...
 {
 .pid = 0xb034,
 .name = "MX Anywhere 3S",
 .minDpi = 200, .maxDpi = 8000, .dpiStep = 50,
 .buttonHotspots = 6, .scrollHotspots = 3,
 .minControls = 7,
 .control0Cid = 0x0050, .control5Cid = 0x00C3,
 .control5ActionType = "gesture-trigger",
 .control6ActionType = "smartshift-toggle",
 .battery = true, .adjustableDpi = true, .smartShift = true,
 .reprogControls = true, .gestureV2 = false,
 .gestureDownType = ButtonAction::Keystroke,
 .gestureDownPayload = "Super+D",
 .gestureUpType = ButtonAction::Default,
 },
};

Mock Device Setup

Add a helper to MockDevice (in tests/mocks/MockDevice.h) for the new device:

void setupMxAnywhereControls() {
 m_deviceName = QStringLiteral("MX Anywhere 3S");
 m_productIds = { 0xb037 };
 m_features.reprogControls = true;
 m_features.battery = true;
 m_features.adjustableDpi = true;
 m_features.smartShift = true;
 m_features.hiResWheel = true;
 m_features.thumbWheel = false;
 // ... populate m_controls
}

Hardware Test

If you have the physical device, enable hardware tests:

cmake -B build -DBUILD_HW_TESTING=ON
cmake --build build
./build/tests/hw/logitune-hw-tests

The HardwareFixture will detect the device and run integration tests. Make sure the device is connected and awake.

Manual Testing Checklist

Device is detected on Bolt receiver connection
Device is detected on Bluetooth connection
Battery level reads correctly
DPI changes apply and persist across profile switches
SmartShift toggle works
All configurable buttons divert and un-divert correctly
Button remapping works (keystroke injection)
Profile switching works on window focus change
Device images render correctly in the Buttons page
Hotspots align with the correct buttons
Disconnect/reconnect works cleanly

Step 9: Notes on PIDs

A single device may have multiple PIDs:

Bolt receiver PID — reported by the receiver when the device is connected wirelessly via Bolt
Bluetooth PID — the PID seen when connected directly via Bluetooth
USB PID — if the device supports wired USB connection

For Bolt connections, DeviceManager matches by PID first, then falls back to matching by device name (read via the DeviceName HID++ feature). So even if the Bolt PID differs from the Bluetooth PID, the device will be found as long as either:

One of the PIDs is in productIds(), or
The device name matches via DeviceRegistry::findByName()

Include all known PIDs in productIds() for the most reliable matching.

Reference: MX Master 3S Control Map

For reference, here is the complete control map of the MX Master 3S:

CID	Index	Name	Default Action	Configurable
`0x0050`	0	Left click	default	No
`0x0051`	1	Right click	default	No
`0x0052`	2	Middle click	default	Yes
`0x0053`	3	Back	default	Yes
`0x0056`	4	Forward	default	Yes
`0x00C3`	5	Gesture button	gesture-trigger	Yes
`0x00C4`	6	Shift wheel mode	smartshift-toggle	Yes
`0x0000`	7	Thumb wheel	default	Yes

Button index 7 (thumb wheel) uses CID 0x0000 because it is a virtual entry — the thumb wheel is controlled via the ThumbWheel feature (0x2150), not ReprogControlsV4.

Logitune Wiki

🏠 Home

📚 User Guide

🏗️ Architecture

🔧 Extending

🧪 Quality

Navigation Menu

Adding a Device

Adding a Device

Prerequisites

Step 1: Understand the IDevice Interface

Key Structs

Step 2: Find the Device's PIDs and Features

Using hidraw tools

Using Solaar

Using logiops / libratbag

Manual HID++ enumeration

Step 3: Create the Descriptor

Header: `MxAnywhere3sDescriptor.h`

Implementation: `MxAnywhere3sDescriptor.cpp`

Step 4: Add Device Images

Image Guidelines

Step 5: Position Hotspots

Step 6: Register in DeviceRegistry

Step 7: Add to CMakeLists.txt

Step 8: Testing

Unit Test

Mock Device Setup

Hardware Test

Manual Testing Checklist

Step 9: Notes on PIDs

Reference: MX Master 3S Control Map

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Adding a Device

Adding a Device

Prerequisites

Step 1: Understand the IDevice Interface

Key Structs

Step 2: Find the Device's PIDs and Features

Using hidraw tools

Using Solaar

Using logiops / libratbag

Manual HID++ enumeration

Step 3: Create the Descriptor

Header: MxAnywhere3sDescriptor.h

Implementation: MxAnywhere3sDescriptor.cpp

Step 4: Add Device Images

Image Guidelines

Step 5: Position Hotspots

Step 6: Register in DeviceRegistry

Step 7: Add to CMakeLists.txt

Step 8: Testing

Unit Test

Mock Device Setup

Hardware Test

Manual Testing Checklist

Step 9: Notes on PIDs

Reference: MX Master 3S Control Map

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Header: `MxAnywhere3sDescriptor.h`

Implementation: `MxAnywhere3sDescriptor.cpp`