USB and HID Devices on macOS: When You Need a Driver and When You Do Not
Before writing a DriverKit extension for a USB device, it is worth asking whether macOS needs one. macOS includes drivers for the standard USB classes, and applications can open vendor-specific devices directly through Apple frameworks or libraries such as libusb. A driver is only necessary when the device must appear to the whole system as something macOS does not already support.
At a glance
- HID
- Handled by the built-in HID driver and readable from apps.
- CDC ACM
- USB serial devices using this class appear as serial ports without a custom driver.
- UAC 2
- USB Audio Class 2 devices work with the built-in audio support.
- libusb
- A portable user-space library for vendor-specific USB devices.
The problem
A common pattern is a custom USB protocol designed early in a project, followed by the discovery that every operating system now needs its own driver. Each brings signing, installation and maintenance, for a device that could have used a standard class.
The reverse also happens: an app tries to open a device that a built-in driver has already claimed, such as a keyboard-class HID device or a mass storage interface, and finds it cannot get exclusive access or is blocked by privacy controls.
The cheapest macOS driver is the one you never write.
Choosing the path
If the device fits a standard class, such as HID, CDC ACM serial, audio, video, mass storage, MIDI or CDC networking, implement that class in the firmware and test it with the built-in drivers. For custom HID devices, a vendor-defined usage page lets an app exchange reports through Apple HID APIs with no driver. Reading keyboard input requires the user to grant the app Input Monitoring permission.
For a vendor-specific interface used by one application, open it from the app with the IOUSBHost framework or libusb; sandboxed apps also need the USB device entitlement. Write a DriverKit extension only when the device must act as a system-wide resource with no class driver, such as a non-standard serial bridge, a network interface or an audio device that is not class compliant, where an audio server plug-in may also be an option.
What good looks like
Decide the USB class at the firmware design stage, with every target operating system in mind, not only macOS.
Prototype host access from a simple app and check permissions and entitlements on a release build.
Only if that cannot meet the requirement, scope a DriverKit extension and start the entitlement request.
| Class | Appears as | Driver needed |
|---|---|---|
| HID | Input device, or reports to apps | No |
| CDC ACM | Serial port device node | No |
| Audio Class 1 and 2 | Core Audio device | No |
| Video Class (UVC) | Camera | No |
| Mass storage | Disk | No |
| Vendor-specific | Nothing until an app opens it | Only for system-wide use |
Deciding whether a macOS driver is needed
- Standard class: Use the built-in driver
- One app uses it: IOUSBHost or libusb from the app
- System-wide service: Check for a DriverKit family
- Family exists: Write a dext and request entitlements
What it changes
No Driver to Ship
Class-compliant devices work as soon as they are plugged in.
Cross-Platform
Common classes work with built-in drivers on macOS, Windows and Linux.
Simpler Releases
App-level access avoids extension approval and entitlement delays.
Lower Maintenance
There is no driver to update for each new macOS release.
Where to go next
Give each unit a unique serial number string so apps can tell several connected units apart.
If a browser-based tool is planned, note that WebUSB and WebHID are supported only in some browsers, and not in Safari.
Problems this prevents
- A custom protocol that needs a driver on every OS
- Apps blocked from devices a system driver has claimed
- Release builds failing on missing entitlements
- A dext written for a class macOS already supports
Discuss your project
Email support@aavico.com or use Get in Touch when the website finishes loading.