TMRemote SDK

REST API

Control TMRemote via HTTP from any device on your network.

Endpoints

Example: Run a Scenario

curl -X POST http://localhost:8080/api/scenarios/Gaming/run

Example: Route Matrix

curl -X POST http://localhost:8080/api/matrix/route \
  -H "Content-Type: application/json" \
  -d '{"input": 1, "output": 3}'

Plugin Development

Create plugins to add new devices, automation, and API endpoints.

Quick Start

1. Create a class implementing IDevicePlugin
2. Add your plugin DLL to the Plugins folder
3. Enable via Settings → Plugins tab

Minimal Plugin

public class MyPlugin : IDevicePlugin
{
    public string PluginId => "my-plugin";
    public string DisplayName => "My Custom Plugin";
    public Version Version => new Version(1, 0, 0);
    public string Description => "My plugin description";
    public string Author => "Your Name";
    public int MinHostVersion => 1;
    public bool IsEnabled { get; set; }
    public IEnumerable<IDevice> ConnectedDevices => Array.Empty<IDevice>();

    public Task InitializeAsync(IPluginHost host)
    {
        // Register custom API route (path, HTTP method, handler)
        host.RegisterApiRoute("myplugin/status", "GET", async req =>
            new ApiResponse { Success = true, Data = "OK" });

        // Use logger
        host.Logger.Info("Plugin initialized");

        return Task.CompletedTask;
    }

    // Required interface members
    public Task ShutdownAsync(PluginCloseReason reason) => Task.CompletedTask;
    public void ShowConfigDialog(IntPtr parentWindow) { }
    public Task<IEnumerable<IDiscoveredDevice>> DiscoverDevicesAsync()
        => Task.FromResult<IEnumerable<IDiscoveredDevice>>(Array.Empty<IDiscoveredDevice>());
    public Task<IDevice> ConnectDeviceAsync(DeviceConfig config) => Task.FromResult<IDevice>(null);
    public IEnumerable<IActionDefinition> GetActionDefinitions() => Array.Empty<IActionDefinition>();
    public UserControl CreateSettingsPanel() => null;
    public PluginRequirements GetRequirements() => new PluginRequirements();
    public void Dispose() { }
}

Key IPluginHost Services

Device Interfaces

Plugins expose devices through interfaces. Use IMatrixDevice for matrix switchers with labeled I/O ports.

IDevice (Base Interface)

IMatrixDevice (extends IDevice)

For matrix switching devices with input/output ports. Labels are used in routing grid tooltips.

Example: Matrix Device

public class MyMatrixDevice : IMatrixDevice
{
    public string DeviceId => _config.DeviceId;
    public string DisplayName => _config.DisplayName;
    public string PluginId => "my-matrix";
    public string Address => _config.IpAddress;
    public bool IsConnected => _client.IsConnected;

    // IMatrixDevice - labels shown in UI tooltips
    public string[] InputLabels => _config.InputLabels;
    public string[] OutputLabels => _config.OutputLabels;

    // ... connection methods, events
}

Services Reference

Core service interfaces for advanced integration.

• IMatrixService - HDMI matrix control
• IProfileService - Profiles and scenarios
• IPluginService - Plugin management

IMatrixService

Interface for HDMI matrix control operations.

Connection

Routing

Power & Audio

CEC Commands

Presets

Events

Example Usage

// Connect and route
await matrix.ConnectAsync("192.168.1.100");

// Route input 1 to outputs 1-4
await matrix.SetAllRoutesAsync(new[] { 1, 1, 1, 1, 2, 2, 3, 4 });

// Power on all TVs
for (int i = 1; i <= 8; i++)
    await matrix.CecPowerOnOutputAsync(i);

// Set external audio to input 3
await matrix.SetExternalAudioAsync(3);

IProfileService

Interface for monitor profiles and scenarios.

Monitor Profiles

Scenarios

ScenarioInfo Properties

Example Usage

// Execute a scenario with progress
var progress = new Progress<ScenarioProgress>(p => {
    Console.WriteLine($"[{p.StepNumber}/{p.TotalSteps}] {p.CurrentStep}");
});

var result = await profiles.ExecuteScenarioAsync("Gaming", progress);

if (result.Success)
    Console.WriteLine($"Completed in {result.Duration.TotalSeconds}s");
else
    Console.WriteLine($"Failed: {result.Message}");

IPluginService

Interface for plugin management and API routing.

Plugin Information

Plugin State

Plugin Configuration

API Routing

Plugin Development

Create plugins by implementing the IDevicePlugin interface.

IDevicePlugin Interface

public interface IDevicePlugin : IDisposable
{
    // Identity
    string PluginId { get; }
    string DisplayName { get; }
    string Author { get; }
    Version Version { get; }
    string Description { get; }
    int MinHostVersion { get; }

    // Lifecycle
    Task InitializeAsync(IPluginHost host);
    Task ShutdownAsync(PluginCloseReason reason);
    void ShowConfigDialog(IntPtr parentWindow);
    bool IsEnabled { get; set; }

    // Device Management
    Task<IEnumerable<IDiscoveredDevice>> DiscoverDevicesAsync();
    Task<IDevice> ConnectDeviceAsync(DeviceConfig config);
    IEnumerable<IDevice> ConnectedDevices { get; }

    // Actions
    IEnumerable<IActionDefinition> GetActionDefinitions();

    // UI
    UserControl CreateSettingsPanel();

    // Requirements
    PluginRequirements GetRequirements();
}

IPluginHost Interface

The IPluginHost provides access to TMRemote services:

public interface IPluginHost
{
    // Logging
    IPluginLogger Logger { get; }

    // Configuration & Storage
    string GetPluginDataPath(string pluginId);
    T LoadSettings<T>(string pluginId) where T : class, new();
    void SaveSettings<T>(string pluginId, T settings) where T : class;

    // UI Integration
    void ShowNotification(string title, string message, NotificationIcon icon);
    void RequestSettingsRefresh();
    void NavigateToSettingsTab(string tabName);

    // Firewall Management
    bool RequestFirewallAccess(PortRequirement port);
    bool RevokeFirewallAccess(PortRequirement port);
    bool IsFirewallPortOpen(int port);

    // System Enumerations
    IReadOnlyList<DisplayInfo> GetDisplays();
    IReadOnlyList<AudioEndpointInfo> GetAudioEndpoints(AudioFlow flow);
    IReadOnlyList<string> GetMonitorProfiles();
    IReadOnlyList<string> GetScenarios();
    IReadOnlyList<PluginInfo> GetPlugins();

    // Device Enumeration (Cross-Plugin)
    IReadOnlyList<IDevice> GetAllDevices();
    IReadOnlyList<IDevice> GetDevicesByPlugin(string pluginId);
    IReadOnlyList<T> GetDevicesByType<T>() where T : class, IDevice;
    void RegisterDevice(IDevice device);
    void UnregisterDevice(string deviceId);
    IDevice GetDevice(string deviceId);

    // REST API Extension
    void RegisterApiRoute(string path, string method, Func<ApiRequest, Task<ApiResponse>> handler);
    void UnregisterApiRoute(string path, string method);

    // Event Subscription
    void Subscribe<TEvent>(Action<TEvent> handler) where TEvent : IPluginEvent;
    void Unsubscribe<TEvent>(Action<TEvent> handler) where TEvent : IPluginEvent;
    void Publish<TEvent>(TEvent evt) where TEvent : IPluginEvent;

    // Hotkey Registration
    void RegisterHotkey(string hotkeyId, string displayName, Action callback);
    void UnregisterHotkey(string hotkeyId);

    // Services
    T GetService<T>() where T : class;
    INavigationPanelService NavigationPanels { get; }

    // Application Info
    Version HostVersion { get; }
    string ApplicationPath { get; }
    int InterfaceVersion { get; }
    int ApiRevision { get; }
}

Example Plugin

public class MyPlugin : IDevicePlugin
{
    private IPluginHost _host;

    public string PluginId => "my-plugin";
    public string DisplayName => "My Custom Plugin";
    public string Description => "Does amazing things";
    public Version Version => new Version(1, 0, 0);
    public string Author => "Your Name";
    public int MinHostVersion => 1;
    public bool IsEnabled { get; set; }

    public IEnumerable<IDevice> ConnectedDevices => _devices;
    private List<IDevice> _devices = new();

    public async Task InitializeAsync(IPluginHost host)
    {
        _host = host;
        _host.Logger.Info("MyPlugin initializing...");

        // Register API route (requires path AND HTTP method)
        _host.RegisterApiRoute("myplugin/status", "GET", HandleStatusRequest);

        // Subscribe to events
        _host.Subscribe<RoutingChangedEvent>(OnRoutingChanged);
    }

    private Task<ApiResponse> HandleStatusRequest(ApiRequest request)
    {
        return Task.FromResult(new ApiResponse
        {
            Success = true,
            Data = new { Status = "OK", Version = Version.ToString() }
        });
    }

    private void OnRoutingChanged(RoutingChangedEvent e)
    {
        _host.Logger.Info($"Routing changed: {string.Join(",", e.Routes)}");
    }

    public Task ShutdownAsync(PluginCloseReason reason)
    {
        _host.Unsubscribe<RoutingChangedEvent>(OnRoutingChanged);
        return Task.CompletedTask;
    }

    public void ShowConfigDialog(IntPtr parentWindow) { }
    public Task<IEnumerable<IDiscoveredDevice>> DiscoverDevicesAsync()
        => Task.FromResult<IEnumerable<IDiscoveredDevice>>(Array.Empty<IDiscoveredDevice>());
    public Task<IDevice> ConnectDeviceAsync(DeviceConfig config) => Task.FromResult<IDevice>(null);
    public IEnumerable<IActionDefinition> GetActionDefinitions() => Array.Empty<IActionDefinition>();
    public UserControl CreateSettingsPanel() => null;
    public PluginRequirements GetRequirements() => new PluginRequirements();
    public void Dispose() { }
}

Navigation Panel Provider

Plugins that want to provide custom control panels implement INavigationPanelProvider:

public interface INavigationPanelProvider
{
    // Synchronous - returns immediately with current state (may be stale)
    NavigationPanelDefinition GetPanelDefinition(IDevice device = null);

    // Asynchronous - waits for device state to load before returning
    Task<NavigationPanelDefinition> GetPanelDefinitionAsync(IDevice device = null);

    // Execute control actions
    Task<bool> ExecuteControlAsync(IDevice device, string controlId);
    Task<bool> ExecuteControlAsync(IDevice device, string controlId, object value);

    // Get current control state
    Task<object> GetControlStateAsync(IDevice device, string controlId);
}

Sync vs Async Panel Definition

Why Async Matters

Device state (patterns, controls, volume, etc.) is fetched asynchronously. If you build the panel before state is loaded, it will show stale or empty data. GetPanelDefinitionAsync ensures state is loaded first:

public async Task<NavigationPanelDefinition> GetPanelDefinitionAsync(IDevice device = null)
{
    var myDevice = device as MyDevice ?? _connectedDevices.FirstOrDefault();

    // Load current state before building panel
    if (myDevice != null && myDevice.IsConnected)
    {
        await myDevice.RefreshStateAsync();  // Fetch current state from device
    }

    // Now build panel with up-to-date state
    return BuildPanelDefinition(myDevice);
}

Panel Definition Structure

var panel = new NavigationPanelDefinition
{
    PanelId = "my-panel",
    DisplayName = "My Device",
    PluginId = PluginId,
    PollIntervalMs = 5000  // Refresh state every 5 seconds
};

// Add control sections
var section = new ControlSection
{
    SectionId = "controls",
    DisplayName = "Device Controls",
    Layout = SectionLayout.Row
};

section.Controls.Add(new ControlDefinition
{
    ControlId = "power",
    DisplayName = "Power",
    Type = ControlType.Toggle,
    StandardControl = StandardControl.Power
});

panel.Sections.Add(section);

CLI Integration

The ServicesCLI class provides programmatic CLI access:

// Create CLI with services
var cli = new ServicesCLI(
    matrix: AppServices.Instance.Matrix,
    profiles: AppServices.Instance.Profiles,
    plugins: AppServices.Instance.Plugins
);

// Execute commands
int exitCode = await cli.ExecuteAsync(new[] { "route", "1", "3" });
await cli.ExecuteAsync(new[] { "scenario", "run", "Gaming" });
await cli.ExecuteAsync(new[] { "plugins" });

Available Commands

See Also

• TMRemote README - Main documentation
• TMRemote CLI Reference - Command-line usage
• OREI Matrix API - HTTP API reference
• Matrix HTTP API Reference - OREI BK-808 direct control