> For the complete documentation index, see [llms.txt](https://manual.simhubdash.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manual.simhubdash.com/device-definition-authoring/simucube-integration.md).

# Simucube device definitions

SimHub can use the Simucube API exposed by Simucube Tuner to drive compatible displays and LEDs in the Simucube 3 / Simucube Link ecosystem. The Device Definition Builder can create definitions for screen-only, screen-and-LED, and LED-only devices without requiring a dedicated SimHub driver for each model.

{% hint style="warning" %}
Simucube Tuner must be running. If Tuner is stopped or restarted, SimHub temporarily disconnects the device and reconnects it when the API becomes available again.
{% endhint %}

The Device Definition Builder supports three Simucube configurations.

| Configuration                      | Screen model     | Hardware communication                         |
| ---------------------------------- | ---------------- | ---------------------------------------------- |
| Screen only                        | **Simucube API** | No LED interface is required                   |
| Screen and LEDs on the same device | **Simucube API** | **Screen passthrough**                         |
| LEDs only, without a screen        | No screen        | **Simucube API (LEDs-only device, no screen)** |

Do not select the LEDs-only Simucube hardware interface for a device that also exposes a screen. Use **Screen passthrough** so the screen and LEDs share the same Simucube API device and session.

Adding a Simucube screen does not claim its LEDs by itself. SimHub only opens LED control when the definition also enables and configures LEDs.

## Creating a definition

1. Start Simucube Tuner and connect the device.
2. Create or open a project in the **Device Definition Builder**.
3. Enable the screen and/or LED features required by the device.
4. Select the configuration from the table above.
5. Enter the Manufacturer ID and Product ID reported by the Simucube API scan.
6. Check that the device is marked **Matches this definition**.
7. For an LED-capable definition, configure the LED count and logical-to-physical mapping as usual.
8. Test the definition before exporting the installable package.

### Model identifiers

A Simucube definition is matched using the stable model identifiers reported by Tuner:

* **Manufacturer ID**: the API `manufacturer_id` value.
* **Product ID**: the API `product_id` value.

These values are strings and are not the USB VID and PID. Matching is case-insensitive, but the complete values must match.

With Tuner running and the device connected, the builder lists the devices reported by the API and shows whether each device matches the current definition. Use **Rescan Simucube devices** after reconnecting hardware or changing the identifiers.

### Automatic detection

Definitions with valid Manufacturer and Product IDs are automatically detected in the Device Picker. Multiple devices of the same model are supported.

### Display behavior

Simucube displays support fine software brightness control. Touch input is not currently supported through this integration.

## Troubleshooting

If the device is not detected:

1. Confirm that the compatible Simucube Tuner version is running.
2. Confirm that the device is visible in Tuner.
3. In the Device Definition Builder, compare the reported Manufacturer ID and Product ID with the definition.
4. Confirm that the selected mode matches the hardware capabilities: screen only, screen with LED pass-through, or LEDs only.
5. Use **Rescan Simucube devices** or reopen the Device Picker.