# X-keys on Raw Panel

With SKAARHOJ's X-keys application (*xpanel-xkeys* package), you have the capability to **connect one or more X-keys keyboards** to a SKAARHOJ product, equipped with USB-A. This integration allows the X-keys keyboard to function as a control panel alongside your existing SKAARHOJ devices. As a result, you'll experience increased user-friendly integration between SKAARHOJ panels and your HID devices, expanding your overall control freedom.

- <span class="Apple-converted-space">Mix your X-keys devices with SKAARHOJ controllers</span>
- <span class="Apple-converted-space">Enjoy easy and powerful configuration with Reactor</span>
- <span class="Apple-converted-space">No external computer needed - connects to SKAARHOJ devices directly</span>
- <span class="Apple-converted-space">Raw Panel enables X-keys over network with PoE</span>
- <span class="Apple-converted-space">Add unique workflows with X-keys specialty devices  
    </span>

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

#### Support Table

The X-keys models supported are listed below.

<table border="1" id="bkmrk-stream-deck-model-su" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 30.4079%;"></col><col style="width: 12.8554%;"></col><col style="width: 32.5093%;"></col><col style="width: 24.3511%;"></col></colgroup><tbody><tr><td>**Name**</td><td>**Tested**</td><td> **Comment**</td><td>**Image**</td></tr><tr><td><div><div>XK-24</div></div> </td><td>Yes </td><td> </td><td>[![XK24.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xk24.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xk24.jpg)

</td></tr><tr><td><div><div>XK-12 Jog-Shuttle</div></div></td><td> Yes</td><td> </td><td>[![XK12JOG.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xk12jog.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xk12jog.jpg)

</td></tr><tr><td><div><div>XK-12 Joystick</div></div> </td><td>Yes </td><td>Joystick rotation is an encoder component. </td><td>[![XK12JOYSTICK.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xk12joystick.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xk12joystick.jpg)

</td></tr><tr><td><div><div>XK-68 Joystick</div></div></td><td>Yes</td><td>  
</td><td>[![XK68JOYSTICK.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xk68joystick.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xk68joystick.jpg)

</td></tr><tr><td><div><div>XK-60</div></div></td><td>Yes</td><td>  
</td><td>[![XK60.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xk60.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xk60.jpg)

</td></tr><tr><td><div><div>XK-80</div></div></td><td>Yes</td><td>  
</td><td>[![XK80.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xk80.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xk80.jpg)

</td></tr><tr><td><div><div>XKE-124 T-bar</div></div></td><td>Yes</td><td>  
</td><td>[![XKE124TBAR.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xke124tbar.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xke124tbar.jpg)

</td></tr><tr><td><div><div>XKE-128</div></div></td><td>Yes</td><td>  
</td><td>[![XKE128.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xke128.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xke128.jpg)

</td></tr><tr><td><div><div>XK-68 Jog-Shuttle</div></div></td><td>Yes</td><td>  
</td><td>[![XK68JOGSHUTTLE.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xk68jogshuttle.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xk68jogshuttle.jpg)

</td></tr><tr><td><div><div>XKE-64 Jog T-bar</div></div></td><td>Yes</td><td>  
</td><td>[![XK64JOGTBAR.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xk64jogtbar.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xk64jogtbar.jpg)

</td></tr><tr><td><div><div>XK-4 Stick</div></div></td><td>Yes</td><td>  
</td><td>[![XK4.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xk4.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xk4.jpg)

</td></tr><tr><td><div><div>XK-8 Stick</div></div></td><td>Yes</td><td>  
</td><td>[![XK8.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xk8.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xk8.jpg)

</td></tr><tr><td><div><div>XK-16 Stick</div></div></td><td>Yes</td><td>  
</td><td>[![XK16.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xk16.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xk16.jpg)

</td></tr><tr><td><div><div>XK-3 Switch Interface</div></div></td><td>Yes</td><td>  
</td><td>[![XK3SI.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xk3si.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xk3si.jpg)

</td></tr><tr><td><div><div>XKE-40</div></div></td><td>Yes</td><td>  
</td><td>[![XKE40.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xke40.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xke40.jpg)

</td></tr><tr><td><div><div>XK-3 Foot Pedal</div></div></td><td>Yes</td><td>  
</td><td>[![XK3FOOT.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xk3foot.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xk3foot.jpg)

</td></tr><tr><td><div><div><div><div>XBA-T-bar Module</div></div></div></div></td><td>Yes</td><td>A 3D printable STEP-file for a stand that will make the T-bar module align with SKAARHOJ products like Air Fly can be downloaded here.

[XKE-14\_T-bar\_XC\_v2.step](https://wiki.skaarhoj.com/attachments/49)

</td><td>[![XBATBAR.jpg](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xbatbar.jpg)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xbatbar.jpg)

</td></tr><tr><td>XK-12 Switch Interface</td><td>Yes</td><td> </td><td>[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-11/scaled-1680-/HRbimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-11/HRbimage.png)

</td></tr><tr><td>HD15 Wire Interface</td><td>Yes</td><td>  
</td><td>[![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-11/scaled-1680-/u5aimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-11/u5aimage.png)

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

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

#### How It Works

The **X-keys 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.

Below, you see an X-keys XK-24 connected directly 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 TCP protocol on the IP address of the Blue Pill Server.

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

Multiple X-keys devices can be driven by a single Blue Pill using a (powered) USB hub in between:

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

You can use an application like [Raw Panel Explorer](https://github.com/SKAARHOJ/raw-panel-explorer/releases) 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):

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

Inside Reactor you can discover the panels on the network, add them and configure actions for their buttons, knobs, faders and joysticks:

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

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

### Watch it

<iframe allowfullscreen="allowfullscreen" height="314" src="https://www.youtube.com/embed/8v-hNG4BxqE" width="560"></iframe>

### Getting Started

- **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:  
    [![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 Blue Pill 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-xkeys*** package in the list of Available Packages. Click "Install"  
    [![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/xD2image.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/xD2image.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-/opsimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/opsimage.png)
- **Click the package name "xpanel-xkeys"** 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-/lKRimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/lKRimage.png)
- Please check the log view on the right side. It may contain important information such as licensing status. Since the X-keys panels don't have displays there will be no other indications of errors or license quarantine than what you see in this view:  
    [![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/QHJimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/QHJimage.png)
- Using PuTTy, Telnet or nc you can now make a TCP connection manually to test it. On a Mac, try "nc 192.168.10.204 9933" from the Terminal, then it should connect, type in "list"+Enter and you should see something like this:  
    [![image.png](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/scaled-1680-/qfAimage.png)](https://wiki.skaarhoj.com/uploads/images/gallery/2023-08/qfAimage.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 X-keys on a Blue Pill device currently costs 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-xkeys 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. Please note that after 10 minutes, an unlicensed X-keys device will stop sending triggers. However, you can reset this period by re-starting the xpanel-xkeys package in the Blue Pill Web UI.

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

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

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

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

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.

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

#### Serial Numbers

X-keys devices don't report unique serial numbers until recent versions and therefore when X-keys devices don't report a serial number, the Raw Panel server generates a sort-of serial number by making a so called "hash" (like "fb3ab267") based on the USB Product ID in case the X-keys device doesn't report it. 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 of older X-keys 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