Linux Unix Guide

Introduction

Operating systems based on UNIX, Linux, or that otherwise implement or emulate the general UNIX architecture and programming interfaces will be referred to as Unix-like systems for this article.

In addition to systems clearly branded as Linux or UNIX, this includes SteamOS (based on Arch Linux), Raspberry Pi OS (based on Debian Linux), ChromeOS (also based on Debian), Batocera (a Linux distribution customized for retro gaming), and most of the other non-Android setups that you might find on all-in-one arcade machines and indie consoles. Technically, the term could also include macOS and iOS, which have a core based on BSD UNIX that could probably run much of the software listed below, but Apple's customizations and lockdowns are so extensive that the Sinden driver is not yet supported on those platforms. Similarly, the system software (Orbis) for the Playstation 3, 4, and 5 is also based on BSD UNIX, but Sony's lockdowns would prevent you from natively running any of the software below without modifications to the Playstation firmware. Finally, although Android uses the Linux kernel, its programming interfaces and user interface philosophy are so different from UNIX that this guide does not apply to Android systems.

Note that there is already a separate wiki page for setting up a Raspberry Pi with a prebuilt Sinden-compatible image; however, if you want to run an alternative OS build, you may find the directions below helpful.

Supported Operating Systems

While the Sinden Software should run on most Unix-like systems, check the latest Supported OS List for setups verified by other users. Please submit feedback to this wiki or in the Discord channel if you are able (or unable) to get your Sinden Lightguns working on another system not already listed.

Supported Hardware

The Sinden driver for Unix-like systems is primarily packaged as a Microsoft .NET portable executable (LightgunMono.exe) that can theoretically run on almost any processor and operating system combination. However, as of this writing the .exe depends on two shared libraries (libCameraInterface.so and libSdlInterface.so) that are distributed only in 64-bit x86 and 64-bit ARM versions. As a result, there is currently no direct support for other CPUs, including 32-bit x86 or ARM. On other platforms, you might be able to use an emulator such as VirtualBox or QEMU to run the driver if you configure direct pass-through of the USB lightgun to the virtual guest OS.

Setting up Sinden support on a Unix-like system

There are six basic steps to getting your Sinden Lightgun working:

1. Installing a .NET runtime environment that can run the Sinden driver
2. Installing the software libraries the Sinden driver uses for camera support
3. Setting up that Sinden driver so that the lightgun appears as a mouse or joystick
4. Calibrating your lightguns
5. Setting up a screen border
6. Ensuring your games are launched with the right options to preserve or interact with #3 and #5 above

.NET Runtime Environment

In order to run LightgunMono.exe, you will need a .NET interpreter, which for non-Windows systems will almost always be the free and open-source Mono You will also need a copy of Microsoft's .NET runtime, which is also freely available. On most Linux distributions, these packages are available in the standard package repositories as mono and dotnet-runtime or very similar names. For example, on Arch Linux (including SteamOS) you can install these prerequisites with the command sudo pacman -S mono dotnet-runtime; on Debian-based distributions (including Ubuntu and Raspberry Pi OS) you would use sudo apt install mono dotnet-runtime-9.0. Directions for other Unix-like systems will vary.

Some older documentation states that the driver requires versions 6 and 8 of the .NET runtime to be installed, but newer versions of the runtime can usually run software compiled for older versions without significant problems. On my systems, the Sinden driver runs just fine with only the newest version of the .NET runtime (9.0) installed. If you are having problems with Mono or the .NET environment, you can try installing the dotnet-runtime-8 and/or dotnet-runtime-6 packages (on Debian/Ubuntu, dotnet-runtime-6.0 and dotnet-runtime-8.0), but that is probably unnecessary for most users.

Once you have any version of the .NET runtime or SDK installed, you can use dotnet --list-runtimes to see all installed runtimes on your system.

Other software libraries

libCameraInterface.so and libSdlInterface.so depend on the Video4Linux, libJPEG, SDL 1.2, and SDL_image 1.2 libraries, which must be installed on your system. These may all be pre-installed on many systems, but on Arch Linux that can be guaranteed with sudo pacman -S v4l-util libjpeg-turbo sdl12-compat sdl_image. On Debian-based distributions (including Ubuntu and Raspberry Pi OS) you would use either sudo apt install v4l-utils libjpeg libsdl1.2 libsdl-image1.2 or else sudo apt install v4l-utils libjpeg libsdl2 libsdl2-image (if you prefer to use the SDL-2.0-to-1.2 compatibility layer, which could be more stable than SDL 1.2 on some systems but less stable on others).

The Sinden driver bundle includes a script named setup-lightgun.sh in each Raspberry Pi directory which simply contains versions of the apt commands above. The script installs the -dev versions of some packages, which is not strictly necessary for running the driver. Note also that the script for the Pi 5 uses the libsdl2 packages, while the script for older Pis uses libsdl12.

Installing and running the Sinden Driver

The driver for Unix-like systems is included within the standard Sinden software bundles. The directory layout changes significantly between driver releases, but the driver itself is always named LightgunMono.exe. As of this writing, the latest release of the main Unix-like driver was from version 2.05 of the Sinden software bundle. Versions 2.07b and 2.07 include an adjusted version of the driver with support for the Sinden Pedal. The 2.07b bundle also includes a subfolder with the older 2.05 pedal-free driver, but the main 2.07 release does not. If you don't have pedals and experience problems with the "Pedal" driver (especially with button events), try downloading the 2.05 or 2.07b zipfile and running the 2.05 driver.

To run the driver, open a terminal window, navigate to the directory containing LightgunMono.exe, and run the command mono LightgunMono.exe. If you don't want to change directories, mono /path/to/LightgunMono.exe will also work just fine; the Mono engine will automatically find libCameraInterface.so and libSdlInterface.soas long as they're still in the same directory as LightgunMono.exe.

On my system, I find that "mouse mode" (the default) is more stable than "joystick mode" for most games. If you want or need to run in joystick mode, run mono LightgunMono.exe joystick to have the lightgun appear as a joystick instead of a mouse.

Note that the driver will exit immediately if it does not detect any Sinden devices connected. You can use lsusb -v to see all USB devices currently recognized by your system.

You will need to keep the mono LightgunMono.exe process running in the background while playing your lightgun games; the moment you terminate it (e.g. with ^C in the shell window) your emulated mouse or joystick will go away. You can launch the command in the background with mono LightgunMono.exe & and terminate it later with the kill command if desired.

Calibration

The Sinden calibration utility is built into LightgunMono.exe; kill any existing mono LightgunMono.exe process and run mono LightgunMono.exe sdl to enter calibration mode. The calibration utility will draw its own rectangular border to support lightgun tracking. After completing calibration, the utility will exit and you'll need to re-run mono LightgunMono.exe or LightgunMono.exe joystick to restart the driver.

The Sinden driver for Unix-like systems does not yet include all of the hardware configuration features of the Windows version; for tasks like firmware upgrades you will need to run the Windows utility. If you don't have a dedicated Windows system available, you can run the Windows utility in an emulator such as VirtualBox if you pass the associated USB devices directly through to the guest OS.

Border Overlays

The "UNIX philosophy" of separating functionality into different processes and layers and letting users mix-and-match their preferred software packages means that there are many possible combinations of desktop environments on Unix-like systems. As as result, there's no one-size-fits all solution to draw a border that's always on the screen, as there is in the Windows version of the Sinden driver. The options below should be adequate for most users, and serve as a starting point for more exotic environments. Of note, all of the options below should work equally well whether your desktop uses the older X11 or newer Wayland protocol.

Bezels within a retro game emulator

RetroArch, EmulationStation, and many other emulation front-ends can apply custom bezels around the emulated game window. You can find a list of available bezel packs here and instructions for individual emulators here.

If you're using RetroPie, the Pi directories within the Sinden software bundle contain a setup-retropie.shscript that will copy border scripts to appropriate folders for a default installation. The path names may require adjustment for your particular setup. Note that the script will make a number of files within /home/pi/RetroPie/roms/ports/ world-readable and writable, which you might not want. Users are always advised to carefully review .sh scripts before running them.

GNOME Desktops

If your game isn't running within an emulator¸ or only runs in an emulator that lacks bezel support, or you simply want to use your Sinden Lightguns to navigate around your desktop (e.g. to select other games), you'll need a different solution to draw a border around your screen. Discord user aaronbpaden created the Gnome Shell Extension White Border Overlay that serves this purpose. Note that it may not work with some full-screen games depending on the method they use to request the fullscreen drawing surface.

KDE

An equivalent utility for KDE (or any other QML-compliant desktop manager) with user-customizable border thickness and color is available here. To set it up, first install the QtLayerShell library, then run kqml screen-borders.qml to activate the border. The border will disappear as soon as the kqml process is killed. Like the GNOME extension above, this KDE utility provides screen layout hints that should be respected by most applications in "fullscreen" mode, but some game engines using direct screen access may draw over the border, requiring a different solution such as the Vulkan module below.

Vulkan games (and DirectX or OpenGL layered over Vulkan)

For 3D games that take over the entire screen, one solution is to use Vulkan's plug-in mechanism to draw a solid border on top of every frame. This will cover the edges of your game screen since the game doesn't know anything about the border overlay, but for most games that's a negligible issue. Even though this depends on Vulkan, it can be used automatically within DirectX and OpenGL games: WINE and Proton normally translate DirectX API calls to Vulkan primitives, and Mesa (the main open-source OpenGL driver) offers an OpenGL-to-Vulkan translation driver called Zink. Full directions for the Vulkan border overlay plugin are here. Note that specific environment variables (or Steam game launch options) must be set for the driver to load in each individual game; see the directions in the README.