Device Templates

Device templates are reusable blueprints for a type of device. A template explains what a device is expected to look like in Firmngin: its board type, connection options, data points, controls, and optional firmware rollout rules. Instead of setting up the same structure one device at a time, create one template and assign it to devices that follow the same pattern. [image:device template list with search, assignment filter, version badge, and device count]

​

What templates are for

Device templates are useful when you want many devices to behave consistently. They help your team keep setup, firmware, dashboard widgets, automations, and monitoring aligned around the same device definition.

​

When to use templates

Use device templates when:

• You sell or operate many devices with the same board or model.
• Devices should expose the same entity keys, units, icons, and value types.
• You want a clear contract between firmware, dashboard, automations, and monitoring.
• You need reusable firmware OTA rules for devices using the same template.
• You want device setup to be more consistent across a workspace.

Do not use a template just to rename one device. Templates are more useful when they describe a reusable device type.

​

Example uses

You can use device templates for:

• Temperature or cold-chain sensors that always report temperature, humidity, battery, and signal quality.
• Smart relays that expose relay state, active mode, and power usage.
• Vending or paid-service devices that share the same control and usage data.
• Environmental monitoring devices with the same sensor layout across many locations.
• Field devices that should receive firmware updates only during a selected maintenance window.

​

Template list

The Device Templates page shows the workspace template registry. From this page, you can:

• Search templates by name.
• Filter templates by whether they are assigned to devices.
• Open template details.
• Edit template identity.
• Delete a template when it is safe to remove.
• See the current version, revision, assigned device count, and last updated time.

[image:device template detail drawer showing overview, entity contract, copy key, and Arduino example]

​

What a template contains

The entity contract is the most important part. It tells firmware developers and dashboard users which values a device should send or receive.

​

Entities

Templates can include custom entities for telemetry, state, controls, or device-specific values. Each custom entity can define:

• Name and key.
• Entity type.
• Value type, such as boolean, enum, number, or string.
• GPIO pin and pin type when relevant.
• Default value, range, unit, prefix, suffix, and icon.
• Description for the people configuring or maintaining the device.

Selected protocols can also generate protocol entities automatically. Avoid creating a custom entity with the same key as a generated protocol entity.

​

Versions and edits

Creating a template starts with version 1. Editing the hardware or entity contract publishes a new immutable template version. This helps existing device definitions stay understandable over time. Simple identity edits, such as name or description, can be changed from the template list. Contract changes should be treated as a new version.

​

Device assignment

Templates are optional for devices. Creating a template does not automatically change existing devices. A device only uses a template after it is explicitly assigned. The template list can show assigned and unassigned templates, so you can quickly see which templates are already in use.

​

Firmware OTA policy

A template can include one firmware OTA policy. Supported options include:

• Latest compatible or fixed firmware selection.
• Schedule: immediate, user-defined datetime, or maintenance window (days, time window, timezone).
• Rollout strategy: all_at_once, canary, or staged_expand.
• Canary percent and expand stage percents for staged rollouts.
• max_devices_per_batch (wave size per execution step).
• approval_required for owner sign-off before OTA triggers.
• Safety gates: min_success_percent, min_observation_minutes, max_failure_percent, retry_limit.

See OTA policy for full field reference. Use OTA policy carefully. Start with conservative staged settings when a template is used by many devices.

​

Before publishing

Before creating or publishing a template version:

• Confirm the board and model are correct.
• Review selected protocols.
• Check each custom entity key and value type.
• Make sure enum options, numeric ranges, and default values are valid.
• Review firmware OTA policy timing if a policy is attached.
• Use a clear description so other workspace members know when to use the template.