Author a workspace parameter template

Overvis already ships parameter templates. A workspace template adds a device for this workspace only, or replaces a shipped template here. Templates live in templates/parameters/ of a pulled workspace checkout, next to setup.db, one JSON file per device.

Write the template

1. Pull the workspace, and open templates/schemas/parameter-template.schema.json. The template must match it. Do not edit or push templates/README.md or templates/schemas/: every pull rewrites them.
2. If the checkout has no templates/parameters/ directory yet, create it. A pull has none until the workspace has templates of its own.
3. Create the JSON file at any depth under templates/parameters/. Its path without .json is the template id that list and stamp use, so do not put an id in the JSON. To replace a shipped template, use the path of its id as templates.parameter.list shows it.
4. Set $schema to the relative path of templates/schemas/parameter-template.schema.json. Count ../ from the JSON file’s directory.
5. Build the tree (see Build the tree) and check its quality (see Check the content).
6. Run pnpm hmi check and fix every problem.
7. Push the clean checkout with pnpm hmi push. The template is available to Setup and templates.parameter.stamp only after the push completes.

Build the tree

1. Give the template one root branch. Group the leaves the way an operator commissions the device. Sibling display names must be unique per language.

2. For Modbus leaves, use the same table, addresses, and writeFunction fields as a live parameter (Modbus source). The workspace schema is the field contract. Take addresses as zero-based PDU addresses: convert 1-based or “40001”-style register numbers from the manual.

3. If the device has a factory unit ID, set it as defaultUnitId. Leaves have no unit ID of their own: stamp takes it from the request, or from defaultUnitId when the request has none.

4. For a leaf computed from other leaves, use a calc source:

   • give each input leaf a key that is unique in the file;
   • list those keys in inputKeys in formula order (#1, #2, …);
   • write formula and returnFormat as on a live calc source.

   Stamp replaces the keys with the new parameter ids. Use this when the device’s scale depends on one of its own settings: read the raw value and the setting as separate leaves and compute the engineering value from them.

{
  "name": { "en": "Phase 1 current" },
  "source": {
    "kind": "calc",
    "inputKeys": ["phase-1-current-raw", "current-resolution"],
    "formula": "#1 * #2",
    "returnFormat": "float"
  }
}

Check the content

• Take every register from the device manual or other documentation you rely on. Leave out registers it does not document, and skip reserved and always-zero rows.
• Locale maps (name, title, repr labels) can use one key, in the language of that documentation. To add another language, add its key with a real translation; a copy of the source string in another locale key adds nothing.
• To list the template in Setup for stamping, set visibility to "public". "private" hides it there.
• To associate the template with documentation already available to the in-app assistant, set docsPath. Otherwise omit it or set it to null.

Extend MC252 device identification

Do this only when you identify unknown Modbus devices on an Overvis MC252 and Overvis does not already know the model. The script and map formats are in the device-find language reference.

1. Create templates/class-find/catalog.txt with probes that return a class name for the device. It is prepended to the Overvis catalog, so its probes run first. Put each label on its own line, and narrow every range to the values your device can hold.
2. Create templates/class-find/map.json with an entry for each class name your probes return. Set templateId to the template id, for example acme/foo for templates/parameters/acme/foo.json. If the probes cannot tell several models apart, list them in candidates instead. To name the device without a template, leave both out.
3. Run pnpm hmi check, and commit and push the overlay with the template.

To use Overvis identification only, leave the templates/class-find/ folder out.