Skip to content

xaqfan/Karabiner-DriverKit-VirtualHIDDevice

 
 

Repository files navigation

Build Status License

Karabiner-DriverKit-VirtualHIDDevice

Virtual devices (keyboard and mouse) implementation for macOS using DriverKit.

Supported systems

  • macOS Big Sur (11.0)
    • Both Intel-based Macs and Apple Silicon Macs
  • macOS Catalina (10.15)
    • Intel-based Macs

Status

  • Implemented:
    • Extension manager
    • Virtual HID keyboard
    • Virtual HID pointing
    • Virtual HID device client

Documents

Screenshots

  • System Preferences (macOS detects the virtual keyboard)

    System Preferences


Usage

  1. Open dist/Karabiner-DriverKit-VirtualHIDDevice-x.x.x.dmg, and then open Karabiner-DriverKit-VirtualHIDDevice.pkg (installer).

  2. Install files via installer.

  3. Execute the following command in Terminal.

    /Applications/.Karabiner-VirtualHIDDevice-Manager.app/Contents/MacOS/Karabiner-VirtualHIDDevice-Manager activate
  4. Run a client program to test the driver extension.

    git clone --depth 1 https://github.com/pqrs-org/Karabiner-DriverKit-VirtualHIDDevice.git
    cd Karabiner-DriverKit-VirtualHIDDevice/client/examples/virtual-hid-device-service-client
    make
    sudo ./build/Release/virtual-hid-device-service-client

Uninstallation

  1. Run uninstaller in Terminal.

    bash '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/scripts/uninstall/deactivate_driver.sh'
    sudo bash '/Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/scripts/uninstall/remove_files.sh'

Installed files

  • /Applications/.Karabiner-VirtualHIDDevice-Manager.app
  • /Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice
  • /Library/LaunchDaemons/org.pqrs.Karabiner-DriverKit-VirtualHIDDeviceClient.plist
  • /Library/Application Support/org.pqrs/tmp
  • /var/log/karabiner

For developers

How to build

System requirements to build Karabiner-Elements:

  • macOS 10.15+
  • Xcode 12+
  • Command Line Tools for Xcode
  • XcodeGen

Note

A provisioning profile which supports com.apple.developer.driverkit is required to build a driver extension since Xcode 12.

If you want to start without a valid provisioning profile, use Xcode 11 and Karabiner-DriverKit-VirtualHIDDevice v0.11.0.

Steps

  1. Gain the DriverKit entitlements to be able to create a provisioning profile which supports com.apple.developer.driverkit. Specifically, follow the instructions on Requesting Entitlements for DriverKit Development

    Note: This process may take some time to complete on Apple's end.

    If you want to start without the request, use Xcode 11 and Karabiner-DriverKit-VirtualHIDDevice v0.11.0. (See above note)

  2. Create a Developer ID distribution provisioning profile for org.pqrs.Karabiner-DriverKit-VirtualHIDDevice with com.apple.developer.driverkit entitlement.

    Generate a Provisioning Profile
  3. Replace CODE_SIGN_IDENTITY at src/scripts/codesign.sh with yours.

    Find your codesign identity by executing the following command in Terminal.

    security find-identity -p codesigning -v

    The result is as follows.

    1) 8D660191481C98F5C56630847A6C39D95C166F22 "Developer ID Application: Fumihiko Takayama (G43BCU2T37)"
    2) 6B9AF0D3B3147A69C5E713773ADD9707CB3480D9 "Apple Development: Fumihiko Takayama (YVB3SM6ECS)"
    3) 637B86ED1C06AE99854E9F5A5DCE02DA58F2BBF4 "Mac Developer: Fumihiko Takayama (YVB3SM6ECS)"
    4) 987BC26C6474DF0C0AF8BEA797354873EC83DC96 "Apple Distribution: Fumihiko Takayama (G43BCU2T37)"
        4 valid identities found
    

    Choose one of them (e.g., 8D660191481C98F5C56630847A6C39D95C166F22) and replace existing CODE_SIGN_IDENTITY with yours as follows.

    # Replace with your identity
    readonly CODE_SIGN_IDENTITY=8D660191481C98F5C56630847A6C39D95C166F22
  4. Replace team identifier, domain and embedded.provisionprofile.

    • Search G43BCU2T37 and replace them with your team identifier.

      git grep G43BCU2T37 src/
    • Search org.pqrs and org_pqrs, then replace them with your domain.

      git grep org.pqrs src/
      git grep org_pqrs src/
    • Replace embedded.provisionprofile file with yours.

      find * -name 'embedded.provisionprofile'
  5. Build by the following command in terminal.

    make package

    dist/Karabiner-DriverKit-VirtualHIDDevice-X.X.X.pkg will be generated.

Components

Karabiner-DriverKit-VirtualHIDDevice consists the following components.

  • Extension Manager (including DriverKit driver)
    • /Applications/.Karabiner-VirtualHIDDevice-Manager.app
    • It provides a command line interface to activate or deactivate DriverKit driver.
  • VirtualHIDDeviceClient
    • /Library/Application Support/org.pqrs/Karabiner-DriverKit-VirtualHIDDevice/Applications/Karabiner-DriverKit-VirtualHIDDeviceClient.app
    • It mediates between the client app and the driver.
    • It allows apps to communicate with the virtual device even if the app is not signed with pqrs.org's code signing identity. (The client app must be running with root privileges.)
  • Client apps
    • Client apps are not included in the distributed package.
    • For example, you can build the client app from client/examples/virtual-hid-device-service-client in this repository.
    • Client apps can send input events by communicating with VirtualHIDDeviceClient via UNIX domain socket. (/Library/Application Support/org.pqrs/tmp/rootonly/virtual_hid_device_service_server.sock)

components.svg

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • C++ 84.4%
  • Shell 6.8%
  • Swift 3.6%
  • Makefile 2.9%
  • Python 1.9%
  • CMake 0.4%