# 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.<span class="Apple-converted-space"> </span>

[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/ZJYimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/ZJYimage.png)

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](mailto:innovationlab@skaarhoj.comi) if you have a device you think should be supported here.

<table border="1" id="bkmrk-stream-deck-model-su" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 24.8455%;"></col><col style="width: 11.2485%;"></col><col style="width: 11.1248%;"></col><col style="width: 32.7565%;"></col><col style="width: 19.9011%;"></col></colgroup><tbody><tr><td>**Device**</td><td>**Vendor ID**</td><td>**Product ID**</td><td>**Comment**</td><td>  
</td></tr><tr><td>**Tangent Ripple**

("TangentRipple")

</td><td><div><div><div><div>1240</div></div></div></div></td><td><div><div>64015</div></div></td><td>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](https://wiki.skaarhoj.com/attachments/53)) has been contributed by user Jaron Berman. Thanks!

</td><td>[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-11/scaled-1680-/wbPimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-11/wbPimage.png)

</td></tr><tr><td>**USB Generic Gamepad**

("GamePad")

</td><td><div><div>2064</div></div></td><td>1

</td><td>Supports all buttons. Left button array is linked to left joystick. Analog button changes that function. Precision of the joysticks is very low.

</td><td>[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/woEimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/woEimage.png)

</td></tr><tr><td><div><div>**[Delcom FootSwitch Mouse](https://www.delcomproducts.com/productdetails.asp?PartNumber=703600-5M)**</div><div>("FootSwitchDelcom")</div></div></td><td><div><div><div><div>4037</div></div></div></div></td><td><div><div>13921</div></div></td><td></td><td>[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/QdFimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/QdFimage.png)

</td></tr><tr><td><div><div><div><div>**Contour ShuttlePro**  
("ContourShuttlePro")</div></div></div></div></td><td><div><div><div><div><div><div>2867</div></div></div></div></div></div></td><td><div><div><div><div>48</div></div></div></div></td><td></td><td>[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/image.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/image.png)

</td></tr><tr><td><div><div><div><div>**Logitech Presenter R400**  
</div></div><div>  
</div><div>("LogitechR400")</div></div></div></td><td><div><div><div><div><div><div>1133</div></div></div></div></div></div></td><td><div><div><div><div><div><div>(50477)</div></div></div></div></div></div></td><td>(see R500)

</td><td>[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2024-02/scaled-1680-/rF8image.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2024-02/rF8image.png)

</td></tr><tr><td><div><div><div><div>**Logitech Presenter R500s**</div><div>  
</div></div><div>("LogitechR500")</div></div></div></td><td><div><div><div><div><div><div>1133</div></div></div></div></div></div></td><td>50496  
(50494)</td><td>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.

</td><td>[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2024-02/scaled-1680-/ewZimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2024-02/ewZimage.png)

</td></tr><tr><td><div><div><div><div><div><div>**APEM HF-45S10-U Joystick**</div><div>  
("APEM-HF45S10U")</div></div></div></div></div></div></td><td><div><div><div><div><div><div>1678</div></div></div></div></div></div></td><td>415</td><td>APEM USB Joystick with two buttons on top.

</td><td>[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2024-06/scaled-1680-/HDgimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2024-06/HDgimage.png)

</td></tr><tr><td><div><div><div><div>**Generic Keyboard**</div><div>  
</div></div><div>("GenericKeyboard")</div></div></div></td><td><div><div><div><div><div><div>1133</div></div></div></div></div></div></td><td><div><div>49974</div></div></td><td>Logitech G213 (Y-U0029)

*Many other keyboards would work too, but you will need to detect it's vendor and product IDs and inject into the package. See below for instructions.*

</td><td></td></tr><tr><td><div><div><div><div>**Generic Mouse**</div></div></div></div><div>  
</div><div>("GenericMouse")</div></td><td><div><div><div><div><div><div>1133</div></div></div></div></div></div></td><td><div><div>49271</div></div></td><td>Logitech B100 (M-U0026). Notice that by default the X/Y positions are reported as encoder input scaled down by a factor 5 and also sampled at only 10Hz.

*Many other mice would work too, but you will need to detect it's vendor and product IDs and inject into the package. See below for instructions.*

</td><td></td></tr></tbody></table>

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.

[![IMG_8011.JPG](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/img-8011.JPG)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/img-8011.JPG)

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

[![IMG_8013.JPG](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/img-8013.JPG)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/img-8013.JPG)

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:

[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/0X6image.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/0X6image.png)

[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/Sjgimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/Sjgimage.png)

### 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:  
    [![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2022-11/scaled-1680-/xFqimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2022-11/xFqimage.png)
- Go to the **Packages tab** of the Web UI of your SKAARHOJ device  
    [![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2022-11/scaled-1680-/72eimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2022-11/72eimage.png)
- Find the ***xpanel-hids*** package in the list of Available Packages. Click "Install"  
    [![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/wJOimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/wJOimage.png)
- When installed, you should find it listed as "Running" in the top of the Packages page:  
    [![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/HwBimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/HwBimage.png)
- **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:  
      
    [![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/Ndximage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/Ndximage.png)
- Check the log in the right side to see if panels are recognized and check it also for quarantine information (see licensing further down):  
    [![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/UIIimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/UIIimage.png)
- 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.   
    [![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/JMlimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/JMlimage.png)
- With PuTTy on Windows you should make sure to set "Implicit CR in every LF"
    
    [![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2022-11/scaled-1680-/521image.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2022-11/521image.png)

### 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. A single license will allow up to about 10 USB devices to be connected and Raw Panel enabled.


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.

[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/LC6image.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/LC6image.png)

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.

[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/wPKimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/wPKimage.png)

### 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](https://github.com/SKAARHOJ/Support/blob/master/Manuals/SKAARHOJ/SKAARHOJ_RawPanel_V2.pdf) and in addition we will advice you to download and play with the [Raw Panel Explorer](https://github.com/SKAARHOJ/raw-panel-explorer/releases/). To help you succeed with SKAARHOJs command-line-applications, please check out these wiki pages for [windows](https://wiki.skaarhoj.com/books/applications/page/running-cli-applications-windows) and [mac](https://wiki.skaarhoj.com/books/applications/page/running-cli-applications-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:

[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/5Vvimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/5Vvimage.png)

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

[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/Zreimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/Zreimage.png)

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.

### Deep Configuration

It's possible to provide additional JSON based configuration to the application. This is done by adding JSON to the "Deep Config" field:

[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2024-05/scaled-1680-/image.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2024-05/image.png)

Here is examples of config that can be helpful:

<table border="1" id="bkmrk-deep-config-descript" style="border-collapse: collapse; width: 100%; height: 251.771px;"><colgroup><col style="width: 54.8037%;"></col><col style="width: 45.2625%;"></col></colgroup><tbody><tr style="height: 29.349px;"><td style="height: 29.349px;">**Deep Config**</td><td style="height: 29.349px;">**Description**</td></tr><tr style="height: 62.9427px;"><td style="height: 62.9427px;">`{"Development":{"Mode":"Scan"}}`  
</td><td style="height: 62.9427px;">Stops normal run mode of the application and scans the USB hub repeatedly, reporting in detail the results. This is very technical and output looks very chaotic.</td></tr><tr style="height: 130.13px;"><td style="height: 130.13px;">`{"Development":{"Mode":"Log","SleepMS":100}}`  
  
`{"Development":{"Mode":"Log","SleepMS":500,"VendorID":1240}}`  
</td><td style="height: 130.13px;">Stops normal run mode of the application and and rather connects to the first found device that corresponds to the filter settings. After that it will report back the received HID reports as bytes in the log with a max period of 100 ms.  
Filters include "VendorID", "ProductID", "UsagePage", "Usage", "InterfaceNum"</td></tr><tr style="height: 29.349px;"><td style="height: 29.349px;">`{"InjectVIDsAndPIDs":{"GenericKeyboard":[[1267, 259]]}}`  
</td><td style="height: 29.349px;">This adds the VID (1267) and PID (259) to the existing list of devices recognized as a Generic Keyboard. "GenericKeyboard" is the identifier found under the title of the device type in the table of supported devices in the top.  
This can be used to test if a mouse, keyboard, game pad, remote control etc. could potentially work as one of the known devices. If successful the user can help SKAARHOJ make the support permanent by reporting a working pair of VID and PID.</td></tr><tr><td>`{"XYScaler":5} `  
</td><td>Divides the Generic Mouse input for X/Y positions by 5. </td></tr><tr><td> </td><td>  
</td></tr></tbody></table>

Here is an example of the log output from Log mode, and a Logitech Keyboard inserted, pressing "a", "b", "c". Note that log reports are updated at a frequency of about 1 second in the UI.

[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2024-05/scaled-1680-/dG4image.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2024-05/dG4image.png)

### Feedback

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

\- kasper