DOCSEARCHbyAlgolia
Submit Docs

USBToolBox Documentation

repository·master·Indexed 21 days ago

https://github.com/usbtoolbox/tool

A tool for simplifying USB port mapping to generate custom injector kexts for macOS. It supports mapping from Windows and macOS, offering features such as automatic port type guessing and companion port binding on Windows. The tool allows users to build maps using either the USBToolBox kext or native Apple kexts (AppleUSBHostMergeProperties).

Tokens
889
Snippets
0
Records
6
Agent score
30%

What's inside USBToolBox

  1. Overview of USBToolBox

    master

    USBToolBox is a USB mapping tool designed to simplify the process of mapping USB ports for macOS. It supports building custom injector kexts from both Windows and macOS environments.

    Key features include:

    • Support for mapping from Windows and macOS.
    • Ability to build maps using either the USBToolBox kext or native Apple kexts (AppleUSBHostMergeProperties).
    • Multiple matching methods.
    • Companion port binding (Windows only).
    • Automatic port type guessing (Windows only).

  2. Map USB ports using USBToolBox

    master

    Follow these steps to create a USB map:

    1. Download and Setup: Download the appropriate version for your OS and adjust settings if necessary.
    2. Discover Ports: Select Discover Ports and wait for the list to populate.
    3. Physical Testing:
      • Plug a USB device into each port one by one. Wait for the device to appear in the listing before moving to the next port.
      • On Windows: You only need to plug one device into USB 3 ports (companion detection is automatic).
      • On macOS: You must plug in both a USB 2 device and a USB 3 device into each USB 3 port.
      • Legacy Controllers (OHCI/UHCI/EHCI): Plug in a mouse or keyboard to map USB 1.1 personalities.
    4. Configure Ports: Go to the Select Ports screen. Select your ports and adjust the port types as needed.
    5. Build Kext: Press K to build the kext.
    6. Installation:
      • Add the resulting USB map to your EFI/OC/Kexts folder.
      • Update your config.plist.
      • Important: If your map uses the USBToolBox kext, you must also download and add the latest release of the USBToolBox kext.
      • Important: Remove UTBDefault.kext if you have it installed.
    7. Reboot: Restart your system to apply the new USB map.

  3. Install and run USBToolBox on Windows

    master

    Windows 10 or 11 64-bit is recommended to access the full feature set, including companion port binding and port type guessing. Windows 8 may work, but Windows 7 and below are likely to crash. 32-bit versions are not supported.

    To install:

    1. Download the latest Windows.exe from the releases page.
    2. If antivirus software flags the download, you can whitelist it or use Windows.zip (which avoids the self-extractor that often triggers warnings).

    You can also run the tool from a Windows PE environment by opening a command prompt (cmd) via Shift + F10.

  4. Install and run USBToolBox on macOS

    master

    Using USBToolBox on macOS is not recommended because it lacks features like port type guessing and companion port binding. Additionally, macOS 11.3 has a broken XhciPortLimit. If you are on macOS, it is suggested to use USBMap instead.

    If you must use USBToolBox on macOS:

    1. Download macOS.zip from the releases page.

  5. Troubleshoot missing USB information

    master
    If USBToolBox reports ports as 'unknown' or shows missing information, ensure that you have the correct drivers installed for all your devices on Windows. Missing drivers prevent the tool from retrieving necessary device details.

  6. Identify USB connector types by ID

    master

    USBToolBox uses numeric IDs to represent different physical USB connector types. When analyzing hardware or interpreting tool output, use the following mapping to identify the connector type:

    IDConnector Type
    0USB Type A (Standard USB 2.0)
    1USB Type Mini-AB
    2ExpressCard (USB side)
    3USB 3 Type A
    4USB 3 Type B
    5USB 3 Type Micro-B
    6USB 3 Type Micro-AB
    7USB 3 Type Power-B
    8USB Type C - USB 2 only
    9USB Type C - with switch
    10USB Type C - without switch
    255Internal (Card readers, fingerprint scanners, webcams, etc.)