Device Templates Reference

This reference covers the technical specification of the device template Excel file format used for import and export in Overvis Cloud. For a general overview of how templates work, see the Device Templates guide.

File format

Device templates use the Microsoft Excel .xlsx format. Only .xlsx is accepted — older .xls files, CSV, and other formats are not supported.

A template workbook contains two required sheets and two optional sheets. The sheet names are exact and case-sensitive — any unrecognized sheet name causes an import error.

Sheet	Required	Purpose
Info	Yes	Device metadata and communication settings
Params	Yes	Parameter definitions (one row per parameter)
Visualization	No	Embeddable device visualization (HTML/JS source)
Alerts	No	Alert template definitions in YAML format

Info sheet

The Info sheet stores device-level metadata and communication defaults. Values are read from fixed cell positions (not by column headers).

Row	Column A (1) — label	Column B (2) — value	Required
1	Manufacturer:	Manufacturer name (up to 200 characters)	No
2	Model:	Template name / device model (1–200 characters)	Yes
3	Device Version:	Version string (up to 50 characters)	No
4	Category:	Category text (up to 200 characters)	No
5	(empty)
6	Read Group Size:	Integer 1–255	Yes
7	Write Function:	normal, always-6, or always-16	Yes

Description is stored in column D (4), starting from row 2. If the description is longer than 32,000 characters, it is split across multiple cells in that column (row 2, row 3, etc.). On import, all cells in column D below row 1 are concatenated.

Field details

Template name (row 2) is the primary identifier. Together with manufacturer and version, it forms a unique identity within a scope (global or per-organization). Importing a template with the same name+manufacturer+version as an existing one in your organization replaces the existing template.

Read group size controls how many consecutive Modbus registers Overvis combines into a single read request. A value of 1 reads each parameter individually. Higher values (e.g. 16) batch adjacent registers into fewer requests, which speeds up polling but requires the device to support multi-register reads across that range.

Write function determines which Modbus function code is used when writing parameter values:

Value	Meaning
normal	Overvis chooses automatically — function 06 (Write Single Register) for single-register values, function 16 (Write Multiple Registers) for multi-register values.
always-6	Always use function 06, regardless of value size.
always-16	Always use function 16, regardless of value size.

Params sheet

The Params sheet defines all device parameters. Row 1 is the header row; data starts from row 2. Columns are matched by header name (not by position), so column order does not matter.

Required columns

Every parameter row must provide values for these columns. Missing values cause an import error for that row.

Column header	Field	Description
Name	name	Parameter display name (1–200 characters).
Address	address	Modbus register address, integer 0–65535.
Type	valueType	Data type identifier. See Value types.
Register Kind	registerKind	Register type: holding, input, coil, or discrete-input.
Is Tracked	isTracked	1 to store historical readings, 0 to skip.
Is Programmable	isProgrammable	1 if the parameter can be written from the UI, 0 if read-only.
Read As Group	readAsGroup	1 to include in grouped reads, 0 to read individually.
Widget	autoAddWidget	1 to create a dashboard widget when the template is applied, 0 to skip.

Optional columns

Column header	Field	Description
Category	category	Grouping label (up to 200 characters), e.g. Inputs, Configuration, Status.
Mnemonic	label	Short identifier (up to 20 characters), e.g. T1, P.out. The column can also be named Label.
Description	description	Longer explanation of what this parameter represents.
Units	unitName	Measurement units (up to 20 characters), e.g. °C, kW, bar, %.
Multiplier	multiplier	Scaling factor applied to the raw register value. displayed = raw × multiplier + shift. A value of 1 is treated as “no multiplier.” Not allowed for bit, string, IP address, and MAC address types.
Shift	shift	Offset added after multiplying. A value of 0 is treated as “no shift.” Same type restrictions as multiplier.
Decimal Precision	decimalPrecision	Number of decimal places to display (integer 0–20).
Min	minValue	Minimum expected value (for display and validation).
Max	maxValue	Maximum expected value (for display and validation).
Bit Position	bitPosition	For bit and bits types: which bit within the register to start from (0–15). Required for bit and bits, not allowed for other types.
Bits Num	bitsAmount	For bits type only: how many consecutive bits to extract (1–16). Required for bits, not allowed for other types including bit.
Represent As	intrepr	Enumeration mappings or a system bit-representation code. See Enumerations and representations.

Translation columns

Parameter text fields can be translated into additional languages. Add translation columns by appending a space and a language code to the base column name:

Base column	Translation column examples
Name	Name uk, Name pl, Name ru
Category	Category uk, Category pl, Category ru
Description	Description uk, Description pl, Description ru
Units	Units uk, Units pl, Units ru

Supported language codes: en, uk (Ukrainian), pl (Polish), ru (Russian). English is the base language — the main column values are always English, and en translation columns are not needed.

A translation column requires the corresponding English column to have a non-empty value in the same row. You cannot translate an empty field.

Enumeration translations use a separate column format — see Enumeration translations.

Value types

The Type column specifies how raw register bytes are interpreted. The value must exactly match one of the identifiers below.

Integer types

Type	Size	Description
u8	1 register (low byte)	Unsigned 8-bit integer (0–255)
i8	1 register (low byte)	Signed 8-bit integer (-128–127)
u16-be	1 register	Unsigned 16-bit, big-endian
u16-le	1 register	Unsigned 16-bit, little-endian (byte-swapped)
i16-be	1 register	Signed 16-bit, big-endian
i16-le	1 register	Signed 16-bit, little-endian (byte-swapped)
u32-be	2 registers	Unsigned 32-bit, big-endian
u32-byte-le	2 registers	Unsigned 32-bit, byte-swapped
u32-word-le	2 registers	Unsigned 32-bit, word-swapped
i32-be	2 registers	Signed 32-bit, big-endian
i32-byte-le	2 registers	Signed 32-bit, byte-swapped
i32-word-le	2 registers	Signed 32-bit, word-swapped
u64-be	4 registers	Unsigned 64-bit, big-endian
u64-byte-le	4 registers	Unsigned 64-bit, byte-swapped
u64-word-le	4 registers	Unsigned 64-bit, word-swapped
i64-be	4 registers	Signed 64-bit, big-endian
i64-byte-le	4 registers	Signed 64-bit, byte-swapped
i64-word-le	4 registers	Signed 64-bit, word-swapped
u48-be	3 registers	Unsigned 48-bit, big-endian
u24-zero-sep	2 registers	Unsigned 24-bit with zero separator
u16-bcd	1 register	Unsigned 16-bit, BCD-encoded

Floating-point types

Type	Size	Description
float	2 registers	IEEE 754 single-precision (32-bit), big-endian
float-byte-le	2 registers	Single-precision, byte-swapped
float-word-le	2 registers	Single-precision, word-swapped
double	4 registers	IEEE 754 double-precision (64-bit), big-endian
double-byte-le	4 registers	Double-precision, byte-swapped
double-word-le	4 registers	Double-precision, word-swapped

Bit types

Type	Description
bit	A single bit within a register. Requires Bit Position (0–15). Bits Num must not be set.
bits	Multiple consecutive bits within a register, read as an integer. Requires both Bit Position and Bits Num.

For coil and discrete-input register kinds, the type must be bit.

String and special types

Type	Description
byte-str	ASCII string, one character per byte (two characters per register)
word-str	ASCII string, one character per register (low byte)
byte-ipaddr	IPv4 address stored as 4 bytes across 2 registers
word-ipaddr	IPv4 address stored as 4 registers (one octet per register)
byte-macaddr	MAC address stored as 6 bytes across 3 registers
word-macaddr	MAC address stored as 6 registers (one octet per register)

Enumeration type

Type	Description
enum	Numeric value mapped to human-readable labels via the Represent As column. See Enumerations and representations.

Byte order conventions

For multi-register types, the suffix indicates byte order:

• -be (or no suffix for float/double) — big-endian: most significant byte first. This is the standard Modbus byte order and the most common.
• -byte-le — byte-swapped (little-endian bytes): bytes within each register are reversed. Some devices use this non-standard order.
• -word-le — word-swapped: the register order is reversed (least significant register first), but bytes within each register remain big-endian.

Multiplier and shift restrictions

The following types do not support multiplier or shift values: bit, byte-str, word-str, byte-ipaddr, word-ipaddr, byte-macaddr, word-macaddr. Setting a multiplier or shift on these types causes a validation error.

Enumerations and representations

The Represent As column serves two purposes depending on the value type.

For enum type: enumeration mappings

When the Type is enum, the Represent As cell defines mappings from numeric values to display text. The cell must contain multiple lines, each with fields separated by semicolons (;):

<value>;<display text>
<value>;<display text>;<description>

The description is optional. Example cell content (each line in the same cell):

0;Stopped
1;Running
2;Error;Critical fault detected
3;Maintenance;Scheduled service mode

Rules:

• English mappings are required — the base Represent As column must be filled.
• Each numeric value must be unique within the English mappings.
• At least one mapping is required.

Enumeration translations

To provide enumeration mappings in other languages, add columns named Represent As XX where XX is the language code in uppercase:

• Represent As UK — Ukrainian
• Represent As PL — Polish
• Represent As RU — Russian

Each translation column uses the same semicolon-and-newline format as the base column. The numeric values must match the English values exactly — the same set of values, in any order. Example Represent As UK cell:

0;Зупинено
1;Працює
2;Помилка;Критична несправність
3;Обслуговування;Планове сервісне обслуговування

For bit type: system representation codes

When the Type is bit, the Represent As cell can contain a system representation code — a short text identifier referencing a built-in bit representation (e.g. showing On/Off or Open/Closed instead of 1/0).

The value must reference an existing system bit representation code. If the code is not recognized, import fails with an error listing the available codes.

This is distinct from enum mappings: the cell contains a plain string (no semicolons or newlines), and it is only valid for bit type parameters.

Visualization sheet

The optional Visualization sheet contains the HTML/JavaScript source code for an embeddable device visualization. Row 1 is a header; the actual content starts from row 2 in column A (1).

Long content is split across multiple cells (row 2, 3, etc.) at 32,000-character boundaries and concatenated on import.

When the template is applied to a device, the visualization source can contain {{device_id}} and {{network_id}} placeholders, which Overvis replaces with the actual IDs.

Alerts sheet

The optional Alerts sheet contains alert template definitions in YAML format. Row 1 is a header; the YAML content starts from row 2 in column A (1).

Like the Visualization sheet, long YAML is split across cells at 32,000-character boundaries and concatenated on import.

For the complete alert template YAML syntax, see the Alerts Templates Reference.

Alert templates can also be edited directly in the Overvis web interface through the template settings page, without modifying the Excel file.

Validation rules

Overvis validates the template during import at multiple levels. If any validation fails, the template is not imported, and errors are reported with their sheet name, row, and cell reference.

Structural validation

• The workbook must contain sheets named exactly Info and Params. Any other sheet name besides Visualization and Alerts is rejected.
• The Info sheet values must be in the correct cell positions.
• The Params sheet must have a header row with recognized column names.

Info validation

• Model (template name) is required and must be 1–200 characters.
• Read Group Size is required and must be an integer between 1 and 255.
• Write Function is required and must be exactly normal, always-6, or always-16.
• Manufacturer must be at most 200 characters; version at most 50; category at most 200.

Parameter validation

Each parameter row is validated independently. A row with errors is skipped, but other rows are still validated (all errors are collected and reported).

• Name is required (1–200 characters).
• Address must be an integer between 0 and 65535.
• Type must be one of the recognized value type identifiers.
• Register Kind must be holding, input, coil, or discrete-input.
• Is Tracked, Is Programmable, Read As Group, and Widget must be 0 or 1.
• Multiplier and Shift must be numbers (if provided).

Consistency validation

After individual field validation, business rules are checked:

• coil and discrete-input register kinds require value type bit.
• bit type requires Bit Position (0–15) and must not have Bits Num.
• bits type requires both Bit Position (0–15) and Bits Num (1–16).
• Other types must not have Bit Position or Bits Num.
• Multiplier and shift are not allowed for bit, string, IP address, and MAC address types.
• System bit representation codes (in Represent As) are only allowed for bit type.

Enumeration validation

• enum type parameters must have at least one mapping in the Represent As column.
• English mappings are required. The base Represent As column must be populated.
• Numeric values in the English mappings must be unique.
• Translation columns (e.g. Represent As UK) must contain the same set of numeric values as the English column. Missing or extra values cause an error.

Alert YAML validation

If the Alerts sheet is present, its YAML is parsed and validated:

• The top level must be a YAML array.
• Each alert must have name, level, conditions, and actions (see Alerts Templates Reference for the full structure).
• Each condition’s param reference must match a parameter defined in the Params sheet (by address and register kind).

Import behavior

• Templates are always imported into the current organization (never directly to the global library). To make a template global, use the separate “Make global” action in the web interface.
• If a template with the same name, version, and manufacturer already exists in the organization, the existing template and all its parameters, translations, and enumeration definitions are replaced with the imported data.
• Import is atomic: if any validation error occurs, no changes are made.

Export format

Exporting a template produces an .xlsx file with the same structure described above. The exported file can be edited in any spreadsheet application and re-imported.

The export includes:

• Info sheet with all device metadata.
• Params sheet with all parameters, including any translation columns that have data.
• Visualization sheet (only if the template has a device visualization).
• Alerts sheet (only if the template has alert YAML).

Exported files use frozen header rows and auto-filters on the Params sheet for easier navigation.

Related documentation

• Device Templates guide — how to browse, create, apply, and manage templates.
• Alerts Templates Reference — complete YAML syntax for alert templates.
• Networks, Devices & Parameters — how parameters, tracking, and device settings work.