Skip to content
GitHub

Screen files

A screen is a customer’s, and it travels as a file. Export a dashboard from one install, import it into another, and nothing about it lives in HotLoop’s code: not the layout, not the tag names, not the text. The same file works in HotLoop IoT, Edge and Gateway, because they run one set of dashboards (Dashboards).

The Edge Relay has no UI and no screens. Flow’s dashboard is part of its flows, which have their own Import and Export. For HotLoop for CODESYS the screens are the Edge’s.

On the Dashboards screen, Export (beside Edit, for the dashboard on screen) saves <id>.hotloop-screen.json. Import (in the bar beside New dashboard) reads a file, tells you what it needs and what is missing here, lets you map each missing tag, device, entity, script or recipe to one that exists, checks again, and saves it. Importing needs dashboards.write, so it is an admin’s. Exporting needs dashboards.read and the dashboard has to be one you are offered.

Through the API, GET /api/dashboards/{id}/export and POST /api/dashboards/import, which is what the screen calls. An import never saves something that building the same dashboard would refuse.

UTF-8 JSON, up to 4 MiB.

{
"format": "hotloop-screen",
"formatVersion": 1,
"exported": { "product": "edge", "version": "4.22.1", "at": "2026-11-19T16:00:00Z" },
"screen": {
"id": "line-2",
"name": "Line 2",
"kind": "cards",
"roles": ["operator", "admin"],
"homeFor": ["operator"],
"screens": ["line-2-panel"],
"position": 1,
"cards": [
{ "id": "temp", "type": "gauge", "title": "Zone 1", "w": 3, "h": 3, "config": { "tag": "press-01/Zone1_Temp" } }
]
},
"requires": {
"tags": [ { "key": "press-01/Zone1_Temp", "dataType": "float", "unit": "C", "writable": false } ],
"entities": [], "scripts": [], "recipes": [], "devices": [], "equipment": []
}
}

format and formatVersion. format is always hotloop-screen. formatVersion is a whole number from 1. A HotLoop reads its own version and older, and refuses a newer one by saying which version the file is and which it reads. A field added to the file is a new version, because a reader refuses a field it does not know: a field dropped without a word is worse than a refusal. This is version 1.

exported. Which product and version wrote it, and when. For the person reading the file. Nothing is decided from it: the card types decide whether a HotLoop can show the screen, and an unknown card type is refused by name.

screen. The dashboard as the dashboards API holds it, without the install’s own bookkeeping (version, updatedBy, createdAt, updatedAt). description is left out when empty. Cards are in reading order, each with its size (w of 12 columns, h in rows) and its config, exactly as Dashboards describes each type. The layout is that: a flow of cards, never pixel coordinates. A symbols card places its symbols by pixel on its own page, inside its config.

Assets are inside. A floor plan on a map card and the background of a symbols card are base64 PNG data URLs in the card’s config, so one file is the whole screen, and sending it is sending the picture too. The limits are the dashboard’s: 700 KB a picture and 2 MiB a screen.

requires. What the screen needs from the install it lands on, worked out from the cards: every tag it reads (with the type and unit it had where it was exported, and whether a button or setpoint writes to it) and the entities, scripts, recipes, devices and equipment ids the cards name. It is for people and for tools that want to look before they import. Import works it out again from the cards and never trusts this block. Where a tag’s type in the file differs from the tag it lands on, that is a warning.

The wall board is not exported. It is an install’s pinned gauges, not a layout. Exporting it is a 400, and a file whose kind is wall is refused.

Assignments. roles, homeFor, screens and position are in the file so a screen comes back as it went. They are also the part most tied to one install: a panel’s name belongs to one dashboard on an install, and a role has one home. An import applies them, and says so (assignment) when this install already gives that screen name or that role’s home to another dashboard. Skip the assignments leaves off screens and homeFor and keeps roles.

The checks run in this order, and nothing is saved until every one passes:

  1. The file. JSON, the right format, a version this build reads, no field it does not know, kind cards.
  2. Your changes to it. A new id or name, no assignments, and the map: tags (whole key to whole key, as the file names the tag or as it reads once the device has moved), devices (id to id; also moves the device part of every tag the tags map does not name, so moving a screen from one PLC to another is one entry), entities, scripts, recipes and equipment (ids are numbers that mean something only where they were made, so they are mapped one by one). A trend’s legend text moves with its tag. A map entry no card used is a warning, because a mapping that did nothing is how a screen ends up pointing at the old thing.
  3. The dashboard’s own rules. Id, name, every card’s config, sizes, the byte limit, in the form that is stored.
  4. Everything the cards name, all of it. Each missing tag, entity, script, recipe, device and equipment id is listed, not only the first, so one pass says what to map. A button or setpoint on a tag that is not writable is writable. A button value or setpoint limit outside the tag’s range and a role that does not exist are screen.
  5. The id and the assignments. An id that is taken is exists, unless you asked to replace it, which saves over that dashboard at the version it has now (so a save made while you were looking is a 409, not an overwrite).

A dry run does all of this and saves nothing. The import is logged as a config event on the dashboard: who, from which product and version, how many cards.

Export on the first install. On the second, make sure the devices and tags the screen reads exist (they carry addresses that belong to the plant, so a screen file does not carry them). Import. If the tag names differ, map them in the dialog, or map the device if only that differs. The screen opens on the second install the way it was on the first.

The same import reads a CODESYS visualization (the IDE’s native export) and makes the screen from it, saying what it left out: Import a CODESYS screen.

The devices and tags a screen reads (their addresses are the plant’s, not the screen’s), the wall board, several screens in one file, and a signature on the file. A file is plain JSON: read it before you import one you were sent.