Skip to content

Latest commit

 

History

History
300 lines (210 loc) · 8.9 KB

autoport.md

File metadata and controls

300 lines (210 loc) · 8.9 KB
Raw

autoport

autoport is an automatic controller (joystick and mouse) selection tool for emulators. It will prioritize which controllers are used as Player 1, Player 2, etc. based on predefined configuration settings.

The benefit of autoport is that you don't need to care which order your joystick or mouse was plugged in to. You can guarantee that certain controllers are always chosen for Player 1, Player 2, etc.

Features

autoport is inspired by RetroPie-joystick-selection but introduces a more sophisticated controller selection system as well as support for additional emulators.

autoport currently supports the following emulators:

  • libretro cores
  • dosbox-staging
  • drastic
  • hpyseus
  • mupen64plus
  • ppsspp
  • redream
  • supermodel3

This means that autoport will adjust the input configuration for every one of these emulators based on a single configuration file.

The following high-level features are supported by autoport:

  • Joystick and mouse selection
  • Filter by name, vendor_id, product_id, usb path, device_id, running system processes, etc.
  • Set the device type automatically in libretro cores and redream
  • Detailed control over how many devices get configured and which player they're associated with
  • Profile-based configurations so you can use different autoport configurations based on the game being played
  • Global, system, emulator, and game-specific overrides

Install

To install autoport via retrokit (which will install all dependencies and configurations):

# Support multiple integrated autostart.sh scripts
bin/setup.sh install retropie-autostart

# Install autoport
bin/setup.sh install autoport

Usage

Normally you won't need to directly interface with the autoport CLI, but if you're integrating it manually, then the CLI can be used like so:

# Reconfigure inputs for the given system/emulator
autoport/autoport.sh setup <system> <emulator> <path-to-rom>

# Restore input configuration for the given system/emulator
autoport/autoport.sh restore <system> <emulator> <path-to-rom>

Configuration files

Autoport uses pre-configured profiles to determine the priority order of joystick and mouse devices when starting up a game. You will find these configurations located here:

Scope retrokit path RetroPie path
Global config/autoport/autoport.cfg /opt/retropie/config/systems/all/autoport.cfg
System config/systems/{system}/autoport.cfg /opt/retropie/config/systems/{system}/autoport.cfg
Emulator config/systems/{system}/autoport/emulators/{emulator}.cfg /opt/retropie/config/systems/{system}/autoport/emulators/{emlator}.cfg
Game config/systems/{system}/autoport/{name or title}.cfg /opt/retropie/config/systems/{system}/autoport/{name}.cfg

It will prioritize each of the above configurations like so (highest to lowest):

  • Game
  • Emulator
  • System
  • Global

Configuration

At its most basic, autoport configurations are structured like so:

[base]

# mouse1...
# mouse2...
# mouse...

# joystick1...
# joystick2...
# joystick...

[autoport]

profile = base
enabled = true

As you might imagine, this can get a lot more advanced. For each input (whether that's a mouse or a joystick), you can configure the following filters:

  • name: The name of the device
  • vendor_id: The Vendor ID of the device
  • product_id: The Product ID of the device
  • usb_path: A full or partial filesystem path for the device
  • related_usb_path: A full or partial filesystem path for another input connected to the same usb port
  • device_id: The unique identifier for the device (e.g. the bluetooth mac address)
  • running_process: A system process that must be running for the input to be considered connected

Each of these filters supports regular expression matching and ignores case.

Example configuration:

joystick1_vendor_id = "1234"
joystick1_product_id = "5678"

Additionally, each input can define how it gets set up in the emulator:

  • set_device_type: The type of device to configure in the emulator (libretro cores and redream)
  • limit: The maximum number of devices to select from this device type

Example configuration:

joystick1_limit = 2
joystick1_set_device_type = 123

Finally, you can control how joysticks and mice get set up overall with the following configurations:

  • start: The player id to start configuring from
  • limit: The total number of devices to assign to players
  • skip: Specific player ids to skip when assigning devices
  • order: The explicit order in which to assign inputs to players
  • set_device_type: The type of device to configure in the emulator (libretro cores and redream)
  • set_device_type_p2: The type of device to configure for a specific player number

Example configuration:

joystick_start = 2
joystick_limit = 1

To see a full example configuration, review autoport.cfg.

Profiles

autoport supports the concept of profiles. A profile is a group of configurations intended for a certain category of games. The default "base" profile is used when a specific profile isn't referenced. Below is an example of an autoport configuration that defines multiple profiles:

[base]

[lightgun]

# Assume by default we're not working with more than 2 lightguns
mouse_limit = 2
joystick_profile = base

[trackball]

# Assume by default we're not working with more than 2 trackballs
mouse_limit = 2
joystick_profile = base

# Example:

# mouse1 = "Kensington ORBIT WIRELESS TB Mouse"

[keyboard]

keyboard_limit = 1
joystick_profile = base
mouse_profile = base

[dial]

joystick_profile = base
mouse_profile = base

[pedal]

joystick_profile = base
mouse_profile = base

[paddle]

joystick_profile = base
mouse_profile = base

[autoport]

profile = base
enabled = true

The biggest benefit of profiles is that you can define a single configuration across all of your systems and reference different profiles based on the type of game you're playing.

Additionally, when paired with retrokit, autoport profiles will be automatically selected based on metadata known about what inputs are used by certain games. This can make setting up inputs, such as lightguns, very easy to do.

Examples

Below are some example use cases you could run into.

Sinden lightguns

To set up Sinden lightguns to be set up as a mouse for Player 1 / Player 2, you can define an autoport profile like so:

[lightgun]

mouse1 = "Unknown SindenLightgun Mouse"
mouse1_related_usb_path = "ttyACM0"
mouse1_running_process = "LightgunMono.exe"

mouse2 = "Unknown SindenLightgun Mouse"
mouse2_related_usb_path = "ttyACM1"
mouse2_running_process = "LightgunMono2.exe"

This configuration will ensure that the Sinden Lightgun software is running and connected before using it as an input.

GPi Case

Support you have a GPi case and you want to prioritize wireless controllers over the built-in gamepad. You can do that like so:

[base]

joystick1 = "8Bitdo SN30 Pro"
joystick1_device_id = "e4:17:d8:f8:f0:75"
joystick2 = "8Bitdo SN30 Pro"
joystick2_device_id = "e4:17:d8:96:f0:75"
joystick3 = "8Bitdo SN30 Pro"
joystick4 = "Microsoft X-Box 360 pad"
joystick4_usb_path = "usb"
joystick5 = "Microsoft X-Box 360 pad"
joystick5_usb_path = "serial"

This prioritizes, in oder:

  • Specific bluetooth controllers
  • Wired usb controllers
  • The built-in controller (serial connection)

Different profiles

Below is my autoport.cfg that defines different profiles based on the type of inputs the game supports:

[base]

mouse1 = "Telink Wireless Receiver Mouse"
mouse2 = "Kensington ORBIT WIRELESS TB Mouse"

joystick1 = "8BitDo Ultimate Wireless / Pro 2 Wired Controller"
joystick2 = "8Bitdo SN30 Pro"
joystick3 = "Microsoft X-Box 360 pad"

[arcade]

joystick1 = "8BitDo Arcade Stick"
joystick2 = "8BitDo Ultimate Wireless / Pro 2 Wired Controller"
joystick3 = "Microsoft X-Box 360 pad"

[trackball]

mouse1 = "Kensington ORBIT WIRELESS TB Mouse"

How it works

During the runcommand onlaunch hook, autoport will read from all of the various configurations defined on the system to determine which profile is active. Based on that profile, it will attempt to match as many inputs of a particular name before it moves onto the next input name. If an input can't be found, then it will move onto the next input.

After the game is terminated, the onend hook will be executed, causing autoport to revert any changes it may have needed to make to the emulator's configuration files. If there is a system crash or this hook is never executed, it will still revert those changes the next time a game is launched.