Master USB HID device control on macOS with IOKit in Swift

Developing native macOS applications that interact with USB Human Interface Devices (HIDs) at a low level requires understanding how the operating system handles hardware communication. While most developers rely on macOS’s built-in input event system, some devices—particularly gaming peripherals like Razer mice—offer advanced configuration options through raw feature reports. These are direct byte streams sent outside standard input events, enabling custom control over device behavior. However, working with these reports on macOS demands a precise approach using the IOKit framework.

Why IOKit is Essential for USB HID Development

The IOKit framework provides the necessary APIs to communicate directly with USB HIDs on macOS without requiring kernel extensions. While many applications abstract this interaction, developers who need to send custom configuration commands must bypass these abstractions. Feature reports allow sending raw byte arrays to devices, enabling functionality like adjusting DPI settings or RGB lighting—capabilities traditionally controlled by manufacturer software like Razer Synapse.

For macOS, the primary API for this is IOHIDManager, part of the IOKit framework. This approach eliminates the need for sandboxing workarounds or complex entitlements, though developers must temporarily disable the App Sandbox during development to test feature reports effectively.

Setting Up Your Development Environment

To begin working with IOKit in Swift, create a Command Line Tool project in Xcode targeting macOS. The setup process involves two critical configuration steps:

• Link the IOKit.framework under the project’s General → Frameworks and Libraries section
• Ensure the App Sandbox is disabled in your target’s Signing & Capabilities tab

import IOKit
import IOKit.hid
import Foundation

Without these configurations, feature report commands will fail silently, making debugging particularly challenging.

Identifying Your Target Device

The IOHIDManager API requires a matching dictionary to locate specific USB HID devices. At minimum, this dictionary should include the vendor and product IDs, which uniquely identify hardware devices. The process begins with creating an IOHID manager instance and configuring it to search for your device:

let manager = IOHIDManagerCreate(kCFAllocatorDefault, IOOptionBits(kIOHIDOptionsTypeNone))
IOHIDManagerSetDeviceMatching(manager, [
    kIOHIDVendorIDKey: 0x1532,
    kIOHIDProductIDKey: 0x0084
] as CFDictionary)

Opening the manager and retrieving devices follows a similar pattern:

guard IOHIDManagerOpen(manager, IOOptionBits(kIOHIDOptionsTypeNone)) == kIOReturnSuccess else {
    print("Failed to open manager")
    exit(1)
}

guard let devices = IOHIDManagerCopyDevices(manager) as? Set<IOHIDDevice>, !devices.isEmpty else {
    print("Device not found")
    exit(1)
}

If you’re unsure about a device’s product ID, you can filter by vendor ID alone and inspect all connected devices:

IOHIDManagerSetDeviceMatching(manager, [kIOHIDVendorIDKey: 0x1532] as CFDictionary)
// ... open manager ...
for device in devices {
    let name = IOHIDDeviceGetProperty(device, kIOHIDProductKey as CFString) as? String ?? "?"
    let pid = IOHIDDeviceGetProperty(device, kIOHIDProductIDKey as CFString) as? Int ?? 0
    print("Device: \(name) (PID: 0x\(String(pid, radix: 16)))")
}

Navigating Multiple HID Interfaces

A single physical USB device often registers multiple HID interfaces, each serving different purposes. For example, a Razer DeathAdder V2 typically appears as four distinct interfaces with varying usage pages and feature report sizes. The correct interface for sending configuration commands is determined by its maxFeatureReport value, which matches Razer’s 90-byte packet format.

To identify the right interface, examine each device’s properties:

for device in devices {
    let usagePage = IOHIDDeviceGetProperty(device, kIOHIDPrimaryUsagePageKey as CFString) as? Int ?? 0
    let usage = IOHIDDeviceGetProperty(device, kIOHIDPrimaryUsageKey as CFString) as? Int ?? 0
    let maxFeature = IOHIDDeviceGetProperty(device, kIOHIDMaxFeatureReportSizeKey as CFString) as? Int ?? 0
    print("Interface: page=0x\(String(usagePage, radix: 16)) | usage=0x\(String(usage, radix: 16)) | maxFeature=\(maxFeature)")
}

Once identified, filter for the interface with maxFeatureReport set to 90:

guard let targetDevice = devices.first(where: { device in
    (IOHIDDeviceGetProperty(device, kIOHIDMaxFeatureReportSizeKey as CFString) as? Int ?? 0) == 90
}) else {
    print("Control interface not found")
    exit(1)
}

This filtering strategy works for most HID devices, where the feature report size often serves as the clearest indicator of the correct interface.

Sending and Receiving Feature Reports

After selecting the appropriate interface, opening the device and sending a feature report follows a straightforward process. However, two critical details often cause implementation challenges:

1. Buffer size precision: The IOHIDDeviceSetReport function expects the report ID as a separate parameter, not embedded in the data buffer. For a device with a 90-byte feature report, your buffer must contain exactly 90 bytes. Adding an extra byte will trigger error code -536850432 (0xE0005000) without clear explanation.

1. Response timing: The device requires a brief delay between sending a command and reading the response. A 200–300 millisecond sleep typically ensures reliable communication:

guard IOHIDDeviceOpen(targetDevice, IOOptionBits(kIOHIDOptionsTypeNone)) == kIOReturnSuccess else {
    print("Could not open device")
    exit(1)
}

var report = UInt8
// Populate report bytes with your configuration command

let result = IOHIDDeviceSetReport(
    targetDevice,
    kIOHIDReportTypeFeature,
    0,
    &report,
    report.count
)

Thread.sleep(forTimeInterval: 0.3)

var response = UInt8
var responseLen = CFIndex(90)
IOHIDDeviceGetReport(
    targetDevice,
    kIOHIDReportTypeFeature,
    0,
    &response,
    &responseLen
)

Use a fresh buffer for the response to accurately detect whether the device processed your command.

Decoding Device Responses

Razer devices, in particular, use byte [0] of the response to indicate command status:

• 0x00: No response or stale data
• 0x01: Device busy
• 0x02: Command accepted
• 0x05: Command not understood

A response of 0x02 confirms the full communication stack is functioning correctly. If you receive all zeros, investigate potential causes: timing issues, incorrect interface selection, or buffer size mismatches.

The final step involves understanding the specific packet format for Razer devices, including CRC computation and transaction ID management. Future implementations should account for these elements to ensure robust communication with different device families.

With precise buffer handling and timing control, developers can unlock advanced device customization on macOS without relying on proprietary manufacturer software.