MK20Box

Turn your Waveshare MK20 into a live sim-racing dashboard and button box.

A SimHub plugin that puts real telemetry on the keys and the strip — speed, gear, fuel, tyre temps — and sends real keystrokes back to the game.

---

What it does

Your MK20 has 20 little LCD keys, two rotary encoders and a 428×142 display. MK20Box makes all of it useful while you drive.

Live telemetry	Speed, gear, RPM, fuel, tyre temps — anything SimHub reports, on the strip
Real keystrokes	The device sends them itself, so they work even with SimHub minimised
Per-game profiles	ETS2 gets truck controls, iRacing gets pit controls, switched automatically
Shareable	Export a profile to a file — pictures included — and send it to a friend
Pages & folders	Twenty keys is never enough. Nest them
530+ icons	A sim-racing icon set is built in, or drop in your own picture or GIF
Encoders	Volume, brightness, media — or a different keystroke per direction
Macros	Type a whole pit message from one key

Install

Requires SimHub 9.12.1 or later.

1. Download the latest release and unzip it.

2. Close SimHub — it holds the plugin open while running.

3. Copy everything inside the SimHub\ folder into your SimHub folder, usually C:\Program Files (x86)\SimHub, keeping the layout intact:

   Mk20Box.dll             <- plugin
   Mk20Box\                <- its dependencies and icons
   Languages\Mk20Box.resx  <- translations
   

4. Start SimHub. It offers to enable newly found plugins — enable MK20Box. You can also enable it later under Settings -> Plugins.

5. Plug in the MK20. It is picked up automatically.

Nothing SimHub ships is replaced. To uninstall, delete those three items plus PluginsData\Common\Mk20BoxPlugin.GeneralSettings.json, which holds your profiles.

Getting started

Open the MK20Box page in SimHub's sidebar.

The editor is a picture of your device. Click a part of it, and the panel on the right becomes the editor for that part:

• Click a key — give it a picture, a label and an action.
• Click the strip — add widgets that show live telemetry.
• Click an encoder — choose what turning it does.

Press Send to device when you like what you see.

Tip: right-click a key or the strip for picture options.

Start from an example

examples/LMU.mk20profile is a ready-made Le Mans Ultimate layout — a main page plus folders for electronics, pit, MFD and cameras, across sixty keys.

In the Profiles section, press Import and pick the file. It arrives alongside your own profiles, so nothing is overwritten, and it is available for every game rather than tied to LMU.

The keys carry their pictures and labels, but their actions are left unassigned: bind them to suit your own wheel, since anything already on it is better left there. It is a starting point to edit, not a finished profile.

_{The same profile on the real device}

Documentation

Usage guide — how to drive the plugin

• Keys — icons, labels, keystrokes, macros
• Pages and folders — more than twenty keys
• Secondary screen — widgets and live telemetry
• Encoders — the two knobs
• Profiles — a layout per game
• Properties — what SimHub gets back
• If something does not work

Architecture — how it is implemented

• Project layout
• Two seams — the device format and the host API
• Where work happens — device vs plugin
• Telemetry and profiles
• Device constraints — hard-won facts
• Building

Icon catalogue — every bundled icon, by category

Building

Requires the .NET SDK and a local SimHub install, whose assemblies are referenced but never modified.

setx SIMHUB_INSTALL_PATH "C:\Program Files (x86)\SimHub\"
git clone --recursive https://github.com/alexmuraru27/Mk20Box.git
cd Mk20Box
.\build.ps1

The result is staged in dist\Mk20Box, ready to copy. While developing, .\deploy.ps1 builds and installs it for you.

Tests

Unit tests live in src/Mk20Box.Tests and cover the parts of the plugin that are pure logic: the layout, key and widget models, the editor's copy and paste, profile import and export, and the SimHub property lookup. They need neither SimHub running nor an MK20 plugged in.

dotnet test src\Mk20Box.Tests\Mk20Box.Tests.csproj

release.ps1 runs them as well, and refuses to pack a release if any fail.

Credits

Built on MK20Control, a reverse-engineered library for the MK20's serial protocol. MK20Box is an independent project and is not affiliated with Waveshare or SimHub.

Licence

Apache 2.0.