Adding a Device

Mina Maher edited this page Apr 1, 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.

Note

Before starting, make sure you understand the Architecture and HID++ Protocol pages.

📋 Prerequisites

Before starting, you need:

Requirement	Source
🔢 Product ID (PID)	`lsusb`, `/sys/class/hidraw/*/device/`, or Solaar
🔀 Control IDs (CIDs)	ReprogControlsV4 feature enumeration
🎚️ DPI range	AdjustableDPI feature
📋 Supported features	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 int easySwitchSlots() 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;
};

🔍 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)"

Tip

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;
 int easySwitchSlots() 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; }
int MxAnywhere3sDescriptor::easySwitchSlots() const { return 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

Guideline	Recommendation
📐 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:

Index	Meaning
`-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

Important

Every new device should have at minimum a unit test verifying the descriptor and, ideally, a hardware test if you have the physical device.

🔬 Unit Test

Create a test to verify the descriptor returns valid data:

// In tests/test_device_registry.cpp (or a new test file)
TEST(DeviceRegistryTest, MxAnywhere3sRegistered) {
 logitune::DeviceRegistry registry;
 auto *dev = registry.findByPid(0xb037);
 ASSERT_NE(dev, nullptr);
 EXPECT_EQ(dev->deviceName(), "MX Anywhere 3S");
 EXPECT_FALSE(dev->controls().isEmpty());
 EXPECT_GT(dev->maxDpi(), dev->minDpi());
 EXPECT_GT(dev->dpiStep(), 0);
 EXPECT_EQ(dev->easySwitchSlots(), 3);
}

🧩 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

Note

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

Warning

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()

Tip

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

Note

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`