Concepts

Settings

Settings are the per-instance configuration of a Komod. A plain record that you give as the type parameter of KomodBase<TSettings>.

public sealed record ThermometerSettings
{
    [Range(-50, 150)]
    public double BaseCelsius { get; init; } = 21;

    [Range(0, 50)]
    public double AmplitudeCelsius { get; init; } = 4;

    [Range(1, 3600)]
    public double PeriodSeconds { get; init; } = 60;

    [Range(0, 5)]
    public double NoiseCelsius { get; init; } = 0.2;

    [Range(0.1, 20)]
    public double RateHz { get; init; } = 2;
}

Rules

• The record can be created with new(); the default values are in the properties. A new instance starts with them.
• KOFA validates the data annotations ([Range], [StringLength], [Required] etc.) before saving. For rules across fields implement IValidatableObject on the record.
• [Description] and the XML documentation appear in the form's help.
• Storage is JSON (camelCase), so the property names stay in the stored graph: do not rename fields of a released Komod, because the old graph's value would be lost. A new field should always get a default value.

The form

The graph editor builds a form from the settings automatically (number, switch, text, enum; other fields as JSON). A custom editor can also be written: see User interface (UI).

Change at run time

When a setting is modified, KOFA calls:

protected override Task<bool> OnSettingsChangedAsync(TSettings oldSettings, TSettings newSettings)

Settings already holds the new value.

• true: you applied it (for example the loop re-reads it every round) → the instance keeps running.
• false (the default): KOFA restarts the instance, which starts with the new setting.

For a Komod that uses hardware, a restart is the safer choice when the change needs reconfiguration (for example a different I2C address).

Settings from the UI

The browser part reads and saves the settings with IKomodClientContext.GetSettingsAsync / SaveSettingsAsync; the save is written into the active graph as well. Example: the thermostat's tile.

Deployment-dependent values

If a value belongs to the machine, not to the graph (for example a Bluetooth name), mark it with [DeploymentSetting]: Deployment setting.