Parameter sources

A parameter’s source says where its bytes come from and whether they can be written. Its value type then turns those bytes into the parameter’s value. The source is a JSON object; kind selects one of three sources:

kind	Bytes come from	Writable?
const	A small value stored in the workspace under a key	With allowWrite: true
calc	A formula over other parameters’ values	Never
modbus-tcp	Coils or registers of a device, through an endpoint	Holding registers and coils, per writeFunction

Devices on a Modbus RTU (RS-485) bus are reached through a gateway that speaks Modbus TCP, such as an MC252: the parameter uses a modbus-tcp source on the gateway’s endpoint, with the device’s unit ID. Which source suits which need is explained in choosing a source.

Saving the setup rejects a source that refers to something missing or that does not fit, as described for each kind below. Device errors and formula failures that depend on the values appear only when the parameter is read or written.

const

{ "kind": "const", "key": "line-a.setpoint", "allowWrite": true }

Field	Rules
key	1–200 characters, naming the stored value in the workspace
allowWrite	false makes the parameter read-only: writes fail with not_writable

• The stored value is at most 1,024 bytes. Until something is written, it is empty.
• The parameter’s value type decodes the stored bytes, and a write stores the bytes it encodes.
• Several parameters can share a key; they then read and write the same stored value.
• The stored value is live data, not setup: hmi pull and hmi push sync the key, not the value.

calc

{
  "kind": "calc",
  "inputParamIds": [
    "11111111-1111-1111-1111-111111111111",
    "22222222-2222-2222-2222-222222222222"
  ],
  "formula": "#1 * 0.1 + #2",
  "returnFormat": "float"
}

Field	Rules
inputParamIds	1–32 other parameters; their order defines #1 … #n
formula	1–2,000 characters in the formula language, such as "#1 * 0.1 + #2"
returnFormat	"int": a signed 32-bit integer; "float": a 64-bit IEEE 754 float, both big-endian

• Each read reads the inputs, evaluates the formula, and packs the result into bytes that this parameter’s value type decodes. The value types that fit each returnFormat are in source bytes and value types.
• A calc parameter is never writable: writes fail with not_writable.
• Saving the setup, hmi push, and hmi check reject a formula that does not compile or refers to an input it does not have, such as #3 with two inputs (parameter_formula_invalid). They also reject a parameter that is its own input (parameter_input_self_reference), inputs that loop back to the parameter, even indirectly (parameter_input_cycle), and missing inputs (parameter_input_not_found).
• A read fails when an input is disabled (param_disabled), when the formula fails on the values, such as a division by zero (formula_error), or when the chain of calc inputs is too deep (depth_exceeded).

modbus-tcp

{
  "kind": "modbus-tcp",
  "endpointId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "unitId": 1,
  "table": "holding-register",
  "addresses": [100, 101],
  "writeFunction": "multi-or-single-write"
}

Common fields

Field	Rules
endpointId	An endpoint of the workspace
unitId	Modbus unit ID, 0–255
table	coil, discrete-input, holding-register or input-register
addresses	1–64 addresses, each 0–65535; their number is the count
writeFunction	Required for coil and holding-register; absent for the read-only tables
read	Optional read settings

addresses are the zero-based addresses sent on the wire. Many device manuals number registers from 1, or in the “40001” style, so a holding register documented as 40001 is often address 0; the offset depends on the vendor.

The value type reads the bytes of the addresses in the order listed. Each register supplies two bytes, high byte first; each coil or discrete input supplies one byte, 0x00 when off or 0xff when on. To translate a manual’s word and byte order into value type settings, see byte relation.

Saving the setup, applying a template, hmi push, and hmi check reject a parameter whose addresses supply fewer bytes than its value type needs (modbus_source_too_short, with the available and required bytes). A float32 needs at least two registers and a float64 four; a byte filter that keeps one byte per register doubles that. More addresses than needed, and gaps in the list, are allowed. Strings, big integers, and ISO date strings have no minimum. An existing parameter with too few addresses does not block other saves, but saving that parameter fails until it is corrected; hmi check reports every such parameter, and hmi push refuses while any remains.

Saving also checks that the endpoint exists (parameter_endpoint_not_found). An endpoint that parameters still read from cannot be deleted (endpoint_in_use). While the endpoint is disconnected, reads and writes fail with endpoint_disconnected; the setup is unchanged.

Write functions

writeFunction	Writes
none	Nothing: the parameter is read-only
single-write	One single-coil or single-register request per address
multi-or-single-write	One multiple-write request for contiguous addresses, otherwise single writes. When the device answers Modbus exception 1 or 2 (illegal function or address), it writes the addresses one by one
always-multi-write	One multiple-write request; addresses with gaps fail with sparse_write_unsupported

In a parameter template, writeFunction may be left out on coil and holding-register: applying the template sets multi-or-single-write. Templates set it only for another policy, such as single-write for a device that accepts only single-register writes.

Optional read settings

Overvis combines reads of neighboring addresses of the same endpoint, unit ID and table into one request. read tunes this for one parameter; every field is optional. Setup has no controls for it: set it in a template, a pulled workspace, or through the API. Editing the parameter in Setup keeps it.

Setting	Default	Meaning
allowMultiRead	true	false keeps this parameter out of combined reads
maxQuantityPerRequest	50 registers, or 500 coils or discrete inputs	The most addresses in one request, at most 125 registers or 2,000 coils
atomic	true with several addresses, otherwise false	One request must cover all the addresses, or the read fails with atomic_unsatisfiable
maxMergeGap	0	How many unread addresses may lie between combined spans (0–2,000)

Keep atomic: true when a value split across registers, such as a float, must not be read in two halves.

Setup form

Kind	Setup controls
const	Key, allow-write switch
calc	Ordered input parameters (#1, #2, …), formula, result type
modbus-tcp	Endpoint, unit ID, table, addresses, write function (for writable tables)

Changing the kind in Setup replaces the whole source with the defaults of the new kind; the value type stays as it was.

Related

• Parameters overview
• Value types
• Endpoints
• Formula language