HID devices on Raw Panel

With SKAARHOJs HID application (xpanel-hids package) you can connect one or more particular USB devices to a SKAARHOJ product (with USB-A) and integrate the USB device as a control panel with your existing SKAARHOJ devices. In this way you can enjoy even more freedom of user friendly integration with professional SKAARHOJ panels and your existing HID devices.

The devices supported are specific models and brands of HID devices. We know this list is very short at the moment, and we are looking to extend it by your help, so reach out to innovationlab@skaarhoj.com if you have a device you think should be supported here.

Device	Vendor ID	Product ID	Comment
Tangent Ripple	1240	64015	Trackballs are read out as two encoders, one for each axis. Encoders and trackballs are scaled down by a factor 20 to reach a usable level for most applications, such as Reactor. You can change this by setting this JSON string into the "Deep Config" field which will set scaling to "1:1" instead. You can experiment with the values to reach your desired resolution. {"EncoderScaler":1,"TrackballScaler":1} A mount for the Tangent Ripple (rippleMount.stp) has been contributed by user Jaron Berman. Thanks!
USB Generic Gamepad	2064	1	Supports all buttons. Left button array is linked to left joystick. Analog button changes that function. Precision of the joysticks is very low.
Delcom FootSwitch Mouse	4037	13921
Contour ShuttlePro	2867	48
Logitech Presenter R400	1133	(50477)	(see R500)
Logitech Presenter R500s	1133	50496 (50494)	The presenter remote recognizes two types of button presses: forward and backward. It only responds to short presses (less than 0.5 second), ignoring longer ones. Upon releasing the button, the down-press trigger is sent, followed by an automatic up-press trigger approximately 50ms after the initial press.

The USB HID devices are network-enabled as they are transformed into Raw Panel compliant devices. This transformation implies that Reactor, along with any other third-party application fully compliant with Raw Panel, can utilize them.

In the illustration below, you'll observe a Delcom Footswitch Mouse directly connected to a SKAARHOJ Blue Pill Server. This server is then linked to a Power over Ethernet (PoE) powered network switch. The Footswitch can be accessed via the Raw Panel TCP protocol, using the IP address of the Blue Pill Server.

Multiple HID devices can be operated by a single Blue Pill. To do this, interpose a powered USB hub between the devices.

With the Raw Panel Protocol, you can readily integrate button presses, joystick movements, and encoder rotations, often referred to as 'triggers', back into your broadcast and AV applications. Devices compliant with Raw Panel will appear in a visually pleasing graphical form in the corresponding applications. Here are two examples from the Raw Panel Explorer and Reactor:

Watch it

(TODO)

Getting Started

Connect your HID Device to your SKAARHOJ Blue Pill Inside product (with USB-A).
Go to the Settings tab of the Web UI of your SKAARHOJ device, find where it says "USB-A" and turn it on. After doing so, please power cycle your SKAARHOJ device once or twice and then confirm that USB-A is still enabled:
Go to the Packages tab of the Web UI of your SKAARHOJ device
Find the xpanel-hids package in the list of Available Packages. Click "Install"
When installed, you should find it listed as "Running" in the top of the Packages page:
Click the package name "xpanel-hids" to go to the configuration page. Here you may want to make sure it's set up for Auto Start and attend to other config settings:
Check the log in the right side to see if panels are recognized and check it also for quarantine information (see licensing further down):
Using PuTTy, Telnet or nc you can now make a TCP connection manually to test it. On a Mac, try "nc 192.168.11.5 9923" from the Terminal, then it should connect, type in "list"+Enter and you should see something like this below. Try pressing a few buttons and you will see trigger messages arrive in a human readable form. This is the Raw Panel protocol in ASCII version.
With PuTTy on Windows you should make sure to set "Implicit CR in every LF"

USB Hubs

You can operate multiple devices simultaneously by using a USB hub. For the best results, it is recommended to use a powered hub if possible.

Licensing

Licenses for unlimited use of HID devices on a Blue Pill device currently cost 79 EUR / 96 USD (January 2024). Please contact support@skaarhoj.com or sales@skaarhoj.com to place your order and get a license assigned. Remember to include your Blue Pill serial number in the request.

The xpanel-hids application will always provide approximately 10 minutes of free and unlimited Raw Panel usage. This starts 30 seconds after the application (re-)start for any number of HID devices. Please note that after 10 minutes, an unlicensed HID device will stop sending triggers. However, you can reset this period by re-starting the xpanel-hids package in the Blue Pill Web UI.

The xpanel-hids logs will report when the quarantine periods start and end.

Configuration

By default, the xpanel-hids application will scan for supported HID devices on the USB port and as it finds them, assign them a Raw Panel port number starting with 9963 - and locking that to their serial numbers.

You can change this behavior. The configuration page for the xpanel-hids application has a number of options worth knowing about.

The Server Starting Port should be adjusted if other applications running on the same Blue Pill are attempting to use this port. There is no explicit indication if this is the case, but if something isn't functioning properly, please check the logs for errors related to port binding.

The protocol mode can mostly remain unchanged since most SKAARHOJ applications will determine whether ASCII or Binary mode should be utilized. The Max Clients and Lock to IP features help protect your Raw Panel enabled HID devices against excessive client connections or connections from unauthorized IP addresses. However, remember that this is a relatively low-tech security measure, which assumes a friendly network environment.

By default, Lock Serials to Port is enabled because we anticipate that it would be most convenient for users if any panel that was previously connected to your SKAARHOJ controller were assigned the same port the next time it is connected.

Fixed Panels

For fixed installations, it's recommended that you set up discrete HIDs as fixed panels. This allows you to assign a specific port to a specific serial number and set individual settings for the above mentioned general settings for the panels.

Exploring with Raw Panel

Above you saw how simple it is to connect to a Raw Panel enabled device. Here is the full protocol information and in addition we will advice you to download and play with the Raw Panel Explorer. To help you succeed with SKAARHOJs command-line-applications, please check out these wiki pages for windows and mac.

When you start the Raw Panel Explorer, it will scan the network for Raw Panel compliant devices. It would find your connected HID devices and show them on the web page that opened:

Click the "Connect" button to the right of the XP_HIDS-GAMEPAD panel and you will see this:

The drawing you see on this page comes straight out of the Raw Panel protocol - one of the many awesome features: Raw Panel allows any connecting client to ask for the topology of the panel and it lets any client know exactly which features a panel has and how to render it visually. This info is provided as a mix of JSON and SVG data.

This should get you started. Have fun! :-)

Please write to innovationlab@skaarhoj.com for any comments or questions. We would love to hear (positive and constructive) remarks from you.

- kasper