Theodicean.UnfoldedCircle

ASP.NET SDK for hosting integration drivers for the Unfolded Circle Remotes.

Features

• mDNS broadcasting for discovery on remotes
• Configuration handling
• Event broadcasting
• Multiple entities in the same instance
• Climate Media Player, Remote, Select and Sensor entity support
• Strongly typed models
• NativeAOT and trimming friendly
• Can be used for applications installed on a remote or on a server

Limitations

• Button, Switch, Cover, Light, IR-Emitter and Voice Assistant are not yet supported

Requirements

• dotnet 10 SDK

Install

• Package (project using the generator):

  • Add a PackageReference to Theodicean.UnfoldedCircle.Server

  • Example csproj snippet:

    <ItemGroup>
      <PackageReference Include="Theodicean.UnfoldedCircle.Server" Version="x.y.z" />
    </ItemGroup>

Usage

Start by adding a driver.json file in the root of your server project. See here for documentation on the file format. You must make sure that the file is copied as part of the publishing process.

The integration requires that you implement a few abstract classes and register them in your Program.cs:

• UnfoldedCircle.Server.Configuration.ConfigurationService<TConfigurationItem> - Handles configuration for the integration.
• UnfoldedCircle.Server.WebSocket.UnfoldedCircleWebSocketHandler<TMediaPlayerCommandId, TConfigurationItem> - Handles requests and events from and to the remotes.

Implement the abstract methods to work with your entities and configuration. You can use unfoldedcircle-oppo as a reference implementation.

In your Program.cs, you can register the services like this:

builder.AddUnfoldedCircleServer<CustomWebSocketHandler, CustomConfigurationService, CustomConfigurationItem>();

...
app.UseUnfoldedCircleServer<CustomWebSocketHandler, CustomConfigurationItem>();

// Or if you want to use custom media player command ids (where CustomCommandId is an enum and must have the members defined in `MediaPlayerCommandId`):
builder.AddUnfoldedCircleServer<CustomWebSocketHandler, CustomCommandId, CustomConfigurationService, CustomConfigurationItem>();

...
app.UseUnfoldedCircleServer<CustomWebSocketHandler, CustomCommandId, CustomConfigurationItem>();

Customization

You can customize some of the behaviour of the integration by using the configureOptions overload when registering via AddUnfoldedCircleServer.

builder.AddUnfoldedCircleServer<CustomWebSocketHandler, CustomConfigurationService, CustomConfigurationItem>(options =>
{
    // Disable the prefixes for identifiers (e.g. "REMOTE:"). This is useful if you already have an integration driver and want to start using this SDK.
    DisableEntityIdPrefixing = true,

    // Override the default port (UC_INTEGRATION_HTTP_PORT environment variable takes precedence)
    ListeningPort = 4242,

    // Allows you to override the deserializer used for different message events.
    MessageEventDeserializeOverrides = new Dictionary<MessageEvent, JsonTypeInfo>
    {
        [MessageEvent.Connect] = CustomJsonSerializerContext.Default.ConnectEvent
    }
}

Note

If you're publishing with NativeAOT, you must add the following to your server's .csproj file to ensure the appsettings.json and driver.json are included in the output:

<PropertyGroup>
    <IncludeAllContentForSelfExtract>true</IncludeAllContentForSelfExtract>
    <ExcludeFromSingleFile>appsettings.json</ExcludeFromSingleFile>
    <ExcludeFromSingleFile>driver.json</ExcludeFromSingleFile>
</PropertyGroup>

Useful links

• Unfolded Circle Remotes
• Unfolded Circle Integration Driver Documentation
• Unfolded Circle Integration API Specification
• Unfolded Circle Entities Documentation