Introduction - how are controllers implemented in FutureDecks/FutureDJ

General info

Every fully-supported controller is implemented using a .js (JavaScript) script file that resides in the controllers folder on Windows or in the app bundle on Mac (inside the app itself). You can also place controller scripts in the Documents/FutureDecks/controllers folder. This folder is user-accessible and all the controllers here take priority over the ones the software comes with. So, you can basically override a default controller script if you want to.

When FutureDecks starts, all the scripts are detected and compiled (you can use DebugView on Windows / Console on Mac to see any error/debug messages from the scripts). Also at startup, all MIDI and HID controllers are scanned and connected to the software. The software then tries to match every connected hardware controller to a script (it basically detects which of the scripts are meant to implement that specific controller). To do this the software must somehow identify the hardware controller.

How controllers are identified

This is done differently for MIDI and HID controllers. It is important to note that there is an order which the software observes when identifying a specific controller. The order is also the preferred one to use when you implement new controllers.

• HID controllers
  1. VID/PID - this is the preferred way to detect an HID controller. See below what VID/PID are and how to find them
  2. device name - the actual name of the HID device - this is something which is not very reliable but it can be used if for some reason the VID/PID method can not work

• MIDI controllers
  1. VID/PID - this is the preferred way to detect a MIDI controller, however this only works on Windows. See below what VID/PID are and how to find them
  2. SysEx ID - this is the preferred way to detect a MIDI controller on Mac (since we can not use VID/PID on Mac) but also for Windows. Almost every controller has a unique SysEx ID that can be used to identify that specific brand and model of controller. You can use DebugView on Windows / Console on Mac to see the SysEx ID of the connected controllers (start DebugView/Console before starting FutureDecks). If a controller does not have a sysex id then you can use the next option
  3. device name - the actual name of the MIDI IN and OUT device - this is something which is not very reliable but it can be used if the other methods don't work (eg. the controller does not have a sysex id)

In general, VID/PID is used for HID controllers and VID/PID + SysEx ID are used for MIDI controllers. Whenever possible try to avoid identifying the controller using it's name (which might change depending on firmware, drivers and even the USB port is connected to).

VID/PID

VID/PID stands for Vendor/Product ID and every brand/model USB device has a unique number. To find out the VID/PID of a certain USB device (a hardware controller) you can:

• on Windows - open Device Manager (right click properties on Computer to find it or simply type Device Manager in the search field). Find the USB device you want (which might be in the Sound controllers or Human Interfaces tabs, not necessarily on the USB tab) and right click -> Properties. Go to the Details tab and choose Hardware Ids (instead of Device description). You will see something like "USB\VID_0556&PID_0001&MI_00". The actual VID and PID for this example are 0556 and 0001. You can then use these in the script as 0x0556 and 0x0001 (you just add 0x in front of them).

• on Mac - Apple menu -> About This Mac -> More Info -> System Report -> USB. Click on the USB device you want and you will be able to see Vendor ID and Product ID. You can then use these in the script.