Device-find language

An MC252 identifies an unknown Modbus device by running a catalog script against it. The script returns a class name, and a class map turns the class name into a device title and, optionally, a parameter template. Overvis ships the catalog and the map. A workspace can add its own fragment of each (catalog.txt and map.json), as described in Author a workspace parameter template. This is not the MC252 taskfile language.

The workspace catalog.txt is inserted in front of the Overvis catalog, so its probes run first. Keys in the workspace map.json replace the Overvis entries with the same key. hmi check checks both files: the map against its schema, and every catalog line the MC252 would stop at with an error. Without them, identification uses the Overvis catalog and map only.

Catalog script

catalog.txt is UTF-8 text. A byte-order mark is allowed. UTF-16 and UTF-32 are not. The controller reads the script top to bottom. A line either returns a class name, continues at the next line, or jumps forward to a label. Labels are forward only. Reaching the end without return leaves the class undefined, and the run fails with ERROR_EOF.

Each non-empty line is at most 82 characters before its comment, not counting the line ending. ; starts a comment. Keywords and labels are case-insensitive. The class name in return is stored upper case. Spaces separate tokens; tabs are not allowed. Numbers are unsigned 16-bit: 0 through 65535 or 0x0 through 0xFFFF.

Metadata lines

Metadata lines do not read Modbus. @createdon is up to 31 characters and @version up to 15. Write the @createdon value without quotes.

@createdon 2026-08-07T00:00:00Z
@version 1

Commands

<source> [ & <mask> ] <check>(<min>, <max>) ? <then> [ : <else> ]

A line without ? is not a command and does nothing. A bare return UNKNOWN therefore never returns. <source> is a Modbus address and a suffix: c coil, d discrete input, h holding register, i input register. 0h is holding register 0. The optional & <mask> is a bitwise AND on the value or exception code before the check.

Check	Succeeds when
inrange(min, max)	The read completed and the masked value is in the inclusive range
mbexception(min, max)	The masked Modbus exception code is in the inclusive range

When the check fails and there is no : <else>, the next line runs.

Labels

A label is a line of its own: up to 23 characters followed by :. A goto continues at the next later line with that label. The MC252 rejects a command that shares a line with a label and stops with ERROR_DATA_SOURCE_ADDRESS.

0h inrange(26, 30) ? goto acme : goto other
acme:
1h inrange(9, 11) ? return ACME-FOO : return ACME
other:

Here a register-0 value from 26 through 30 enters acme. Every other answer continues at other.

Action	Effect
return <class>	Stop. Report <class> (1 through 21 characters)
goto <label>	Continue at the next later <label>:

0h mbexception(0, 255) ? return UNKNOWN
0h inrange(99, 99) ? return FOO

UNKNOWN means no match. A workspace fragment that returns UNKNOWN stops identification before the Overvis catalog runs.

Reads and timing

The MC252 sends one Modbus request per command, for one item. Consecutive commands that check the same item reuse its answer and send nothing. A command on another item sends a new request, even for an item read earlier.

A device that does not answer reads as Modbus exception 11. inrange fails, mbexception(11, 11) succeeds, and so does mbexception(0, 255). An answer, a value or an exception, takes about 70 ms at 9600 baud. Silence takes about 270 ms. There are no retries. Each line also costs a few milliseconds, including a line that a goto skips while it looks for its label.

Class map

map.json is an object keyed by class name. Keys are the upper-case names that catalog.txt returns, at most 21 characters. UNKNOWN is not a map key.

Field	Meaning
title	Name shown after identification. A string, or a map of two-letter locale keys
templateId	Optional. Parameter template id, the template file’s path without .json, for example acme/foo
candidates	Optional. Two to 16 template ids, for a class that covers several models the catalog cannot tell apart
docsPath	Optional. Path to device documentation when it exists

An entry sets templateId, candidates, or neither, never both. With candidates, the result lists every candidate, and the user or the assistant picks the model. Without either, identification names the device but picks no parameter template.

{
  "FOO": {
    "title": { "en": "Acme Foo" },
    "templateId": "acme/foo"
  },
  "ACME": {
    "title": { "en": "Acme Foo 1 or Foo 2" },
    "candidates": ["acme/foo-1", "acme/foo-2"]
  }
}