Configuration & Templates

Template inheritance, binding types, and the effective configuration model

The Template Model

Managing hundreds of identical devices (e.g., 200 LG displays across a campus) would be impossible if each device needed full individual configuration. The template model solves this.

Template

A template defines the default shape for a device type:

Property definitions (name, type, default value, polling interval)
Trait configurations (power control, input switching)
Communication settings (protocol, port, timeouts)
Plugin assignment

Instance

An instance represents a specific physical device. It inherits from a template and overrides only what's unique:

IP address or serial port
Room assignment
Custom display name
Site-specific thresholds

Effective Configuration

At runtime, the agent computes the effective configuration by merging template defaults with instance overrides:

Effective Config = Template Defaults ← Instance Overrides

Binding Types

Each field in a template declares how it can be overridden:

Binding Type	Template	Instance	Use Case
`TemplateOnly`	Defines value	Cannot change	Protocol type, plugin assignment
`InstanceRequired`	May have default	Must provide	IP address, serial port
`InstanceOptional`	Has default	Can override	Display name, polling interval

Example

Template: "LG Commercial Display"
  protocol: Telnet          (TemplateOnly)
  port: 9761                (InstanceOptional, default: 9761)
  ipAddress: ""             (InstanceRequired)
  pollingInterval: 30s      (InstanceOptional, default: 30s)
  displayName: ""           (InstanceOptional)

Instance: "Boardroom A - Left Display"
  ipAddress: "192.168.1.100"   ← Required override
  displayName: "Left Display"  ← Optional override
  port: 9761                   ← Inherited from template
  pollingInterval: 30s         ← Inherited from template

Template Versioning

When a template is updated:

All instances using that template are notified
The agent recomputes effective configuration
Only changed properties trigger device reconfiguration
TemplateOnly changes apply immediately
InstanceRequired/InstanceOptional fields keep their instance values

This allows fleet-wide updates (e.g., changing a polling interval for all devices of a type) while preserving per-device customizations.

Headless Agent Design

Plugin Isolation