Skip to content
Library guide

Library guide

This page summarizes what a library for driving the display must provide – independent of the programming language. The .NET reference implementation implements it.

Layers

    flowchart TB
    App["Application / service<br/>(read sensors)"] --> Session
    Session["Session / keep-alive<br/>Timer 250 ms, reconnect, off on exit"] --> Device
    Device["Device<br/>Find, open, 65-byte write, error → disconnect"] --> HID["HID backend<br/>hidraw · hidapi · Windows HID"]
    Session --> Codec["Codec (pure, no I/O)<br/>Frame → 64-byte packet"]
  
LayerResponsibilityTestability
Codecvalues → 64 bytes per update packet, off packetfully unit-testable with the test vectors
DeviceVID/PID search, opening, prepending the report ID, write with timeoutagainst real device / mock
Sessionperiodic sending, atomic swap of the current frame, hotplugwith fake device

Requirements

Detection

  • Only address known VID/PID pairs (5131:200e, 5131:2007). Vendor 0x5131 is also used for unrelated devices – never write to “all devices of 0x5131”.
  • Additionally check: HID interface with output report length 64 (or 65 including report ID).
  • No serial number available → distinguish multiple devices by their physical path.
  • Missing product/manufacturer strings are not an error.

Sending

  • Send every packet completely (64 bytes); via hidraw/hidapi/Windows with report ID 0x00 prepended (65 bytes).
  • Interval 250 ms by default, configurable, but at most 400 ms – the display turns off after approx. 400–500 ms without a packet.
  • The sending thread must not be blocked by slow sensors: read sensors at their own pace and place the last valid frame into the session atomically.
  • One writer per device (mutex or similar). Two processes on the same device cause flickering.
  • Fill the time fields with the current local time in every packet.

Errors & hotplug

SituationBehavior
Device not present at startuprescan periodically (e.g. every second) or use a udev monitor
Opening fails with “access denied”clear message pointing to the udev rule; do not log in an endless loop
Write fails (ENODEV, EPIPE, I/O error)close handle, state “disconnected”, reconnect
Write timeoutretry once, then treat as an error
Exit (Dispose, SIGTERM, service stop)stop timer, send off packet, close handle
System suspendreconnect after resume (device is often re-enumerated)

Recommended API

Frame            – immutable set of values (nullable fields, temperatures always in °C, unit separate)
encode_update(frame, now) -> bytes[64]
encode_off()              -> bytes[64]
enumerate()               -> [DeviceInfo]        # without opening (works without permissions)
open(info)                -> Device
Device.send_packet(bytes[64])
Session(connect_fn, interval)
Session.update(frame)       # thread-safe
Session.start() / Session.close(send_off = true)
events: connected(path), disconnected, packet_sent(bytes)

Non-goals

  • Controlling fan/pump (handled via the motherboard headers).
  • ARGB lighting (handled via the 5 V ARGB header).
  • Sensors in the library itself – better as a plug-in/callback so that the library stays platform-neutral.

Platform backends

PlatformBackendNotes
Linuxhidraw directly (open/write/poll)no dependencies, details
Linux / Windows / macOShidapi (libhidapi-hidraw, hidapi.dll)native library required
.NETHidApi.Net (AOT-capable binding for hidapi)used in the reference, requires native hidapi
.NETHidSharp (fully managed, Linux via hidraw + libudev)no native dependencies, but trim warning under AOT
Windows nativeCreateFile on interface path, WriteFile with 65 bytespath via SetupAPI/HidD_GetHidGuid
Anylibusb (interrupt OUT on EP 0x01, 64 bytes without report ID)kernel driver must be detached – not recommended