Applications

• Running CLI Applications - Mac
• Running CLI Applications - Windows
• Device Core Link (DCLink)
• TCP Link for ATEM (on Blue Pill)
• Raspberry Pi Media Player from SKAARHOJ
• Keyboard & Mouse Over Ethernet

Running CLI Applications - Mac

This page will help you to understand how to run a CLI application from SKAARHOJ Innovation Lab on Mac. CLI means "command line interface" and it's the kind of geeky programs that need to get started from a black window with white text... sigh. The world is unfair, I know. But help is here. 

The example below is based on the popular Raw Panel emulator called "Raw Panel Dummies" (it emulates any SKAARHOJ panel so you can easily and freely get started on integrating support in your hardware or software applications). The principles will however be the same for any CLI application from SKAARHOJ, you just need to change the filenames.

Steps

1. Download the relevant application.
   For example, raw-panel-dummies is downloaded from from https://github.com/SKAARHOJ/raw-panel-dummies-releases/releases. For Mac, look for files that says "darwin" or "mac" in the filename, eg. "raw-panel-dummies_1.0.0_darwin_amd64" for Intel Macs or "_arm64" for M1 macs
   

   
   
   At other times, they may be distributed in a zip-file that you need to unzip first.
   
   

2. Open the download folder in Terminal
   In Finder, right click the download folder, select "Services", select "New Terminal at Folder".
   

   

   
   If you can't see you Downloads folder in this way, right click the Downloads folder in finder and select "Show in Enclosing Folder"
   

   
   
   

3. Set "execute" permissions
   

   In the Terminal window that opened, type in 
   

   chmod +x [filename of downloaded file]
   

   and Enter. This will set permissions to run the application.
   
   

   
   
   

4. Run it first time and manage security settings
   Now, try to run the application like this:
   ./[filename]
   
   Security will kick in some way: When prompted, press OK, then go to Settings > Security & Privacy and press "Allow Anyway"
   

   
   This may take a little forth and back. If the "Allow Anyway" button is not there, try to run it again, try to close and reopen the Settings window etc.
   
   

5. Run it again until it is accepted
   

   Try to run the application again. It may ask a security related question once more. Just press "Open", "OK" or "Yes" and try once more.

   
   

   
   

   Eventually, you should see something like this:

   
   
   

   Usually, if you study the text here, it will tell you clues to what do to, like run the application with "-h" to get some help for options.
   
   
6. Run it with options
   

   You are now ready to run it for real, so type in 
   

   ./raw-panel-dummies_1.0.0_darwin_arm64 -panel PTZFLY

   and Enter. This will emulate a PTZ Fly panel.
   

   
   Try other options, especially "-h" of "-list" 

   
   

7. UI - yes!
   Many applications will have a sort of UI, it will open automatically in a web browser
   

   

   
   

Every application will be different. For Raw Panel Dummies that emulates a panel, here is an example of how to use the application:  You can now connect with Telnet (or "nc") to the panel on port 9923 of your computer. Notice, the emulator runs Raw Panel in server mode. Type in "list" + Enter to identify as an ASCII client and try to press a button on the PTZ Fly emulated panel in the browser - you should see something like this:

Let us know if you are still in trouble. Reach SKAARHOJ Innovation Lab on innovationlab@skaarhoj.com or try to contact SKAARHOJs support team on support@skaarhoj.com

Running CLI Applications - Windows

This page will help you to understand how to run a CLI application from SKAARHOJ Innovation Lab on Windows. CLI means "command line interface" and it's the kind of geeky programs that need to get started from the black Command window with white text... sigh. The world is unfair, I know. But help is here. 

The example below is based on the popular Raw Panel emulator called "Raw Panel Dummies" (it emulates any SKAARHOJ panel so you can easily and freely get started on integrating support in your hardware or software applications). The principles will however be the same for any CLI application from SKAARHOJ, you just need to change the filenames.

Steps

1. Download the relevant application
   For example, raw-panel-dummies is downloaded from from https://github.com/SKAARHOJ/raw-panel-dummies-releases/releases. For Windows, look for files that says "windows" in the filename, eg. "raw-panel-dummies_1.0.0_windows_amd64.exe"
   

   

   
   
2. Open Command Window
   Unzip the file (if it was a zip file). A folder is created. Then, open "Command", type "cd   " and drag the folder over in the command window. Press enter and the command window will go to this folder:
   
   

   
   
   

   
   
3. In the Command window, type in "RawPanelDummies.Win-[yourplatform].exe -panel PTZFLY" if you want to open the emulator with a PTZFLY. The filename may be different. Just focus on the structure of "[Filename] -panel PTZFLY" - this is how you use options to change functionality (in this case, select panel to emulate)
   
   

   

   
   

   Notice: You may face a security dialog box when you run it for the first time. Please accept it.
   
   

4. A web browser opens http://localhost:8052
   
   

   

   
   

5. You can now connect with PuTTy to the panel on port 9923 of your computer. Notice, the emulator runs Raw Panel in server mode.
   
   

   
   
   

   PS: Enable "Implicit CR in every LF"

Device Core Link (DCLink)

The Blue Pill app called dclink-tcp is designed to provide a simple, unified TCP based ASCII interface to any broadcast or AV device supported by SKAARHOJ. It simply translates SKAARHOJs proprietary intermediate device protocol into structured ASCII commands for setting, getting and also subscribing to changes of values. This makes it incredibly easy for integrators to tap into any device, we have already written support for!

For a long time, we have provided the product "TCP Link for ATEM" (formerly known as "ATEM-TCP Link") which is the inspiration for this application. You can even run dclink-tcp in a special "TCP Link for ATEM" mode to support much of the legacy protocol of that product for drop-in replacement situations.

dclink-tcp lets one or more TCP clients connect to it and facilitates a simple, human readable way of setting and getting values from any number of devices of mixed type through the intermediate proprietary protocols SKAARHOJ has developed for Blue Pill.

Command Examples

Set the program video input on ATEM switcher (with device ID 2) on M/E 1 to input 3:

DC:bmd-atem/2/ProgramInputVideoSource/1/ = 3

Set Skin tone mode to "Low" on a panasonic PTZ camera:

DC:panasonic-ptz/1/SkinToneMode/=Low

Subscribe to any change on a Blackmagic Design video hub:

subscribe DC:bmd-videohub/1/

Above commands are sent from the same TCP connection since it can access all devices found on the devicecore-connector end-point

Setup

Install the "dclink-tcp" application

On your Blue Pill, go to Packages and search it up, install it and start it

Check that devicecore-connector is also installed and running

This could also be on another Blue Pill on which you are hosting the device cores.

Configure dclink-tcp

Click on "dclink-tcp" in Packages and you will see the config screen. Add a Link Server entry and enable it. You may leave the rest of the fields alone in the standard case with local device core hosting. Otherwise consider changing Device Core Connector IP:Port and also the server port (in case you have multiple Link Servers you will need that).

Open nc, telnet or Putty to connect to it

Type in "list" + enter to see which device cores and devices are available and whether they are connected.

See parameters with "listio"

Type "listio" + the base IOreference (fx. "DC:bmd-videohub/1/") to see which parameters you can read, write, the value types, which value ranges exists etc.

Type "help" to see commands

Subscribe to changes

It's very useful to subscribe to changes on an individual parameters or everything from a given device core. Try fx. "subscribe DC:bmd-videohub/1/" if you have a device IO reference called "DC:bmd-videohub/1/". This will immediately deliver the values of all parameters and keep sending updates if they change:

To change input on video hub output 12 you would send this string:

DC:bmd-videohub/1/routeInputToOutput/12/=1

Licensing

Licenses for unlimited use of DCLink on a Blue Pill device currently costs 499 EUR / 609 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 dclink-tcp application will always give you about 10 minutes of free and unlimited TCP usage after a 20-60 second quarantine period from application (re-)start. After 10 minutes you won't be able to receive or send messages over TCP. Re-starting the dclink-tcp package in the Blue Pill Web UI will reset the period.

TCP Link for ATEM (on Blue Pill)

The Blue Pill app called dclink-tcp has a special mode to convert the Blackmagic Design ATEM protocol into simple TCP commands. The focus of this is to offer a relatively compatible and more comprehensive and powerful substitute to the long term SKAARHOJ product called "TCP Link for ATEM" (formerly known as "ATEM-TCP Link"). The command set and general workings makes it an almost drop-in replacement for existing installations that need support for the newer ATEM switchers. This page deals exclusively with that. However, if you are about to make a new integration with ATEM using dclink-tcp, please consider to use the more generic API offered instead of the special mode.

A more powerful and updated version of "TCP Link for ATEM" is available as a licensed application (dclink-tcp) that you can run on any Blue Pill device. In this mode, the application limits itself to a single device connection to a single ATEM switcher and maintains the legacy protocol.

Command Examples

Send "Cut" to ATEM M/E 1:

performCutME:0=1

Select Input 3 on Aux 1:

AuxSourceInput:0=3

Run Macro 1:

MacroAction:1=0

Generally, there is a quite nice method to spotting commands: Simply make a change in ATEM software control and a line with the change is returned in the TCP client. If you sent that line yourself, you would normally make that change to the switcher. Sending the line without the "=" will request the value (but you don't need that usually as you are "subscribed" to changes happening). Commands you can't spot like this would be such as "performCutME" since that is a one shot trigger command.

See the section below for more info on the commands and the compatibility differences.

Setup

Install the "dclink-tcp" application

On your Blue Pill, go to Packages and search it up, install it and start it

Check that devicecore-connector is also installed and running

Enable "TCP Link for ATEM"

Click on "dclink-tcp" in Packages and you will see the config screen. Make sure TCP Link for ATEM is enabled. If you run devicecore-connector on your local Blue Pill (most likely) you can leave all the other fields alone.

Use nc, telnet or Putty to connect to port 8899 on your Blue Pill device

You should see a prompt about like this. Try to use ATEM software control to make a simple change to the inputs and you should see it reflected in the terminal window:

Commands

The original manual for ATEM TCP Link is found here. Not all commands are transferred over. Assuming you are only considering the legacy "TCP Link for ATEM" for drop-in replacement of the previous product, you should simply consider the commands you are using already and nothing more. Some will be available, others may not and yet others may work slightly differently. If you are changing your software anyway, it's highly recommended to use the more generic dclink-tcp interface to control your ATEM than the legacy command set.

• If you send a command name without its parameters (those numbers separate from the command by a colon, aka "dimensions"), it will return the values of for all known parameters of that command. For example, sending "InputLongName" will return names for all input sources. This is not so on the original TCP Link for ATEM where you need to specify all parameters.
• Some parameters can only be changed on Blue Pill when other features are enabled. For example, Wipe parameters can only be changed when the current transition is Wipe.

Confirmed compatibility table:

Command	Comment
performAutoME	OK
performCutME	OK
performDownstreamKeyerAutoKeyer	OK
performFadeToBlackME	OK
PreviewInputVideoSource	OK
ProgramInputVideoSource	OK
AuxSourceInput	OK
AtemConnected	OK
TransitionPosition	OK
TransitionStyle	OK
TransitionStyleNext	OK
TallyBySourceTallyFlags	Works slightly differently, where program and preview is not combined into bits in a single value but rather they are second parameters (dimensions) with 1/0 value.
TransitionMixRate	OK
TransitionDipRate	OK
TransitionDipInput	OK
KeyerOnAirEnabled	OK
DownstreamKeyerOnAir	OK
DownstreamKeyerTie	OK
TransitionNextTransition	Works differently with two parameters (dimensions) instead of one
MacroAction	OK

Licensing

Licenses for unlimited use of TCP Link for ATEM on a Blue Pill device currently costs 299 EUR / 365 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 dclink-tcp application will always give you about 10 minutes of free and unlimited TCP usage after a 20-60 second quarantine period from application (re-)start. After 10 minutes you won't be able to receive or send messages over TCP. Re-starting the dclink-tcp package in the Blue Pill Web UI will reset the period.

Raspberry Pi Media Player from SKAARHOJ

This page aims to assist you in getting started with SKAARHOJ's Raspberry Pi-based media player. This isn't a product for sale; It's offered free of charge with no guarantee of fitness for any particular purpose. Under these conditions, you're free to use it as you wish. Internally, we utilize it as a cost-effective solution for playing back video and image content during demonstrations.

Features

The media player is designed to operate on a standard off-the-shelf Raspberry Pi 4 or 5 as a binary application. It utilizes common applications like ffplay, ffmpeg, ffprobe (which are standard on the Pi), as well as VLC and mplayer in certain instances.

Features include:

• Full-screen playback of video, audio, and image files.
• Options for looping, exiting, or freezing after playback.
• Ability to create playlists for videos, audio, or images using VLC.
• Full-screen display of rtsp streams and webpages.
• Full-screen webcam viewing.
• Remote control through a web browser on port 8080, capable of controlling similar devices on the network.
• Compatibility with SKAARHOJ panels for control via the built-in device core interface.
• Media accessibility through a simple USB key.
• Autoplay feature upon startup.
• Configuration settings stored in a JSON file.
• Extraction of meta data and thumbnails.
• Using a locally connected Stream Deck for media selection

The media player is intended to connect to a screen or video processor system through its HDMI-1 output. 

Web UI

The web UI of the player is depicted in the screenshots below. The first screenshot displays three columns, each representing a player found on the network, identified by distinct IDs and names. The first player (ID: 1) also hosts the web view, although in reality, all players display the same interface. When a new player is added to the network, the existing players will detect it and include it in this web UI.

Here's a closer look at just one of the players (the host player). The media player automatically generates thumbnails when possible, but also permits you to specify your own file for use as a thumbnail if desired. It extracts relevant metadata from the files and displays this information too. During playback, you will often see a counter indicating the current position of the player.

Device Core API

The player is equipped with a Device Core API, signifying that panels from SKAARHOJ, specifically those utilizing the Reactor application, will inherently support control over the media player. This integration allows users to seamlessly manage playback, and other functionalities of the media player directly from their SKAARHOJ panels. The Device Core API facilitates a direct communication channel between the media player and the panels, ensuring a smooth and responsive user experience.

Incorporating panels like Frame Shot Pro or Frame Shot Uno extends the functionality to include displaying thumbnails of the media files available. This feature enriches the user interface by providing visual cues about the content, enhancing the ease of media selection. Such a capability is especially useful in environments where quick identification of media is crucial, allowing users to efficiently manage and control playback directly from these panels. 

Stream Deck

For local adhoc playback of media, it's also possible to attach a Stream Deck panel (most models will work) directly to the Raspberry Pi.

Installation

This guide is applicable to both Raspberry Pi 4 and 5 models, utilizing the Raspberry Pi OS available in either 32-bit or 64-bit versions. Detailed instructions for installation can be found in a separate article focused on Densitron screens. Please refer to that article and follow it up to the section titled 'Preparing the Operating System to run the Densitron screen over USB.' From that point onward, continue with the instructions provided below instead.

Preparing the Operating System to run the SKAARHOJ Media Player

• Insert the microSD card into the Raspberry Pi
• Connect an HDMI monitor to Micro-HDMI plug closest to the USB-C plug on the Pi (HDMI-1)
• Insert a newly formatted USB key (MS-DOS FAT32) into one of the USB slots of the Pi
• Connect the Ethernet jack to your network
  
• Connect your power supply to boot it up.

You should see it boot up on the HDMI monitor. If you just flashed the memory card, it will automatically reboot a few times before it finally settles with a standard desktop. It's important to stay alert because on the final desktop you will see the DHCP provided IP address shown in the upper right corner. You need that in the next step.

• On your computer, open a terminal (such as Putty on Windows) to connect with SSH to the Pi. On a Mac it would look like this:

• Here, you need to use the username ("admin" in this case) and password that you selected when customizing the OS earlier. If you have issues with logging in, you may need to attach a mouse and keyboard to your Pi and change password using the UI (Preferences > Raspberry Pi Configuration)

WIndows Server

At the time of writing, the latest Raspberry Pi OS (codenamed "Bookworm") utilizes a display server called Wayland. While Wayland offers its own set of advantages, it is not particularly suited for this media player, primarily because managing screen resolution via the command line can be challenging. The Pi Player requires control over the screen resolution, necessitating a switch to the previous X11 window manager. Fortunately, this is an easy process:

1. Type "sudo raspi-config" into the terminal.
2. In the UI that appears, select "Advanced Options", then choose "Wayland".
3. Here, you'll have the option to select X11 instead of Wayland. Do so and confirm your choice.
4. Exit the configuration tool and reboot the Pi.

After rebooting, if you execute the command "DISPLAY=:0 xrandr", you should see information similar to the following:

Screen 0: minimum 320 x 200, current 1920 x 1080, maximum 7680 x 7680
HDMI-1 connected primary 1920x1080+0+0 (normal left inverted right x axis y axis) 708mm x 398mm
   1920x1080     60.00*+  50.00    50.00    59.94    30.00    25.00    24.00    29.97    23.98  
   1920x1080i    60.00    50.00    59.94  
   1280x720      60.00    50.00    59.94  
HDMI-2 disconnected (normal left inverted right x axis y axis)

This indicates that HDMI-1 is connected to a monitor or other HDMI input which supports a resolution of 1920x1080. This looks promising.

Customizing the Desktop and Hiding the Menu Bar

Next, you might want to connect a keyboard and mouse to customize the desktop. By right-clicking on the desktop, you can remove or change its background image, as well as disable the display of the Trash bin and other icons. Doing so can be advantageous, especially if you prefer a clean desktop appearance when no media is being played.

Additionally, you might find it useful to set the taskbar to auto-hide, so it's not visible by default. This adjustment ensures a more immersive viewing experience by minimizing on-screen distractions. Here's how to auto-hide the taskbar:

sudo nano .config/wf-panel-pi.ini

In this file, add these two lines and save:

autohide=true
autohide_duration=500

Important Notice And Tip

It's important to ensure that a display is connected and powered on when the Raspberry Pi boots up. If not, the window system might fail to accurately detect the available screen resolutions, potentially leaving the HDMI output blank. This requirement can be quite frustrating, but it appears to be a limitation not easy to circumvent. Therefore, it's crucial to be diligent about keeping a display attached and turned on at all times to avoid these issues.

mplayer (for WebCam)

If you want to view Webcams in full screen, please install mplayer:

sudo apt update

sudo apt install mplayer

Static IP address

Another aspect that can be incredibly frustrating with a system supposedly designed to evolve, like the Raspberry Pi OS, is the increasing difficulty in setting a static IP address. If you've made it this far, you might have managed to configure IP using DHCP, but there are instances where setting a static IP address is more practical. This is especially true if you need a network configuration that works even in minimal setups, such as directly between the player and your laptop, without any additional network equipment.

After extensive searching, I discovered a command that effectively sets a static IP address:

sudo nmcli connection modify Wired\ connection\ 1 ipv4.method manual ipv4.addresses 192.168.11.22/23 ipv4.gateway 192.168.10.1 ipv4.dns "8.8.8.8, 8.8.4.4"

In the example above the IP address is set to "192.168.11.22" and you should replace it with your own. The subnet mask is "255.255.254.0" indicated by "/23" following the IP address. In many cases, the subnet mask is "255.255.255.0"; if this applies to you, use "/24" instead. In the example provided, the gateway is "192.168.10.1"; ensure this matches your gateway.

(Source: https://forums.raspberrypi.com/viewtopic.php?t=358069)

You are advised to reboot the device entirely after this step.

Installing core-skaarhoj-piplayer

• In the terminal, run the following command to download the SKAARHOJ Media Player:

curl -O https://raw.githubusercontent.com/SKAARHOJ/Support/master/Files/PiPlayer/core-skaarhoj-piplayer.zip

The above download is generic for both 32 bit and 64 bit systems, but does not include support for Stream Deck! For Stream Deck usage you need the 64 bit version and the file is located in the same repository location, but named "core-skaarhoj-piplayer_arm64bit.zip"

• Next, we need to extract the archive we have just downloaded:

unzip core-skaarhoj-piplayer.zip

• Insert an empty USB stick and try to run it:

./core-skaarhoj-piplayer

You should see an output more or less like this:

INFO[0000] core-skaarhoj-piplayer started, version v1.0.0-pre1 (9e3d1a8)   module=main
INFO[0000] Loading config                                module=main
INFO[0000] Set up discovery of other media players on the network  module=main
INFO[0000] mDNS services initialized                     module=main
INFO[0000] Web frontend is available on http://192.168.11.23:8080  module=main
INFO[0000] Connected to XWindows Server                  module=main
INFO[0000] Disabling screen saver                        module=main

Setting up Auto Start of core-skaarhoj-piplayer:

It can be started by systemd creating a config file, piplayer.service, in /etc/systemd/system/ with the following contents:

sudo nano /etc/systemd/system/piplayer.service

[Unit]
Description=SKAARHOJ Pi Player


[Service]
ExecStart=/home/admin/core-skaarhoj-piplayer
Restart=always
User=admin
Group=admin
WorkingDirectory=/home/admin


[Install]
WantedBy=multi-user.target

The above config assumes you named your user "admin" and keep the binary in the home directory.

After creating this file, you must reload systemd and set it to auto start on every boot:

sudo systemctl daemon-reload

sudo systemctl enable piplayer.service

Restart if needed with this:

sudo systemctl restart piplayer.service

Check status like this:

sudo systemctl status piplayer.service

Follow log messages from the service like this:

journalctl -u piplayer.service -f

Configuration

Hopefully, you've managed to set everything up as described above. All system-related settings can be tailored to your individual preferences. The goal is to use a standard, plain vanilla Raspberry Pi so you can rely on external sources for further customization.

The media player application is named core-skaarhoj-piplayer.

USB key with Media Files

To run core-skaarhoj-piplayer, a USB key is required. The application will attempt to mount /dev/sda1 and, if not found, /dev/sdb1. It will keep looping until a successful mount.

Once mounted, it searches for a playerconfig.json file on the drive. If found, this file is used for configuration. If the "AutoUpdate" flag is set internally, the application will automatically scan the USB drive for media files in the root directory and add them to the playerconfig.json file.

If the USB key is empty, the Pi Player not only creates a playerconfig.json file with sample contents but also adds a sample video file, a thumbnail, and a small slideshow as examples. These samples help confirm that your installation is successful and demonstrate how the playerconfig.json file functions.

Should the USB stick contain only a single media file, such as a video, the Pi Player will use that file to create a new playerconfig.json file on the USB drive, setting it up for autoplay.

In summary:

• For a quick start, insert an empty USB drive. The Pi Player will write sample files to it for exploration and learning.
• To play a video in a loop on boot, simply place that file on the USB key. A configuration for looped autoplay will be created.

playerconfig.json

This file contains the player's configuration. It's advised to let the Pi Player generate this file initially to understand the example structure. Many fields are self-explanatory. Here are some tips:

• Set the DeviceId field to your desired device ID for device core integration. This helps organize players in the Web UI, even if you're not using it with Reactor.
• The Name and Description fields help identify your players in Web UIs.
• AutoPlayMediaFile specifies the media entry from the Media array to be automatically loaded and played on boot.
• Setting the AutoUpdate flag to true enables automatic scanning for new media files on each boot, adding unmatched files to the configuration.
• Setting the Tag field will group mediaplayers together in the way they discover each other in the UI. Using "*" will show all players.

The Media array in playerconfig.json is an ordered list of known media, influencing their identification in Reactor and the Web UI.

• The Ignore field can be set to skip certain media files.
• The Type field specifies the entry's format (Video, Audio, Image, Webpage, Webcam, Stream).
• Thumbnail specifies a dedicated thumbnail image file.
• MediaReference is an array of strings representing media file names. Multiple entries enable playlist functionality, while a single entry defaults to the first file unless MediaIndex specifies otherwise.

metadatacache.cache

This JSON file contains metadata and thumbnail images generated by the Pi Player. Metadata and thumbnails are processed once, updating only if the media file's modification time changes.

• To regenerate all metadata, simply delete this file.

Note: Generating metadata and thumbnails for new files can delay player startup, as processing new media on a USB key may take minutes.

Troubleshooting and tips

• Use a properly cooled Pi. Prolonged video playback can heat the device to levels where it throttles and reduces clock frequency, impairing playback performance.

• If both WiFi and Ethernet are enabled simultaneously, the Web UI may display both IP addresses, resulting in duplicate columns for that player in the Web UI.

• For your information, it will utilize /dev/video0 for the webcam functionality.

   

• Debugging: If you encounter issues with the Pi Player, you can enable more detailed logging with the command: LOG=debug,ln ./core-skaarhoj-piplayer. However, before running this command manually, make sure to stop the service using systemctl if it's set up as one.

• Note that an empty core-skaarhoj-piplayer.toml file could potentially cause problems. If this occurs, the file can be safely deleted to resolve the issue.

Known Issues

• Probably Obsolete: It has been frequently noted that during long times of playback, the USB key may simply be "lost" on the system so that it won't even appear as a device under /dev/sd*. Requires a reboot. 

Keyboard & Mouse Over Ethernet

SKAARHOJ Blue Pill products equipped with USB-A can function as a keyboard/mouse transmitter to hardware endpoints connected to one or more computers, allowing remote control via keyboard and mouse over ethernet. This setup is similar to a KVM (Keyboard, Video, Mouse) solution, but without the video component, which is assumed to be managed separately.

The goal is not to replace existing KVM solutions on the market, but rather to leverage the existing presence of a SKAARHOJ device with USB-A to potentially transmit keyboard and/or mouse inputs over a network to a server, a concept often contemplated by our users.

A key feature of this solution is that it requires a SKAARHOJ hardware device to be connected to the computer being controlled, eliminating the need for software installation on the target computer. Any device that accepts keyboard input will recognize the connected SKAARHOJ device as a keyboard and mouse, thus simplifying setup.

Each controlled computer requires its own hardware device. The solution here uses an existing SKAARHOJ product called "TCP Link for ATEM" loaded with an alternative firmware, available for free download. On the SKAARHOJ panel side, there are two methods: using the xpanel-hids application to connect a keyboard and/or mouse as Raw Panel devices for peer-to-peer configuration, or using the core-skaarhoj-kmserver device for enhanced performance and support for multiple destination channels. The latter allows for easy selection of channels via device parameters, enabling a SKAARHOJ panel to function as a central control panel for keyboard and mouse operations.

Benefits:

• Reduced clutter and fewer devices in your control room: simply connect the keyboard or mouse to your SKAARHOJ device.
• No software installation required on the destination end: it utilizes a hardware-based solution.
• Ability to send key presses and combinations from SKAARHOJ broadcast panels using the Raw Panel protocol.
• Connect multiple destination endpoints using the high-performance, dedicated core-skaarhoj-kmserver device and select between them on your SKAARHOJ panel.

Limitations

• All keyboard and mouse data is transmitted unencrypted over the network. It is assumed that the network is secure, such as a friendly network or a VPN that provides its own encryption. This is important since sensitive information, such as passwords, might be typed in.
• Only "standard" keyboards and mice are supported, with HID reports of 8 and 4 bytes respectively. More complex HID reports, such as those from advanced gaming mice, may not be compatible.
• It is recommended to test the compatibility of the keyboard and mouse you plan to use, as well as the acceptance of input at the destination endpoint, to ensure functionality.

Security

Once again, remember that

• all data is transferred unencrypted on the network and therefore can be tapped for information such as passwords.
• the TCP server is either a Raw Panel server or the Keyboard/Mouse server of core-skaarhoj-kmserver and in both cases, other clients can connect by default and listen to the traffic unless you set up limitations (such as allowed client IPs)

Setting up "TCP Link for ATEM" as Keyboard/Mouse client

The SkaarhojKM firmware for TCP Link for ATEM will turn this device into a keyboard and mouse when you plug it into a computer. On the ethernet jack it will try to connect to one or two servers as a TCP Client. The servers can be a Raw Panel server that should identify as models XP_HIDS-GENERICKEYBOARD (or XP_CORE_GENERICKEYBOARD) or XP_HIDS-GENERICMOUSE (or XP_HIDS_GENERICMOUSE). This response is what determines if inputs are interpreted as mouse or keyboard commands.

If the server is a Keyboard Mouse server from the core-skaarhoj-kmserver device core, then the communication is set up a little differently and requires the set up of a channel on the device. The channel is used by the device to filter out keyboard/mouse commands intended for other end points and only accept those intended for itself.

Install alternative firmware

Download the binary hex file SkaarhojKM.hex from this page.

Use the SKAARHOJ Firmware Updater tool to upload the file to your TCP Link for ATEM, which is assumed connected via a Micro USB - USB-A cable to your computer. This follows the normal guidelines for updating SKAARHOJ stand alone firmwares (see the TCP Link for ATEM manual).

As it uploads, you should see a green progress bar moving:

Set IP addresses

After a successful upload or a power cycle, go immediately to the Serial Monitor of the SKAARHOJ firmware updater. You should see output like this:

You now need to manually set IP addresses up. Here is an example:

ip=192.168.10.21
subnet=255.255.254.0
server1=192.168.11.119:9963
server2=192.168.11.119:9964
reset

Each of these lines, one at a time, is typed into the input field at the bottom of the SKAARHOJ Updater Application window.

Eventually it will reset and in this case the servers connect and show that in the serial monitor:

Serial Monitor

The serial monitor is an important tool to check if everything is correctly set up. You can even monitor the incoming commands such as key presses and mouse movements. Here is an example:

The most important thing to look out for is errors. If one of the servers are not connected by set up with an IP address, you will experience heavy lagging for the other server. So watch out for such messages. They will look like this:

Command	Description
ip=x.x.x.x	Sets the IP address of the TCP Link for ATEM device. Each x is an octet in the IP address, fx. "ip=192.168.10.21"
gateway=x.x.x.x	Sets the gateway of the device. Each x is an octet in the IP address, fx. "ip=192.168.10.1"
subnet=x.x.x.x	Sets the subnet of the device. Each x is an octet in the IP address, fx. "ip=255.255.254.0"
server1=x.x.x.x:port server2=x.x.x.x:port	Sets the IP address of the Keyboard/Mouse server or Raw Panel device. Each x is an octet in the IP address and port is the port number, fx. "ip=192.168.11.119:9963" The firmware supports two servers. If input is delivered from a Raw Panel device, one could be your keyboard, another could be your mouse. Set the server to "0.0.0.0:0" if you want to disable it!
server1Channel=byte server2Channel=byte	Sets the channel number to listen to when using the core-skaarhoj-kmserver device core which supports multiple end points. Only packages tagged with this channel will be forwarded to the destination computer.
reset	Reboots the unit
newmac	Will generate a new MAC address for the unit in case there is a clash.

LED codes

During boot up you will see the status LED to the right of the Ethernet jack rotate colors through red, green, blue and finally white.

During boot up it will remain white.

As soon as the unit is in run mode, the led will start blinking:

• Blinking Red: There is an issue. No connection is likely to be the problem. Check the serial monitor.
• Blinking Green: All is good, connecting link place.

Approving keyboards on Mac

On Mac OS you will be prompted to identify your keyboard. This will work like any other keyboard you attach, so just press the button explained by the graphic. In terms of keyboard language, this solution is agnostic to that. It assumes a 105 key keyboard and faithfully transfers the keynumbers - not ASCII numbers - between the SKAARHOJ unit and the destination. It's in other words transparent. However a given keypress is interpreted on the destination system is up to that system and the language profile you have selected for the keyboard.

xpanel-hids as server

xpanel-hids allows you to convert various HID USB devices (Human Interface Devices) into ethernet enabled Raw Panels. If you do so with a generic keyboard or mouse the output commands are conveniently aligned with those expected by the SkaarhojKM firmware for TCP Link for ATEM. The hardware component numbers also corresponds directly to the official key numbers that are found in the HID report (modifier keys starting from 256 plus their bit number 0-7). Here is a picture of the keyboard and mouse layout and numbers for reference:

xpanel-hids has it's own page on this wiki to explain it's functions and config. Please check that out too. Especially you are likely to have to work with injecting another vendor and product ID for your keyboard and mouse since yours are most likely not the same as the ones we have. Also, for a mouse, consider trying the "XYScaler" parameter for adjusting its sensitivity.

This is an example config (default):

If you restart the core and having a keyboard and mouse plugged into a USB hub, you will see output like this. The HID SCAN OVERVIEW shows all devices found on the bus and reveals the Vendor ID (VID) and Product ID (PID) for each device.

Reading on you can see how the keyboard and mouse gets found and associated with a TCP port. Here are lines related to the mouse:

The log reveals it's available on port 9964. It also shows that shortly after, it receives a connection from our TCP Link for ATEM with the SkaarhojKM firmware, namely from IP address 192.168.10.21.

xpanel-hids is a licensed application for the Blue Pill platform. Please visit the xpanel-hids page for more information.

Reactor and core-skaarhoj-rawpanel as server

Instead of having the SkaarhojKM firmware talk directly to a keyboard or mouse Raw Panel made by xpanel-hids, you can also set up a "partial" raw panel server as a device core and assign arbitrary keystrokes or combinations using Reactor. This approach would let you create a button on a regular SKAARHOJ panel for example to press a function key like "F5" or hold down shift and press "c" to copy the selected text.

First you must add the Raw Panel device core to Reactor:

Set it up like this:

In this case we have chosen to create a raw panel server on port 9963 - the same port as the xpanel-hids server for the keyboard before. Of course, they cannot co-exist in this way, so make sure you stop the xpanel-hids application first. 

Other than that, the most important thing is calling the variant "GENERICKEYBOARD" exactly like that since this will make the SkaarhojKM firmware identify this raw panel as a keyboard.

You could now set up buttons for keystrokes or combinations by adding a button press:

Setting the value to "4" as here corresponds to pressing the "a" key on a QWERTY keyboard.

More complex sequences can also be built manually in event handlers using sequences:

In this case, step 1-4 is:

1. Hold down left GUI button (true)
2. Hold down "c" (true)
3. Release "c" (false)
4. Relealse left GUI button (false)

The numbers for the GUI button is 259 and for "c" it's 6. This can be seen if you edit the parameter:

Reactor and the core-skaarhoj-rawpanel device core are free with most SKAARHOJ products

core-skaarhoj-kmserver as server

This device core will

• Look for keyboards and mice and automatically connect them if found
• Send both keyboards and mouse (mice!) from a single server
• Send a more compact and higher performance message format to the SkaarhojKM end point
• Incorporate a channel byte in the message so only SkaarhojKM end points listening to that channel reacts
• Make available a device core for setting the channel

In this way, you can create a selector on your panel to select the destination for your keyboard/mouse.

This approach is the recommended approach if you want a serious full keyboard/mouse solution to Keyboard/Mouse over network.

Inside Reactor you set up the device core like this:

Settings include a server port (again, here it's the same as the one previously used for xpanel-hids and also core-skaarhoj-rawpanel, so only use one of those at a time unless you change ports).

Max Clients and especially Lock to IPs are the security measures you can use to secure that only expect SkaarhojKM units connect as clients and receive the data from the keyboard and mouse.

If you edit the device core inself, you can also preset how many channels you want the system to have:

The max would be 255 since it's a byte that is used for identifying channels.

When a core-skaarhoj-kmserver connects to the SkaarhojKM firmware on an TCP Link for ATEM, it will look like this in the serial monitor:

The serial monitor will also show the received HID reports forwarded. For a keyboard keypress it looks like this:

Server 1: #1:K:0,0,56,0,0,0,0,0
Server 1: #1:K:0,0,0,0,0,0,0,0

For moving a mouse it looks like this:

Server 1: #1:M:0,3,0,0
Server 1: #1:M:0,26,0,0
Server 1: #1:M:0,22,2,0
Server 1: #1:M:0,15,2,0
Server 1: #1:M:0,4,0,0
....

The number "#1" is the channel embedded in the message.

License

The core-skaarhoj-kmserver device core is a licensed application. Please reach out to our sales or support team for more information. It will have a limited function for 10 minutes.