Home

Awesome

USBMap

macOS has a limit on the number of USB ports it can recognize, which might cause some ports to function at lower speeds or not at all. USBMap is a python script which helps to create a custom kext to ensure all ports work correctly by mapping them within macOS's limits.

Features

Installation

With Git

To install using the latest version from Github, run the following commands one at a time in Terminal.app:

git clone https://github.com/corpnewt/USBMap
cd USBMap
chmod +x USBMap.command

Then run with either ./USBMap.command or by double-clicking USBMap.command

Without Git

You can get the latest zip of this repo here. Then run by double-clicking USBMap.command

Quick Start

Why

macOS supports up to 15 USB ports per controller. On a native Mac, these are directly mapped to the physical ports. However, other motherboards may have more ports than are actually in use, leading macOS to default to using the first 15 ports it detects. This often results in physical ports only achieving USB 2 speeds because USB 3 ports are numbered above 15. USBMap allows you to create a kext customized for your system, ensuring that non-existent ports are ignored and all physical ports are accounted for within the 15-port limit.

Before You Begin

General Mapping Process

  1. Make sure you've run D. Discover Ports at least once from USBMap's main menu so it knows what USB controllers you have

  2. Choose K. Create USBMapDummy.kext via USBMap's main menu

  3. Add the USBMapDummy.kext dummy injector to your EFI/OC/Kexts folder and config.plist -> Kernel -> Add

  4. Reboot your machine to apply the dummy map, providing a foundation for mapping.

  5. Go into USBMap's D. Discover Ports and plug both a USB 2 and a USB 3 device into every port - letting the script refresh between each plug. You can assign nicknames to ports for easier identification using the 'N' key.

    ◦ It is normal that not all port personalities will have devices populate under them at this step as macOS can only see the first 15 per controller here!

    ◦ You can verify the dummy map is applied if all ports use a UKxx naming scheme (eg. UK01, UK02, etc)

  6. The USBMap script will save the discovered port information in a file, so you can quit it for now.

  7. Open the USBMapInjectorEdit.command and drag the USBMapDummy.kext from your EFI into the Terminal window. Then toggle off all port personalities that you didn't encounter when using "Discover ports".

    ◦ Disable any of the first 15 port personalities that are not used for a keyboard or mouse - EVERYTHING ELSE in the first 15 can be disabled

    ◦ Disabling these is ONLY TEMPORARY and done for the sake of mapping - you can still choose which to include in the final map

    ◦ <ins>DO NOT</ins> disable port personalities 16 through 26, these need to stay enabled to continue mapping

    ◦ You will need to go through each IOKitPersonality that USBMapInjectorEdit.command lists for this

  8. Reboot your machine to apply the updated dummy map

  9. Go into USBMap's D. Discover Ports and plug a USB 2 and USB 3 device into every port - letting the script refresh between each plug

    ◦ As some port personalities were disabled in step 7, it is normal that not plugged in USB devices will populate under a port personality at this step!

  10. Go into the P. Edit & Create USBMap.kext menu and change the types to match the physical port types (i.e. for standard USB 2 port use "0" and for USB 3 Type-A port use "3". You can find all codes by pressing T) and enable which port personalities (up to 15) you want to keep

  11. Build the final USBMap.kext and replace the dummy injector in your EFI/OC/Kexts folder and config.plist -> Kernel -> Add

The dummy injector + USBMapInjectorEdit steps are to allow you to map using a "sliding window" of sorts. Since macOS can only see 15 port personalities per controller at one time, you need to map what's visible, then disable some to make room for the next sweep - and map again

FAQ