HID Relay Advanced

Advanced utility to control USB relay boards with blinking support, based on usbrelay.
If this project is useful to you, you can support its development here:

Features

• All core usbrelay features: list, status, on/off
• Continuous or counted blinking: frequency control in Hz
• Multiple relay channel support: parallel multi-channel operations
• Non-blocking asynchronous operations: command returns immediately while long operations continue
• Cross-process conflict handling: named mutexes prevent channel contention
• Robust ON/OFF under concurrency: implicit blink stop and mutex release wait

Build

Prerequisites

• Visual Studio 2019 or newer (or Visual Studio Build Tools)
• .NET Framework 4.7.2
• NuGet (for package restore)

Steps

1. Open hid-relay-advanced.sln in Visual Studio.
2. Restore NuGet packages (right click solution > Restore NuGet Packages).
3. Build in Release mode.
4. The executable is generated at hid-relay-advanced\bin\Release\hid-relay-advanced.exe.

Note: usb_relay_device.dll is embedded automatically into the executable via Costura.Fody. In standard usage, no external DLL is required.

Release (Direct Download)

The project publishes Windows binaries automatically on GitHub Releases when a vX.Y.Z tag is pushed.

Published artifacts:

• hid-relay-advanced-vX.Y.Z-windows-x64.exe and .zip
• hid-relay-rust-vX.Y.Z-windows-x64.exe and .zip
• usb-relay-device-dll-vX.Y.Z-windows-x64-x86.zip
• SHA256SUMS.txt

Vendor DLL (usb_relay_device.dll)

• This DLL is a third-party vendor component and is not compiled from this repository application code.
• hid-relay-advanced.exe already embeds this DLL via Costura.Fody for standard usage.
• The vendor DLL zip is provided for advanced integration and debug scenarios.
• hid-relay-rust.exe does not use this DLL (native HID communication).
• Redistribution of this DLL follows upstream terms (GPL/commercial).

See docs/vendor-dll-release.md for full details.

Usage

Core Commands (usbrelay-compatible)

# List devices
hid-relay-advanced.exe -list

# Show status
hid-relay-advanced.exe -status

# Turn channel on
hid-relay-advanced.exe -serial BITFT -on 1

# Turn channel off
hid-relay-advanced.exe -serial BITFT -off 1

Blinking Commands

# Continuous blink at 2 Hz on channel 1
hid-relay-advanced.exe -blink -serial BITFT -channels 1 -freq 2

# Blink 10 cycles at 1 Hz on channels 1 and 2
hid-relay-advanced.exe -blink -serial BITFT -channels 1 2 -freq 1 -count 10

# Stop blink on channel 1
hid-relay-advanced.exe -stop-blink -serial BITFT -channels 1

# Stop and explicitly wait for mutex release
hid-relay-advanced.exe -stop-blink -serial BITFT -channels 1 -wait -wait-timeout-ms 8000

# Stop all active blinks
hid-relay-advanced.exe -stop-all

# Stop all active blinks and wait for lock release
hid-relay-advanced.exe -stop-all -wait

Important behavior:

• -on/-off automatically sends stop signals to active blink operations on targeted channels, then waits for mutex release before applying the action.
• The default wait timeout is 5000ms.

Daemon Mode (Background)

-daemon starts blinking that keeps running in the background. The process remains active to sustain blinking even after Main() returns.

Windows (PowerShell) - lightweight invocation:

# Use cmd /c start /B (lighter than Start-Process)
cmd /c start /B .\hid-relay-advanced.exe -blink 1 -freq 1 -daemon

Windows (CMD):

start /B hid-relay-advanced.exe -blink 1 -freq 1 -daemon

Linux/Unix:

./hid-relay-advanced -blink 1 -freq 1 -daemon &

Technical note: in .NET, reliably detaching from the parent terminal from inside the same process is not supported. Use start /B (Windows) or & (Unix) to return the prompt immediately.

To stop background blinking from another terminal:

hid-relay-advanced.exe -stop-blink -channels 1

all Channel Selector

Use all to target every channel on a relay:

# Turn all channels on
hid-relay-advanced.exe -on all

# Turn all channels off
hid-relay-advanced.exe -off all

# Blink all channels
hid-relay-advanced.exe -blink all -freq 1

# Stop blinking on all channels
hid-relay-advanced.exe -stop-blink all

Conflict Handling

If a channel is already used by another process, the tool returns a clear error:

ERROR: Channel BITFT_1 is already in use by another process

Architecture

• UsbRelayDeviceHelper.cs: P/Invoke bindings to native usb_relay_device.dll
• LockManager.cs: named mutex management for cross-process channel safety
• OperationTracker.cs: active asynchronous operation tracking
• BlinkManager.cs: asynchronous blink orchestration
• UsbRelayWrapper.cs: high-level relay operations
• Program.cs: CLI entrypoint and argument parsing

Technical Notes

• Frequency in Hz: freq = 2 means 2 full cycles per second (ON-OFF-ON)
• Period formula: period_ms = 1000 / (2 * freq) for each half-cycle
• Named mutex format: Global\HidRelay_{serial}_{channel}
• Windows event format: Global\HidRelayStop_{serial}_{channel} for cross-process stop signaling
• Non-JSON errors: emitted on stdout for WinDev compatibility
• Clean shutdown: Ctrl+C stops operations and releases locks

License

This repository source code is licensed under Apache-2.0 (see LICENSE).

Third-party components and bundled vendor artifacts keep their own licenses and terms. In particular, usb_relay_device.dll follows upstream USB relay project licensing (including GPL/commercial terms where applicable).

Security

Disclosure policy: SECURITY.md.