Virpil LED Control Script for SPAD.neXt

Purpose

This script fills the functionality gap in SPAD.neXt regarding the direct control of LEDs on compatible Virpil devices. It allows SPAD.neXt to manipulate LED lights on specific Virpil hardware rather than relying on official configuration software. As a result it allows dynamic lighting control integrated directly into your SPAD.neXt workflows and automations.

Highlights

• Solid Color Control: Set fixed colors on LEDs via the SPAD.neXt application interface.
• Automated Cycles: Configure color cycling with user-defined intervals.
• Flexible Integration: Functions as a standard external script, triggerable from any SPAD.neXt state change or rule.
• Instrumented via JSON: Configuration is handled through a simple JSON structure passed to the script as an argument.

Installation:

1. Place in SPAD.neXt Addons directory: Unpack the DLL files from the recent release (see https://github.com/runeapetersen/VirpilLedControls/releases/) into the SPAD.neXt Addons directory, normally located in %userprofile%\Documents\SPAD.neXt\Addons. Create the Addons directory if it does not exist. SPAD.neXt will automatically load the assembly on startup and initialize the script. See the official documentation at https://docs.spadnext.com/extending-and-apis/scripting-interface/c-scripting-precompile for information.
   Note that if you are getting errors from SPAD.neXt concerning blocked files the included text file "unblocking_files_info.txt" describes how to get around this.
2. Configure SPAD.neXt: When creating a new rule or state change, you can trigger the script by specifying "External Script" as an action and picking "VirpilLightAutomationScript" from the dropdown. Paste the Json snippet defined in the Usage section below into the provided argument text box.

Usage

1. Get Device IDs: Open the VPC Configuration Tool, go to your device view, and note the Product ID (PID) hexadecimal value. Use this value exactly as displayed.
2. Identify the LED: For commands targeting an individual LED, find its number in the VPC tool's monitoring tab. If the LED is on a slave board, note the board slot number displayed.
3. Build Your Configuration: Create a single-line JSON object. Each command includes a Type discriminator:

Type	Purpose	Additional fields	Notes
SingleColor	Set one LED to a fixed color.	LedId, BoardType, Color
ColorCycle	Cycle one LED through multiple colors.	LedId, BoardType, Colors, IntervalMs
DeviceSingleColor	Set a device-level color.	Color	Device-level command. Cancels any active button-level commands for this device.
DeviceFirmwareDefaultColor	Reset the device to its firmware default colors.	None	Device-level command. Cancels any active button-level commands for this device.

Field Reference:

Field type	Allowed Values	Description
Pid	Hexadecimal Product ID string	Device Product ID from the VPC Configuration Tool; no conversion is required.
LedId	LED number	LED to control on the selected board.
BoardType	OnBoard, SlaveBoard1, SlaveBoard2, SlaveBoard3, SlaveBoard4	Selects the controller containing the LED. OnBoard is the device's built-in controller. SlaveBoard1–SlaveBoard4 correspond to the numbered slave-board slots shown in the VPC Configuration Tool; slave boards may be joystick attachments or slaved control panels.
RGB components (R, G, B)	Off, Thirty, Sixty, Full	Intensity for the red, green, or blue channel in a Color.
IntervalMs	250 ms or greater	Delay between colors in a ColorCycle.

For a slave-board LED, set BoardType to the corresponding slot and LedId to the LED number shown for that board in the VPC tool. See the SlaveBoard1 and SlaveBoard2 examples below.

Example: set LED 3 on the onboard board to green:

{"Type":"SingleColor","Pid":"4259","LedId":3,"BoardType":"OnBoard","Color":{"R":"Off","G":"Full","B":"Off"}}

Example: set LED 3 on slave board 1 to green:

{"Type":"SingleColor","Pid":"4259","LedId":3,"BoardType":"SlaveBoard1","Color":{"R":"Off","G":"Full","B":"Off"}}

Example: cycle LED 3 on slave board 2 between green and red every 500 ms:

{"Type":"ColorCycle","Pid":"4259","LedId":3,"BoardType":"SlaveBoard2","Colors":[{"R":"Off","G":"Full","B":"Off"},{"R":"Full","G":"Off","B":"Off"}],"IntervalMs":500}

Example: cycle LED 3 between green and red every 500 ms:

{"Type":"ColorCycle","Pid":"4259","LedId":3,"BoardType":"OnBoard","Colors":[{"R":"Off","G":"Full","B":"Off"},{"R":"Full","G":"Off","B":"Off"}],"IntervalMs":500}

Example: set a device-level color:

{"Type":"DeviceSingleColor","Pid":"4259","Color":{"R":"Off","G":"Full","B":"Off"}}

Example: reset a device to its firmware default colors:

{"Type":"DeviceFirmwareDefaultColor","Pid":"4259"}

4. Apply in SPAD.neXt: Create a new rule → Add Action → Select External Script → Choose VirpilLightAutomationScript → Paste your JSON string into the argument box.
5. Troubleshooting: If lights don't respond, check %appdata%\SPAD.neXt\logs. The script logs all configuration payloads and HID errors there.

If you are encountering errors, remember to check the log files at %appdata%\SPAD.neXt\logs. The script will write any messages to the standard application log.

Automatic LED Reset

The addon resets any devices it has controlled to their firmware default colors when SPAD.neXt shuts down.

If you want to have power state changes trigger LED resets, you will need to set up custom event triggers. Some experimentation may be required depending on the aircraft.

Attribution

This project was inspired by https://github.com/charliefoxtwo/Virpil-Communicator and implements logic adapted from that library to in order to create the data structure which controls the Virpil LED lights. As a result, this script is released under the same GNU v3.0 license.

Limitations

The script is designed to work with Virpil LED lights and may not work with other types of lights. Additionally, the script may not work with all versions of SPAD.neXt. The script is provided as-is and the author is not responsible for any damages or issues that may arise from using the script.

Building

• Clone repository
• Create a directory named local in the root of the newly cloned repository
• Copy SPAD.Interfaces.dll and SPAD.neXt.Devices.dll from your SPAD.neXt installation folder to the new local directory
• Open the solution file in the src directory and build the solution.