New ViGEm Installer

Merry Christmas y’all! 😃

I have a small yet powerful Christmas present for my trusty users. As you might have noticed, the installation of the ViGEm Bus was a bit rough on both the documentation and the procedure itself. I’ve experimented a lot with conventional and unconventional methods, even with my beloved Advanced Installer. But in the end, driver installation isn’t really a common task in most setup maker utilities so I decided to roll my own. As much as I enjoy .NET I’ve always neglected using the  Windows PowerShell for more than a view lines of scripting automation. This changed a lot over the last couple month since I was successfully implementing more and more complex tasks in PowerShell at my job. Therefore I also stumbled upon the neat possibility of developing PowerShell binary modules. In short, these are pieces of code collections written in C# and compiled to a DLL while exposing Cmdlets like you’d do in scripts. This grants me the power I was looking for:

  • Hide/abstract device creation and driver installation from the end user
  • Stick to C# rather than maintaining lots of additional PowerShell scripts
  • Utilize existing and supported distribution mechanisms
  • No GUI development required (I hate that and it slows me down)
  • Profit from built-in PowerShell advantages like passing objects
  • Built into Windows 10 and – provided via Updates – Windows 7 and newer
  • Simple update management

Now I know that not everyone – especially Gamer who just like their stuff to work – enjoys fiddling around with command line interfaces but when my past projects told me one thing, it’s that you can’t satisfy everyone a 100% so I’ll stick to satisfying myself first 😛 Well, that came out weirder than I intended… Anyways, enough babbling, let me show you how it’s done! 😎

How to install ViGEm Bus & Driver

First and foremost: you’ll find a compact version of this article at the repository wiki which I’ll build up more and more as time passes. In this blog post I’ll go into more detail so newcomers don’t get scared too much while we dive into using the command line 😉

Since you need administrative privileges to install drivers I recommend you execute the following commands in an elevated PowerShell session. Since there’s already a ton of articles out there how to fire up PowerShell I won’t comment on it further. In short: you’re dealing with a window you type or paste in text that’s commanding your PC to do awesome stuff as soon as you hit Enter. If something went wrong or further actions are required it will print out some text. That’s really it. Oh, and you won’t need your mouse 😏

Add the Software Repository

I’ve decided to run and host my own software repository. Cloud storage is undoubtedly cool and convenient, but just like GitHub Releases it slows me down too much and since I’m already running a Webserver I might as well host the software my own. Now instead of the conventional way of downloading a setup executable and running through a wizard, a PowerShell (or NuGet in general) repository is optimized to install, update and remove software packages with one or more simple commands. In our case we need to tell PowerShell where to “find” the ViGEm installer module. This is achieved via the Register-PSRepository command:

Register-PSRepository -Name nuget.vigem.org -SourceLocation https://nuget.vigem.org/ -InstallationPolicy Trusted

This command might ask for confirmation to update NuGet, please confirm to do so:

NuGet provider is required to continue
PowerShellGet requires NuGet provider version '2.8.5.201' or newer to interact with NuGet-based repositories. The NuGet
 provider must be available in 'C:\Program Files\PackageManagement\ProviderAssemblies' or
'C:\Users\Nefarius\AppData\Local\PackageManagement\ProviderAssemblies'. You can also install the NuGet provider by
running 'Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force'. Do you want PowerShellGet to install
and import the NuGet provider now?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"):

Now the package management sub-system knows that there’s a new online location where software can get downloaded and installed from.

Install the Management Module

The driver installer is included in the ViGEmManagementModule. We can install (and update) it via the following command:

Install-Module ViGEmManagementModule -Repository nuget.vigem.org

As with the tradition of Command-lets you won’t get any response if the command succeeded, so don’t worry. Warnings and error messages will get printed though but we don’t want those, do we 😉

We’re now ready for action!

Working with the ViGEm Cmdlets

With the module installed we now have access to functions – called Cmdlets – which allow us to manage the bus and its driver. Let’s start with listing existing bus devices.

Get-ViGEmBusDevice

On a vanilla system the Get-ViGEmBusDevice Cmdlet won’t return any output. This is to be expected since the purpose of the command is to list the bus instances present on the system. But if I invoke this command on e.g. my development Laptop I’ll get the following output:

DevicePath         : \\?\ROOT#SYSTEM#0004#{96E42B22-F5E9-42F8-B043-ED0F932F014F}
InstanceId         : ROOT\SYSTEM\0004
DeviceName         : Virtual Gamepad Emulation Bus
DriverVersion      : 1.13.0.0
Manufacturer       : Benjamin Höglinger-Stelzer
DriverProviderName : Benjamin Höglinger-Stelzer

This means that on my system there’s one instance of the bus driver present running the driver version 1.13.0.0. At the time of this writing there’s a newer version available so let’s update while we’re on a roll 😎

Install-ViGEmBusDeviceDriver

To freshly install (or update) the bus driver, we simply invoke the Cmdlet Install-ViGEmBusDeviceDriver:

Install-ViGEmBusDeviceDriver

The command downloads the latest bus driver from downloads.vigem.org, extracts the archive and installs (or updates) the driver, considering the Operating Systems architecture. Depending on your systems state you might get a message that a reboot is required. To validate that the installation was successful we can simply call Get-ViGEmBusDevice again:

DevicePath         : \\?\ROOT#SYSTEM#0004#{96E42B22-F5E9-42F8-B043-ED0F932F014F}
InstanceId         : ROOT\SYSTEM\0004
DeviceName         : Virtual Gamepad Emulation Bus
DriverVersion      : 1.14.1.0
Manufacturer       : Benjamin Höglinger-Stelzer
DriverProviderName : Benjamin Höglinger-Stelzer

As you can see the driver version has changed. Nicely done!

Add-ViGEmBusDevice

Now what if the previous call to Get-ViGEmBusDevice didn’t return anything? Glad you asked! On a virgin system we first need to create a so called pseudo-device or Virtual Hardware. The Cmdlet Add-ViGEmBusDevice will do this:

Add-ViGEmBusDevice

Now don’t forget to call Install-ViGEmBusDeviceDriver afterwards so the new device gets the driver attached and loaded.

Remove-ViGEmBusDevice

To get rid of one or more bus devices utilize the Remove-ViGEmBusDevice Cmdlet. In contrast to the other commands we learned this one actually needs a bit of information on which device to remove. There are multiple ways to achieve that. The simplest one is to pipeline (“chain”) the Get-ViGEmBusDevice and Remove-ViGEmBusDevice like so:

Get-ViGEmBusDevice | Remove-ViGEmBusDevice

Now while this looks weird it’s one of the more neat features of PowerShell. The devices returned by the first command get “fed” into the second command which will use this information to identify the bus device(s) to remove. Once again no output will be displayed on success.

Now if you want to have control over which instance of the bus should be removed we can call the command with the following syntax:

Remove-ViGEmBusDevice -InstanceId ROOT\SYSTEM\0004

This will remove (uninstall) the device with the “virtual” Hardware Identifier (Instance ID) of ROOT\SYSTEM\0004. As you might have guessed; this value is taken from the Get command. You’ll also find this value in Device Manager when you look at the Device instance path property:

Conclusion

That wasn’t too bad was it? And keep in mind: since the process only involved some text commands you can easily make your own silent “batch” or script file to simplify installation even more.

Good luck & happy holidays! 🙂