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.
Use it
Section titled “Use it”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.
The file
Section titled “The file”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.
Importing
Section titled “Importing”The checks run in this order, and nothing is saved until every one passes:
- The file. JSON, the right
format, a version this build reads, no field it does not know, kindcards. - 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 thetagsmap does not name, so moving a screen from one PLC to another is one entry),entities,scripts,recipesandequipment(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. - The dashboard’s own rules. Id, name, every card’s config, sizes, the byte limit, in the form that is stored.
- 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 arescreen. - 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 a409, 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.
Moving a screen
Section titled “Moving a screen”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.
A CODESYS visualization
Section titled “A CODESYS visualization”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.
What is not in version 1
Section titled “What is not in version 1”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.