SignalBridge Plugin

An OpenRGB plugin that runs user-supplied SignalRGB-compatible JavaScript device plugins in OpenRGB.

中文文档 | English

Compatibility Notice

SignalBridge is an independent compatibility project. It was developed from publicly available SignalRGB developer documentation and open-source device plugin material, not by reverse engineering, decompiling, modifying, or extracting source code from the SignalRGB application.

This repository does not include or redistribute SignalRGB application binaries, proprietary source code, paid content, effect libraries, artwork, or device scripts. Users are responsible for providing scripts they are legally permitted to use and for complying with the applicable script licenses and terms.

SignalRGB and OpenRGB names are used only to describe compatibility with their respective ecosystems. This project is not affiliated with, endorsed by, sponsored by, or officially supported by SignalRGB, Whirlwind Virtual Realities Inc., OpenRGB, or their contributors.

Features

• SignalRGB-Compatible Script Runtime: Execute user-supplied JavaScript device plugins within OpenRGB
• Embedded JavaScript Runtime: Uses QuickJS for fast, lightweight script execution
• Automatic Device Discovery: Scans and matches compatible scripts to connected USB HID devices
• Model Translation: Translates between compatible script device definitions and OpenRGB devices
• Configuration Management: Persists device-specific settings across sessions
• Real-time Control: Direct USB HID communication for low-latency RGB updates
• Multi-threaded Architecture: Background discovery without blocking OpenRGB UI

System Requirements

Runtime Requirements

• OpenRGB: 1.0
• Operating System: Windows 10/11 (tested); Linux/macOS have not been tested
• Device Scripts: Place compatible .js scripts that you are permitted to use in OpenRGB's configuration directory under SignalBridge/scripts/ (default Windows path: %APPDATA%/OpenRGB/SignalBridge/scripts/)

Build Requirements

• CMake: 3.16 or later (3.21 or later for presets)
• Qt: 6.8.3 for Windows/macOS; the distribution's Qt 6 packages for Linux
• Compiler: MSVC 2022 or another compiler with C++20 support
• Git: For submodule dependencies

Building from Source

1. Clone the Repository

git clone https://github.com/Zayrick/SignalBridgePlugin.git
cd SignalBridgePlugin
git submodule update --init --recursive

2. Configure with CMake

cmake --preset debug
cmake --preset release

3. Build the Plugin

cmake --build --preset debug --target SignalBridgePlugin
cmake --build --preset release --target SignalBridgePlugin

Alternative: Fast Parallel Builds with JOM

# JOM is located at C:\Qt\Tools\QtCreator\bin\jom\jom.exe
cmake -G "NMake Makefiles JOM" -B build/custom -DCMAKE_BUILD_TYPE=Release
cd build/custom
C:\Qt\Tools\QtCreator\bin\jom\jom.exe

4. Run Tests (Optional)

# Run all tests
cmake --build --preset debug --target SignalBridgeCoreTests
ctest --test-dir build/debug -C Debug --output-on-failure

# Or run the test executable directly
./build/debug/Debug/SignalBridgeCoreTests.exe

Installation

1. Build the plugin following the instructions above
2. Locate the output DLL: build/release/Release/SignalBridgePlugin.dll
3. Copy to OpenRGB plugins directory:

   %APPDATA%/OpenRGB/plugins/SignalBridgePlugin.dll
   

4. Restart OpenRGB
5. Enable the plugin: Settings → Plugins → Enable "Signal Bridge Plugin"

Usage

Initial Setup

1. Place compatible device scripts that you are permitted to use in OpenRGB's configuration directory under SignalBridge/scripts/ (default Windows path: %APPDATA%/OpenRGB/SignalBridge/scripts/)
2. Launch OpenRGB and navigate to the SignalBridge tab
3. Click "Scan Devices" to discover compatible devices

Device Discovery

The plugin will:

• Scan all .js files in OpenRGB's SignalBridge/scripts/ configuration directory
• Extract device metadata (vendor ID, product ID, model name)
• Match scripts against connected USB HID devices
• Create OpenRGB controllers for matched devices

Script Use

• SignalBridge does not download, bundle, or grant rights to third-party device scripts.
• Use only scripts you own, authored yourself, or are otherwise licensed or permitted to use.
• Do not redistribute third-party scripts with this project unless their license or owner allows it.

Device Configuration

• Compatible devices appear in OpenRGB's main device list
• Configure RGB settings through standard OpenRGB controls
• Script-specific settings are available in the SignalBridge tab
• Configurations are automatically saved and restored

Viewing Logs

The SignalBridge tab displays real-time script execution logs, useful for debugging device issues.

Architecture

Core Components

SignalBridgePlugin (OpenRGB Interface)
├── SignalBridgePluginCore (Implementation)
│   ├── DiscoveryService (Device Discovery)
│   │   ├── ScriptScanner (Find .js files)
│   │   └── ScriptMetadataExtractor (Parse script metadata)
│   ├── ControllerRegistry (Manage Controllers)
│   │   └── SignalBridgeController (Per-device controller)
│   │       ├── QuickJsRuntime (JavaScript execution)
│   │       ├── EndpointSession (HID device handles)
│   │       ├── TopologyMapper (SignalRGB → OpenRGB translation)
│   │       └── FrameBuilder (Color frame rendering)
│   ├── DeviceConfigStore (Configuration persistence)
│   └── SignalBridgeWidget (UI components)

Discovery Pipeline

1. ScriptScanner: Finds .js files in OpenRGB's SignalBridge/scripts/ configuration directory
2. ScriptMetadataExtractor: Creates minimal QuickJS runtimes to extract metadata
3. DiscoveryService: Orchestrates scanning, matches scripts to HID devices
4. ControllerRegistry: Creates controllers, registers with OpenRGB

JavaScript Runtime

• SignalRgbRuntimeFactory: Creates configured QuickJS runtime instances
• RuntimeBindings: Provides SignalRGB API (device.log(), device.read(), device.write())
• BuiltinModules: Resolves native C++ modules self-registered from src/runtime/signalrgb
• ModuleLoader: Loads user scripts and native built-ins as ES6 modules
• Scripts export functions: Name(), Initialize(), Render(), Shutdown()

Data Flow

OpenRGB Color Update
    ↓
SignalBridgeController::DeviceUpdateLEDs()
    ↓
FrameBuilder (convert colors)
    ↓
Script Render() function (via QuickJS)
    ↓
device.write() bindings
    ↓
HidBackend (hidapi)
    ↓
USB HID Device

Development

Project Structure

SignalBridgePlugin/
├── include/SignalBridge/    # Public plugin headers
├── src/
│   ├── domain/              # Core types (ControlParameters, DeviceRecords)
│   ├── runtime/             # QuickJS integration, bindings
│   │   └── signalrgb/       # Self-registering native @SignalRGB/* modules
│   ├── scanning/            # Script discovery, metadata extraction
│   ├── discovery/           # Device discovery orchestration
│   ├── openrgb/             # OpenRGB integration (controllers, mapping)
│   ├── hid/                 # HID device abstraction (hidapi wrapper)
│   ├── config/              # Configuration persistence
│   └── ui/                  # Qt widgets
├── tests/                   # Unit tests
└── deps/                    # Dependency submodules (CSerialPort, hidapi, hid-rp, OpenRGB, quickjs)

Code Conventions

• C++20 standard
• Qt naming conventions for Qt types (PascalCase: QWidget, QString)
• Snake_case for private members with trailing underscore (resource_manager_)
• QuickJS error handling: Check JS_IsException() after every runtime call
• Thread safety: Lock mutex_ when accessing shared controller state
• Memory management: std::shared_ptr for HidBackend, raw pointers for Qt parent-child

Running Tests

# All tests
cmake --build --preset debug --target SignalBridgeCoreTests
ctest --test-dir build/debug -C Debug --output-on-failure

# Specific test
./build/debug/Debug/SignalBridgeCoreTests.exe

Tests cover:

• HID device enumeration
• Topology mapping (SignalRGB channels/LEDs → OpenRGB zones/LEDs)
• Frame building and color conversion
• Configuration persistence
• Path normalization

Known Issues

• Windows Sandbox: May fail with error 1312. Use managed escalation if encountered.
• Script Compatibility: Not all third-party device scripts may work due to API differences
• Platform Support: Tested on Windows only; Linux/macOS have not been tested

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow existing code conventions
• Add tests for new functionality
• Update documentation as needed
• Ensure Debug and Release builds pass

License

SignalBridgePlugin source code is licensed under the GNU General Public License v2.0 or later. See LICENSE for details.

Third-party components, OpenRGB headers/source files, QuickJS, hidapi, and user-supplied device scripts remain under their own licenses or terms. This project license does not grant rights to redistribute SignalRGB software, SignalRGB paid content, or third-party scripts.

Acknowledgments

• OpenRGB: For the excellent RGB control platform and plugin API
• SignalRGB: For the public developer documentation and open-source device plugin ecosystem
• QuickJS: For the lightweight JavaScript engine
• hidapi: For cross-platform HID device access

References

• OpenRGB
• SignalRGB
• QuickJS
• hidapi

Support

For issues, questions, or suggestions:

• Open an issue on GitHub
• Check existing documentation in AGENTS.md

---

Note: SignalBridgePlugin is an independent, unofficial compatibility project. SignalRGB and OpenRGB are trademarks or project names of their respective owners.