Stream Deck on Raw Panel

With SKAARHOJs Stream Deck application (xpanel-streamdeck package) you can connect one or more Stream Deck surfaces to a SKAARHOJ product (with USB-A or Ethernet in case of Stream Deck Studio) and integrate the Stream Deck seamlessly 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 fleet of Stream Deck devices. 

The Stream Deck devices become network enabled as they are turned into Raw Panel compliant devices. This means that Reactor and any other third party application fully compliant with Raw Panel can use them. This is an advantage even for Stream Deck Studio (which already has network capability), as Raw Panel offers a simpler, unified, and standardized protocol for third-party integration.

Below, you see a Stream Deck Plus connected directly to a SKAARHOJ Blue Pill Server which in turn is connected to a PoE powered network switch. The Stream Deck can be accessed via the Raw Panel TCP protocol on the IP address of the Blue Pill Server.

Multiple Stream Deck panels can be driven by a single Blue Pill using a charging (powered) USB hub in between:

Using the Raw Panel Protocol, you can easily send colors, text content and monochrome, grayscale and color images to the Stream Deck panels:

Watch it

Stream Deck devices are routinely used in our videos, so you will find many more examples in addition to this video.

Getting Started

• Connect your Stream Deck to your SKAARHOJ Blue Pill Inside product (with USB-A). 
  Please check table below, you may need to use a powered USB hub in between. In case of Stream Deck Studio over Ethernet, please see separate section.
  
  
• 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. (This step is not necessary for Stream Deck Studio via Ethernet).
  

  

  
  
• Go to the Packages tab of the Web UI of your SKAARHOJ device
  

  

  
  
• Find the xpanel-streamdeck package in the list of Available Packages. Click "Install". (Latest version was v2.4.1 @Sept 2024)
  

  
  
  

• When installed, you should find it listed as "Running" in the top of the Packages page:
  

  
  

  
  
• Click the package name "xpanel-streamdeck" 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-)starting the xpanel-streamdeck application you should see a nice animated boot screen on any attached Stream Deck:
  

  

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

  

  
  
• 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. 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

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 since it has no display to show it.

Stream Deck Studio

The Stream Deck Studio is slightly different from other Stream Deck Panels in that it offers ethernet connectivity, is rack mounted and has a price tag which is targeted at the professional AV- and broadcast market. SKAARHOJ supports this panel as well of course.

Here, we are sharing some technical observations about this panel:

• Keys need to be pressed relatively firm to deliver reliable and consistent keypresses.
• Display tile sizes are 144x112 pixels
• LED rings around encoders are 24 segments RGB LEDs
• Ethernet connectivity is on TCP port 5343. Requires a simple keep-alive package sent about every 4 seconds. Accepts multiple connecting clients.
• Package format/Protocol on ethernet is the same as on USB, so it's binary data
• Protocol details can be deducted from our free Go-lang Github repo: https://github.com/SKAARHOJ/go-streamdeck
• USB plug on the front seems to not be a USB hub, but rather it adds another Stream Deck as additional keys to the messages, like "button 33, button 34" etc. This was surprising to us and makes it difficult to leverage. When on Ethernet it also reports the presence or a Stream Deck Panel connected to that port, but no events was detected.
• NFC Reader returns the card ID numer as ASCII in a packet (typically 32bit/8 hex chars, but can be longer)

• Broadcasts itself via mDNS when Ethernet connected

Additional config for Stream Deck Studio

In the package configuration, there is a field called "Deep Config". For Stream Deck Studio, this can be used to customize how the panels operate. The configuration is entered as a single JSON string without any line breaks.

In a formatted view, it would look like this:

{
    "SDStudioLEDSegments": 13,
    "SDStudioLEDOffset": -7,
    "NFCUserGroups": [
        {
            "Name": "Admin",
            "Users": [
                {
                    "Name": "Kasper Keyfob",
                    "CardNumber": "B5EF4A23"
                },
                {
                    "Name": "Kasper Tesla Card",
                    "CardNumber": "153B2FA2845F80"
                }
            ]
        },
        {
            "Name": "User",
            "Users": [
                {
                    "Name": "Kasper VISA",
                    "CardNumber": "75AE20B4"
                }
            ]
        }
    ]
}

• The field "SDStudioLEDSegments" defines the number of LEDs used on the encoder LED rings, with a default of 24.

• The field "SDStudioLEDOffset" determines which LED is the starting point, with a default of 0 (the top LED). For example, using 13 LEDs with an offset of -7 creates a semi-circle from the "9 o'clock" to the "3 o'clock" position.

• A field called "TextColorInversionThreshold" defines the brightness threshold for a background color (0-100). If the background brightness exceeds this threshold, the text will be rendered in black. This is used when the LED Mode is set to "Background," where the text is displayed on a background in the specified LED color. Default value is 78.
• The structure "NFCUserGroups" is likely temporary until a proper UI for setting up NFC cards is implemented. For now, it allows you to create user groups and assign NFC cards to each group. Each group generates a new hardware component on the panel topology, which sends a button trigger to the connected application when a card is presented. The receiving Raw Panel clients can decide how to handle the button trigger. For example, if used for panel access with Reactor, it could toggle a variable that controls layer visibility in Reactor.

USB Hubs

Even if your Stream Deck should be able to connect directly to your Blue Pill and get its power from the Blue Pill we strongly recommend to use an external powered hub instead. This is mostly to avoid the power short 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 4 diverse Stream Deck panels simultaneously this way.

USB hubs we have tried and found working are:

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.

Limitations observed

• There may be a limit of four Stream Decks per hub in some cases.
• On a Mac, using a USB-C to USB-A dongle, a maximum of four Stream Decks have been successfully connected for development purposes with xpanel-streamdeck.
• A Mac setup running seven Stream Decks, distributed across multiple dongles and hubs, operated flawlessly with fairly high update speeds.
• A Blue Pill Device typically supports up to three Stream Decks for reliable operation. Although it can connect more, issues may arise as simultaneous updates to multiple Stream Deck display tiles can interfere with each other, resulting in some displays not being updated. It's important to test with your specific application and be mindful of this potential bandwidth limitation.
  

Licensing

The xpanel-streamdeck application will always give you about 10 minutes of free and unlimited Raw Panel usage since 30 seconds after application (re-)start of any number of Stream Deck controllers. After 10 minutes an unlicensed Stream Deck panel won't send or receive triggers anymore, but rather show a "License Required" message in the displays. Re-starting the xpanel-streamdeck package in the Blue Pill Web UI will reset the period.

Licenses for use of Stream Decks on a Blue Pill device currently costs 79 EUR / 96 USD (September 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 amount of Stream Decks this license covers range from 1 (Stream Deck Studio) over 7 (Stream Deck XL) to 14 (Stream Deck Mini) based on a point system but remember there may also be a practical limit in system resources of the Blue Pill device depending on what else it's doing. A license gives you 1000 points.

Configuration

By default, the xpanel-streamdeck application will scan for Stream Deck panels on the USB port and as it finds them, assign them a Raw Panel port number starting with 9923 - and locking that to their serial numbers.

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

The Server Starting Port should be changed if you have other applications running on the same Blue Pill trying to use this port. There is not clear indication if this is the case, but if something doesn't work, please check the logs if there are errors related to binding to the port.

The protocol mode can mostly stay as it is since most SKAARHOJ applications at least will detect whether ASCII or Binary mode can/should be used. Max Clients and Lock to IP is to help you guard your Raw Panel enabled Stream Deck against too many connected clients or connections from unauthorized IP addresses. It's still a fairly low-tech type of security that still assumes a friendly network environment, just keep that in mind.

Lock Serials to Port is on by default because we assume it would be nicest that any panel that once was connected to your Blue Pill you receive the same port 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 Decks 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 Stream Decks 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