DMXCore.PluginSdk 1.8.3

DMXCore.PluginSdk

Contract SDK for building plugins for the DMX Core 100 lighting controller.

Getting started

1. Create a .NET class library targeting net10.0 and reference this package.
2. Set <PluginId> (plus Version and friends) in the project file — the build then generates manifest.json and a PluginBuildInfo constants class, so the plugin id and version live in exactly one place.
3. Implement IPlugin in a public class with a parameterless constructor.
4. dotnet pack — this produces a plugin package (.nupkg) for the plugin registry plus a bare .dmxplugin archive next to it for manual upload on the device's Plugins page.
5. Publish: dotnet nuget push <package>.nupkg --source https://api.nuget.org/v3/index.json --api-key <key>. Devices browse nuget.org for packages of type DmxCorePlugin and only offer versions whose DMXCore.PluginSdk dependency range the device's SDK satisfies, so publishing to nuget.org is publishing to every DMX Core 100.

<PropertyGroup>
  <PluginId>my-plugin</PluginId>
  <PluginDisplayName>My Plugin</PluginDisplayName>
  <Version>1.0.0</Version>
  <Authors>Me</Authors>
  
  <PackageId>MyCompany.DmxCorePlugin.MyPlugin</PackageId>
  <Description>What the plugin integrates with and what it does.</Description>
  <PackageProjectUrl>https://github.com/me/my-plugin</PackageProjectUrl>
  <PackageLicenseExpression>MIT</PackageLicenseExpression>
  <PackageReadmeFile>README.md</PackageReadmeFile>
  
  <PackageTags>my-device;requires-mqtt</PackageTags>
</PropertyGroup>

Package ids under DMXCore.* are reserved for first-party plugins; use your own prefix.

The requires-mqtt tag marks a plugin that talks to its devices over MQTT (via host.Mqtt). Only Balena appliances have a built-in broker; software installs (Windows, macOS, Linux) need an external MQTT server configured under Settings → MQTT. The device shows the tag as an "MQTT" badge in the plugin registry and warns before install when it has no MQTT connection, so users aren't surprised by a plugin that can't work yet.

public class MyPlugin : IPlugin
{
    public PluginInfo Info { get; } = new()
    {
        Id = PluginBuildInfo.Id,
        Name = PluginBuildInfo.Name,
        Version = PluginBuildInfo.Version,
        Settings =
        [
            new() { Key = "server-address", Label = "Server address", Type = PluginSettingType.String },
            new() { Key = "poll-interval", Label = "Poll interval (s)", Type = PluginSettingType.Integer, DefaultValue = "5" },
            new() { Key = "api-key", Label = "API key", Type = PluginSettingType.String, Secret = true },
        ],
    };

    public Task InitializeAsync(IPluginHost host, CancellationToken cancellationToken)
    {
        string? server = host.Settings.GetString("server-address");
        host.Logger.LogInformation("Connecting to {Server}", server);

        host.Mqtt.Subscribe("some/topic/#", async (msg, ct) =>
        {
            await host.Triggers.FireAsync("MY-TRIGGER");
        });

        return Task.CompletedTask;
    }

    public Task ShutdownAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }
}

Notes

• Plugins run with full trust inside the DMX Core 100 process and can only be installed by device administrators.
• Subscriptions take async handlers and return IDisposable; handler exceptions are logged by the host and do not terminate the subscription.
• host.Mdns discovers devices on the local network through the host's shared mDNS/DNS-SD browser, e.g. await host.Mdns.GetServicesAsync("_hue._tcp") — no need to bundle an mDNS stack in the plugin. Requires SDK contract 1.1; declare "minSdkVersion": "1.1" in the manifest if the plugin depends on it.
• host.Actions.RegisterProvider(...) makes the plugin an output action provider: its targets (e.g. Home Assistant scenes) become selectable on the device's Output Events page, and the resulting events can be fired from control surfaces, custom menus, input triggers, timelines and scripts. Requires SDK contract 1.7.
• Plugin fixture profiles can declare 16-bit channels: list the coarse function followed by its *Fine counterpart (Red, RedFine, ...); the render engine writes the high byte to the coarse channel and the low byte to the fine one. Requires SDK contract 1.8.
• The generated manifest's minSdkVersion defaults to the contract version of the SDK assembly the project compiles against (the assembly version's major.minor — not the NuGet package version, which is just a publish counter). Reference the oldest SDK package you support and the declared floor is correct by construction; set <PluginMinSdkVersion> to override. The packed plugin package carries the same floor as its DMXCore.PluginSdk dependency range, [<floor>, <next major>.0).
• The plugin package contains only content/plugin.dmxplugin (the publish output zipped) — a plugin is never referenced as a library. Set <PackDmxCorePlugin>false</PackDmxCorePlugin> to pack an ordinary library package instead.
• Plugin changes are applied by the Reload action on the device's Plugins page (or a device restart).