Start screens

A start screen is a named entry point that opens one screen. Engineers decide which exist, who sees each and which opens first; every user can pick their own among the ones they may see. This page is for engineers setting up what operators land on, and for anyone wondering why Scadex has no projects.

In the dashboard, start screens are called Pinned screens: the star on a screen in the Screens list pins it.

No projects, on purpose

Scadex keeps one shared pool of screens, tags, tag types and scripts for the whole gateway. There are no projects with their own resources, inheritance or isolation. Instead, any number of start screens point into that pool, each a named entry that opens one screen, optionally grouped, ordered and limited to chosen roles. The roles on a start screen only decide what a menu offers. They do not lock the screen itself: any signed-in user can still open any screen by name at /hmi/<slug> or /app/<slug>. Use roles to decide who may write.

What a start screen is

Field	Meaning
Name	Up to 80 characters. Shown in menus; it can differ from the screen's name.
Opens	The screen (view) it opens. The dashboard offers only screens whose Used as is Operator screen and that declare no parameters; the API checks only that the screen exists. If that screen is later deleted, the entry is marked "Its screen was deleted. Choose another above." and is hidden from users until fixed.
Group	Optional, up to 120 characters. Entries are shown grouped; entries without a group come first, then groups by name.
Shown to	Any of Viewer, Operator, Engineer, Admin. All four ticked is stored as "everyone" (an empty list). An entry needs at least one role; remove it instead if nobody should see it.
Default	Exactly one entry is the gateway default while any exist.
Order	The engineer's order within the list, set with the up and down arrows.

At most 100 start screens can exist. The first one created becomes the default, and creating the first one also turns on Open the start screen straight away for the gateway.

Managing start screens

1. Open Screens, then Pinned screens (the count is shown on the button).
2. Pin a screen with Pin a screen… and Add, or with the star next to a screen in the list. The star removes every entry that opens that screen.
3. For each entry set its name, Opens, Group and Shown to; use the arrows to order; Make default marks it as the gateway default; the bin icon removes it.
4. Open the start screen straight away decides whether the app view opens into the start screen or shows the pinned list first. Each person can override this for themselves.

Changing a default: marking another entry as default clears the previous one. Unmarking the only default hands it to the next entry in order; the only remaining entry cannot be unmarked. Deleting the default passes it to the next in order, and clears it from any user who had chosen it.

What each user sees

The list a user receives contains only the entries whose roles include theirs (or that are open to everyone) and whose screen still exists. From that list the gateway resolves:

• defaultId: the user's own choice if it is in the list, otherwise the gateway default, otherwise the first entry.
• openOnLaunch: the user's own setting (on or off) if they made one, otherwise the gateway's.

The role used is the highest the user holds.

Where start screens appear

• The Screens group in the dashboard rail has one entry per pinned screen the user may see, then All screens (/hmi), which lists Pinned screens first, the default marked Default in words, then All screens by folder.
• The app view picker (/app) lists the same, and when openOnLaunch is on it goes straight to the resolved default.
• The Pinned screens switcher in the app view header appears once a user can see two or more entries. It lists them by group, marks the one on show, and lets the user make any entry their default with the star. Its On launch select offers Follow the gateway (showing what the gateway does), Open my start screen and Show the list.

A user's choice belongs to a person: it needs a signed-in session, and cannot be set with an API key.

API

All routes are under /api/v1/start-screens and need at least the viewer role; writing entries needs the engineer role.

Route	Who	What
GET /api/v1/start-screens	viewer	The caller's entries, defaultId, myChoice, gatewayOpenOnLaunch, myOpenOnLaunch, openOnLaunch, canManage. With ?all=true (engineer) every entry, including hidden ones.
POST /api/v1/start-screens	engineer	Create: name, viewId, folder, roles, isDefault.
PATCH /api/v1/start-screens/{id}	engineer	Change any of those fields.
DELETE /api/v1/start-screens/{id}	engineer	Remove; returns 204.
PUT /api/v1/start-screens/order	engineer	{"ids": [...]}: each id once; entries left out keep their place after the listed ones.
PUT /api/v1/start-screens/me	viewer, cookie session only	startScreenId (one the caller may see) and openOnLaunch as default, on or off. Returns the list as GET does.

Each entry is returned as {id, name, viewId, viewName, missing, folder, roles, isDefault, order}. The gateway-wide Open the start screen straight away switch is the app setting openStartOnLaunch; see Settings.

Upgrading from a single start screen

Earlier versions stored one start screen in the app settings. On the first start of a gateway with none of the new entries, that screen becomes the single default entry, named after the screen, and open on launch is turned on.