How to Create a Custom Controller

This page covers how to create a custom Vixen (non-pixel) 8 bit controller. This page is applicable when working with custom hardware where the built in Vixen controllers are not suitable or need to be extended.

Controller assemblies may contain a configuration dialog.

Project Type:

Create a ‘Class Library (.NET Framework) Project using Visual Studio 2019 or later. Sometimes the easiest method is to copy another controller on the file system and rename the project file and folder to be the new name you desire. Then import that project into the solution and modify the existing files to suit your needs. This will give you something to start with.


Add a project reference to the Vixen.System project.


Controllers are required to contain the following classes:

  • Instance.cs – This is the class that processes the data from Vixen.
  • DataPolicy.cs –
  • DataPolicyFactory.cs
  • Descriptor.cs – This class contains meta-data about the controller. The controller’s name and who created it etc. The controller should have a unique name and Guid.

Controller Module Instance

This class contains the logic to send data to the device. This class should inherit from ControllerModuleInstanceBase found in the Vixen.dll assembly mentioned above.

The custom controller is required to override the UpdateState method. This method is called each frame to send data to the controller. The outputStates argument contains the data for the controller channels. The controller should loop over this array and cast each entry as follow:

(outputStates[channel] as _8BitCommand).CommandValue

The command value contains the intensity or brightness for the channel with a range of 0 -255. With zero representing off (dark) and 255 representing full intensity.

Build Destination:

The controller assembly needs to be built to or copied to C:\Program Files\Vixen\Modules\Controller\.

Warning! – The current Vixen installer wipes out the entire Vixen directory structure. The custom controllers will be removed when upgrading Vixen. Make sure to copy your custom controllers back into this directory before starting Vixen and going into Display Setup otherwise Vixen will remove the controllers and all patching configuration.


Hits: 101