HID devices on Raw Panel

With SKAARHOJs HID application for Blue Pill (xpanel-hids package) you can connect one or more particular USB devices to a SKAARHOJ Blue Pill 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
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

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 StreamHID DeckDevice to your SKAARHOJ Blue Pill Inside (with USB-A). 
  Please check table below, you may need to use a powered USB hub in between.
  
  
• Go to the Settings tab of the Web UI of your Blue Pill device, find where it says "USB-A" and turn it on. After doing so, please power cycle your Blue Pill once or twice and then confirm that USB-A is still enabled:
  

  

  
  
• Go to the Packages tab of the Web UI of your Blue Pill device
  

  

  
  
• Find the xpanel-streamdeckhids 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-streamdeck"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 (see below)
  

  

  
  
• After (re-)startingCheck the xpanel-streamdecklog applicationin youthe shouldright side to see aif nicepanels animatedare bootrecognized screenand oncheck anyit attachedalso Streamfor Deck:quarantine information (see licensing further down):
  

  

  
  
• Shortly after you should see the "Waiting for Blue Pill" screen. This indicates that the Stream Deck is ready to be used over network, but no TCP client is connected. One of the displays will reveals the IP address and port on which to connect:
  

  

  
  
• 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:
  this

  

  below.
  
• Try pressing a few buttons and turn the encoders (if you have a Stream Deck Plus) and you will see trigger messages arrive in a human readable form. This is the Raw Panel protocol in ASCII version.version. You can also send commands back to the StreamDeck to put colors, text and graphics into the displays.
  

  

  

• With PuTTy on Windows you should make sure to set "Implicit CR in every LF"
  
  

  
  
  

• Issues? At this point we don't know what common issues may exist, but if after following the steps above you don't see the blue SKAARHOJ boot screen on the Streamdeck, please read the rest of this page to search for clues, then reach out to innovationlab@skaarhoj.com and let us help you! :-)
  

Device Support

This is the Stream Deck models supported

Stream Deck Model	Support	Power Consumption @5V (Full brightness white)	Direct Connection to Blue Pill
Stream Deck Original	Yes (at least two revisions supported)	370 mA	Yes
Stream Deck MK2	Yes	?	(Yes)
Stream Deck Mini	Yes	130 mA	No (use powered Hub)
Stream Deck XL	Yes	490 mA	No (use powered Hub)
Stream Deck Pedal	Yes	80 mA	Yes
Stream Deck Plus	Yes	360 mA / white full brightness	Yes

Notice: By default, every newly connected Stream Deck gets a new port number assigned to its serial and until the configuration data gets cleared out, this will stick. It means that it won't always be port 9923 where you find a connected Stream Deck and especially for the Pedal you need to look in the logs (or use Raw Panel Explorer to find it on the network) to know what the port number may be.

USB Hubs

EvenYou ifcan youroperate Streammultiple Deckdevices shouldsimultaneously beby ableusing toa connectUSB directlyhub. to your Blue Pill and get its power fromFor the Bluebest Pillresults, weit stronglyis recommendrecommended to use an externala powered hub instead. This is mostly to avoid the power circuit of the Blue Pill to be strained too much by powering a hungry USB device. 

In any case, if you want multiple Stream Decks connected simultaneously to a single Blue Pill, you need a charging USB hub with external power anyway. We have tested that a Blue Pill is able to run at least 5 diverse Stream Deck panels simultaneously this way.

USB hubs we have tried and found working are:

USB Hub	Specs	Comment
i-tec, U3CHARGEHUB10	10 port hub, USB-3, DC12V	Our favourite, as it feels pretty strong and has power buttons for each USB plug.
StarTech ST53004U1C	4+1 ports	Works
LC-Power, LC-HUB-ALU-2B-7	7 ports	Works
D-Link, DUB-H4	4 ports	Works, but not as convincingly as the others, especially this may get into trouble because if external power is not applied, it will try to get the power out of the Blue Pill and that becomes an issue.

Notice, we do not accept responsibility for the above information to be correct or sufficient, we are just kindly sharing our own (limited) experiences. Our impression is that most other powered "charging" USB hubs would work as well.possible.

Licensing

ForAs the time being (updatedof August 2023),2023, we are givingoffering complementarycomplimentary licenses away for free to early adopters.adopters Justat no cost. To avail of this offer, please send us your Blue Pill serial number to innovationlab@skaarhoj.comcom. withIn your message, kindly include a kind messagenote to Kasper about it,your tellintended us a bit what you will be using ituse for the product and what your expectations are.

The xpanel-streamdeckhids application will always giveprovide youapproximately about 10 minutes of free and unlimited Raw Panel usageusage. sinceThis starts 30 seconds after the application (re-)start offor any number of StreamHID Deckdevices controllers. AfterPlease note that after 10 minutesminutes, an unlicensed StreamHID Deckdevice panelwill won'tstop sendsending. orHowever, receiveyou triggerscan anymore,reset butthis ratherperiod showby a "License Required" message in the displays. Re-re-starting the xpanel-streamdeckhids package in the Blue Pill Web UIUI.

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

Configuration

By default, the xpanel-streamdeckhids application will scan for Streamsupported DeckHID panelsdevices on the USB port and as it finds them, assign them a Raw Panel port number starting with 99239963 - and locking that to their serial numbers.

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

The Server Starting Port should be changedadjusted if you have other applications running on the same Blue Pill tryingare attempting to use this port. There is notno clearexplicit indication if this is the case, but if something doesn'isn't work,functioning properly, please check the logs if there arefor errors related to bindingport to the port.binding.

The protocol mode can mostly stayremain as it isunchanged since most SKAARHOJ applications at least will detectdetermine whether ASCII or Binary mode can/should be used.utilized. The Max Clients and Lock to IP is tofeatures help you guardprotect your Raw Panel enabled StreamHID Deckdevices against tooexcessive manyclient connected clientsconnections or connections from unauthorized IP addresses. It'sHowever, stillremember that this is a fairlyrelatively low-tech type of security thatmeasure, stillwhich assumes a friendly network environment, just keep that in mind.environment.

By default, Lock Serials to Port is on by defaultenabled because we assumeanticipate that it would be nicestmost thatconvenient for users if any panel that oncewas waspreviously connected to your Blue Pill youwere receiveassigned the same port the next time it is connected. 

Large Text and No LED Bar is related to rendering on the panels. For example, by default the rendering in the displays has a little rectangular area on top that is painted in the "LED color" sent to the button from the Raw Panel protocol. This helps to make buttons on Stream Decks just as useful as they are on a real SKAARHOJ panel. But if you want to use the whole display area for graphics, just enable this. Notice that these two options - if enabled - will override the same options being set for Fixed Panels. Read on...

Fixed Panels

For fixed installations, it's recommended that you set up discrete Stream DecksHIDs 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.

Don'ts

While in our testing the xpanel-streamdeck package seems very robust to hot plugging and unplugging Stream Deck devices, we have also observed that excessive so-doing can lead to lock-ups on the USB bus so that even a reboot of the Blue Pill is required. So, play nice and we are sure you will find this quite reliable and stable.

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 StreamHID Decksdevices and show them on the web page that opened:

Click the "Connect" button to the right of the XP_STREAMDECK-PLUS 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.

For example, the various components of a Stream Deck plus, such as screens, buttons, encoders, swipe areas are provided by JSON and could be tabularized like this:

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