Touch on Raw Panel

With SKAARHOJ's X-keys application (xpanel-xkeystouch package),package youfor haveour controllers, users can create software UIs accessible through browsers, which appear on the capabilitylocal network as Raw Panel devices. 
Both third-party applications adhering to connectthe oneRaw orPanel moreProtocol X-keysand keyboardsSKAARHOJ's toin-house aBroadcast SKAARHOJControl, product,Automation, and Monitoring application, Reactor™, can interface with these UIs. They can process inputs and provide feedback. These UIs are operable from any touch device equipped with USB-A.a Thisweb integrationbrowser allowsor the X-keys keyboard to function asfrom a controldesktop panelcomputer, alongsideutilizing yourstraightforward existing SKAARHOJ devices. As a result, you'll experience increased user-friendly integration between SKAARHOJ panelsHTTP and yourSVG HID devices, expanding your overall control freedom.technology.

• MixBroad yourAccess: X-keysUse from touch devices withto SKAARHOJ controllersPCs.
• EnjoyIntegrative: easyAdd andtouch powerfulwithout extra development.
• Quick Setups: Fast configuration with ReactorQuick Classes.
• NoVersatile: externalAccess computerUIs neededacross -local connectsnetworks to SKAARHOJ devices directlyeasily.
• RawCost-Efficient: Panel enables X-keys over networkEvaluate with PoE
trial
• Addbefore unique workflows with X-keys specialty devicespurchase.
  

Support Table

The X-keys models supported are listed below.

Name	Tested	Comment	Image
XK-24	Yes
XK-12 Jog-Shuttle	Yes
XK-12 Joystick	Yes	Joystick rotation is an encoder component.
XK-68 Joystick	Yes
XK-60	Yes
XK-80	Yes
XKE-124 T-bar	Yes
XKE-128	Yes
XK-68 Jog-Shuttle	Yes
XKE-64 Jog T-bar	Yes
XK-4 Stick	Yes
XK-8 Stick	Yes
XK-16 Stick	Yes
XK-3 Switch Interface	Yes
XKE-40	Yes
XK-3 Foot Pedal	Yes
XBA-T-bar Module	Pending	LED feedback not implemented yet
(more switch interfaces?)	Pending

How It Works

The X-keysapplication devicescreates becomea networkwebserver enabledthat asserves theya aredynamic turnedSVG intofile Rawthat Panelshows compliantitself devices.in full screen on the screen device it's presented on. This meanscould thatbe Reactora andreal touch device or any other third party application fully compliantcomputer with Rawscreen. PanelSo canit's usereally them.a virtual panel, not only for touch screens.

Below,To youcommunicate seewith anthe X-keyspanel, XK-24the connecteduser directlywould connect with TCP to a SKAARHOJ Blue Pill Server which in turn is connected to a PoE powered network switch. The X-keys device can be accessed via the Raw Panel TCPserver.

protocol

Examples of touch application

Touch Devices will appear on the IPnetwork. addressYou ofcan thediscover Bluethem Pillusing Server.Raw Panel Explorer:

MultipleAt X-keysthe devicesbottom canyou befind driventhe byXP_TOUCH-STREAMDECK which is mimicking a singleStream BlueDeck Pilldevice usingon screen. It's found on port 9953 as a (powered)Raw USBPanel hubdevice. inThe between:

topology

will

You can use an applicationlook like this when Raw Panel Explorer connects to search for and test your Raw Panel enabled X-keys devices. Here is an example of a scan for panels on the network (using the -aggressive setting):
it:

InsideIn Reactorthis you can discovercase the panelstouch application itself is on theport network,7950. addHere themit andis configureshown actionswith forsome theirdummy buttons,content knobs,loaded fadersinto and joysticks:it:

Watch it

(TODO)

Getting StartedConfiguration

• Connect your X-keys device to your SKAARHOJ Blue Pill Inside (with USB-A).
  
  
• 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-xkeys 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-xkeys"touch" toafter goinstalling toit and you will see the configuration page. Here you may want to make sure it's set up for Auto Start and attend to other config settings:page:
  
  

  

  
  
• PleaseThe checkfirst many config options are the logsame viewas found on the rightother side.Xpanel-applications (Stream Deck, X-keys, HIDs etc).
• The Webserver port is where you find the webserver for the touch UI.
• To select the UI style, you use the Layout dropdown. It mayhas containthese importantoptions:
  information

  
  
  

  such
as
• You licensingcan status.also Sinceselect thea X-keysratio panels don't have displays therewhich will be no other indications of errors or license quarantine than whathelp you seeto inoptimize thishow view:it looks on your destination device:
  

   

  
  
  

• Using PuTTy, Telnet or nc you can now make a TCP connection manually to test it. On a Mac, try "nc 192.168.10.20411.5 9933"9953" from the Terminal, then it should connect, type in "list"+Enter and you should see something like this:
  

  

• 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

As of August 2023, we are offering complimentary licenses to early adopters at no cost. To avail of this offer, please send your SKAARHOJ Blue Pill product serial number to innovationlab@skaarhoj.com. In your message, kindly include a note to Kasper about your intended use for the product and what your expectations are.

The xpanel-xkeystouch 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 X-keys devices.start. Please note that after 10 minutes, an unlicensed X-keysapplication device will stop sending triggers. However, you can reset this period by re-starting the xpanel-xkeystouch package in the Blue Pill Web UI.

The xpanel-xkeystouch logs will report when the quarantine periods start and end:

Configuration

By default, the xpanel-xkeys application will scan for X-keys devices on the USB port and as it finds them, assign them a Raw Panel port number starting with 9933 - and locking that to their serial numbers (which are hashes of the USB Product ID)

You can change this behavior. The configuration page for the xpanel-xkeys 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 no 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 X-keys 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. 

Fixed Panels

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

Serial Numbers

X-keys devices don't report unique serial numbers and therefore the Raw Panel server generates a sort-of serial number by making a so called "hash" (like "fb3ab267") based on the USB Product ID. The Product ID will usually be the exact same for the same product. So if you have two XK-24 X-keys devices, they will report the same serial number. 

The serial number may be found in the logs or you can discover it using Raw Panel Explorer.

Handling Multiple Similar devices

The fact that serial numbers will be the same for the same Product IDs still needs a really good solution. P.I. Engineering (the company behind X-keys) propose to set a unique ID in the X-keys internal memory, but that is not available to the Raw Panel server before it's connected to the panel, so this cannot be used (at least not readily).

At this point we have solved it by the option "Multiple Similar" which includes a hash of the USB path. This will at least give the possibility of attaching multiple of the similar X-Keys device, but unfortunately the USB path may change when you reboot your USB-HUB, so this may not be a stable solution either. Of course you can (and should ;-) just attach the same type of X-keys device to multiple SKAARHOJ Blue Pill devices so they will sit on different IP addresses, can have the same port and same serial and then the problem is solved in a stable way.

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

- kasper