Parameter procedures

Parameter procedures are under parameter.*; their types are exported by @overvis/hmi-shared/parameter. How parameters work is explained in parameters.

Procedures

Procedure	Returns or does
listInventory	Compact nested inventory of enabled parameters, with labels and branch names, in one call. Optional locale (default en) resolves keys and labels
listTree	All branches and parameters as flat arrays, with full source and valueType, and the lastReading and nextReading snapshots. Clients build the forest from parentId and branchId
listBranches / getBranch	Short branch list (optional parentId filter) / one branch
listInBranch	Short rows of the parameters directly in one branch
searchByName / searchBranchesByName	Name lookup by query (2 characters minimum), matching any locale value, substring and case-insensitive by default. Optional branchId / parentId limits it to direct members
get	One parameter by id
create / update	Full form fields, including source and valueType
deleteSelection	Deletes parameters and branches with their contents; see delete semantics
createBranch / updateBranch	Creates a branch under a parent or as a root / renames a branch (name only)
listConstValues / upsertConstValues	Lists every const value of the workspace in base64 / creates or replaces up to 500 const values by key (editors and above)
readValues / readValuesStream / writeValues	Live I/O; see live value procedures

Both search procedures return at most 25 rows and set hasMore: true when more matched. A broad query in a large tree can match many more rows, because it matches any locale value.

Parameter fields

Field	Rules
id	UUID (minted by Setup or hmi id)
branchId	A branch in the same workspace
name	LocalizedString, 1–100; not unique
description	Optional LocalizedString, ≤2000
icon	Optional Lucide kebab-case id, ≤64; null = no icon (plain string). Only the id format is checked, not that the icon exists
units	Optional LocalizedString display suffix, ≤100 (for example °C)
mnemonic	Optional LocalizedString short label for compact UIs, ≤100
tags	Freeform plain strings: ≤32 tags, each 1–50 characters
source	Discriminated union; see sources
valueType	Discriminated union; see value types. repr labels are LocalizedString
disabledSince	null = enabled; ISO timestamp = disabled
backgroundReadingPeriodMs	null = off; otherwise an integer 1000…86_400_000 that is a multiple of 1000 (whole seconds)
sortOrder	Order among siblings, assigned by the server at creation; not sent on create

LocalizedString is either a plain string (the same text for every locale) or a map of two-letter locale codes to strings ({ "en": "…", "pl": "…" }). Display resolves it in the order active locale, en, first key. Catalog procedures return full maps; the Setup form shows the resolved string and saves a plain string. Names are not unique, so there are no *_name_taken or *_name_reserved errors.

Branch fields

Field	Rules
id	UUID
parentId	null = root
name	LocalizedString, 1–100; not unique among siblings
sortOrder	Order among siblings, assigned by the server

A workspace can have several root branches. Branches have no description and no enable or disable of their own. There is no procedure to reorder branches or parameters, or to move a branch to another parent.

Readings in listTree and get

parameter.listTree includes lastReading and nextReading for every parameter, or null when there is none. Every workspace member receives them.

• lastReading has the reading’s time, display value, raw bytes, and optional numeric or Boolean value.
• nextReading is the next time on the parameter’s background reading schedule. After a slow or live-view reading, the actual next reading can be one period later.
• deviceLog, in parameter.get and parameter.listTree, is set for a parameter that receives readings recorded on an MC252: the import period, the last complete import, and the time through which its history is complete. Otherwise it is null. See readings recorded on an MC252.

listInventory and CLI setup synchronization return configuration only.

Access and errors

Parameter procedures require workspace access: a sign-in session in the cloud app, or a workspace API key in a local workspace. Setup changes require the editor, admin, or owner role. Every member, including view_only, can read live values; writing them requires the operator role or higher (canWriteParameterValues).

Situation	Error
Not a member, no workspace access	workspace_no_access
Setup change without the editor role	workspace_not_editor
Unknown parameter or branch id	parameter_not_found / parameter_branch_not_found
Modbus endpointId missing	parameter_endpoint_not_found
Calc inputParamIds bad or self	parameter_input_not_found / parameter_input_self_reference
Calc inputs would form a loop	parameter_input_cycle
Formula or transform does not parse	parameter_formula_invalid
Calc input of another parameter	parameter_in_use (on delete)

These setup errors fail the call. Live reads and writes report runtime errors per parameter inside a successful result instead; see live value procedures.

Create and update

parameter.create and parameter.update take the same field set; update adds id and an optional baseRevision. update replaces the whole parameter, so leaving out backgroundReadingPeriodMs turns scheduled reading off. source and valueType take only the keys documented in value types and parameter sources.

disabledSince: null means enabled. Without backgroundReadingPeriodMs, the parameter is read only on demand and its readings are stored only when something reads it.

Const numeric

{
  "branchId": "$branchId",
  "name": "Setpoint",
  "description": null,
  "icon": null,
  "units": "°C",
  "mnemonic": null,
  "tags": [],
  "disabledSince": null,
  "source": { "kind": "const", "key": "value", "allowWrite": true },
  "valueType": {
    "name": "num",
    "composition": {
      "fromBytes": {},
      "byteLength": 2,
      "packing": "unsigned-int"
    },
    "multiplier": 1,
    "shift": 0,
    "decimalPlaces": 1,
    "transform": null,
    "writeValidation": { "min": null, "max": null },
    "zones": null
  }
}

update is the same object plus "id": "$parameterId" and, optionally, the revision read before as baseRevision. A new const parameter has no stored value until a write or parameter.upsertConstValues stores one; the key there must match source.key.

Modbus holding register

A holding register is a writable table, so writeFunction is required; "none" keeps the parameter read-only. Input registers and discrete inputs (input-register / discrete-input) are read-only and have no writeFunction.

{
  "branchId": "$branchId",
  "name": "Temperature setpoint",
  "description": null,
  "icon": null,
  "units": "°C",
  "mnemonic": null,
  "tags": [],
  "disabledSince": null,
  "source": {
    "kind": "modbus-tcp",
    "endpointId": "$endpointId",
    "unitId": 1,
    "table": "holding-register",
    "addresses": [0],
    "writeFunction": "single-write"
  },
  "valueType": {
    "name": "num",
    "composition": {
      "fromBytes": {},
      "byteLength": 2,
      "packing": "unsigned-int"
    },
    "multiplier": 0.1,
    "shift": 0,
    "decimalPlaces": 1,
    "transform": null,
    "writeValidation": { "min": null, "max": null },
    "zones": null
  }
}

A coil is "table": "coil" with "writeFunction": "single-write". For a supported device, the parameter templates hold the device’s addresses.

Calc

"source": {
  "kind": "calc",
  "inputParamIds": ["$parameterId"],
  "formula": "#1 * 2",
  "returnFormat": "float"
}

#1 refers to the first entry in inputParamIds, #2 to the second, and so on.

Integer, bool, and string value types

Integer: like numeric without decimalPlaces and zones, plus repr (null or value labels). packing is unsigned-int, signed-int or bcd, or the composition is { "fromBits": [...], "signed": false }. shift and the writeValidation bounds are integers.

{
  "name": "int",
  "composition": { "fromBytes": {}, "byteLength": 2, "packing": "unsigned-int" },
  "multiplier": 1,
  "shift": 0,
  "transform": null,
  "writeValidation": { "min": null, "max": null },
  "repr": null
}

Bool: { "name": "bool", "bit": null, "repr": null }.

String:

{
  "name": "str",
  "fromBytes": {},
  "encoding": "utf8",
  "nulTerminated": true,
  "writeValidation": { "minLength": null, "maxLength": null, "allowedValues": null }
}

Delete semantics

parameter.deleteSelection accepts up to 10_000 parameter ids and 10_000 branch ids in one call. The response lists the ids that were deleted. Deleting a branch also deletes its descendant branches and every parameter in them. Deleting more than one item at once creates a checkpoint, so the deletion can be undone by reverting the setup.

A parameter that another parameter uses as a calc input cannot be deleted on its own (parameter_in_use); deleting both together works. Setup, template apply, and CLI push check a save against the same rules: formulas, the branches, endpoints, and calc inputs a parameter refers to, and dependency loops. A save is refused only for problems it introduces: an older broken reference elsewhere does not block it, but a parameter being saved must itself be valid.

A report preset that snapshots a parameter does not block delete. Deleting the parameter removes it from those presets’ snapshots; its stored readings may remain, and representations that refer to it are not cleaned up. report.preset.listByParameterIds lists the presets that snapshot given parameter ids: any member may call it, empty or unknown ids return [], and it takes at most 1000 parameter ids. A branch is expanded into parameter ids with listTree or listInBranch first. Setup lists those presets in the delete confirmation.

Write live

parameter.writeValues takes one or more items:

{ "items": [{ "paramId": "$parameterId", "value": "42.5" }] }

or { "paramId": "$parameterId", "rawHex": "…" }, not both. See live value procedures.