# Your first working screen

## Create and connect

1. Open **SCADA Studio** from Edge Console. Choose **Process overview**, **Dashboard**, **Touch menu**, or **New project**.
2. Name the project. Click an object in the library to add it, or drag it onto the page. Select an object to change its appearance, data and actions in the inspector.
3. Open **Data**. Add a PLC source from the approved tag catalog, a Prometheus source, a database source, or a formula. When access is unavailable, approve the app's selected resources in Edge Console and reconnect.
4. Select a value, gauge, lamp or trend in **Design** and connect its value binding. Equipment has named **Live inputs** such as liquid level, running feedback and fault feedback. Choose project sources, variables or explicit fixed values for those inputs. Use a variable for values owned by the screen rather than the machine.
5. Open **Preview**. **Simulated inputs** lets you test numeric, boolean and text signals, variables, and good/stale/unavailable quality. **Reset simulation** restores its starting values. **Live data** saves the draft and reads its actual approved Box signals without enabling machine commands. **Signals** shows values, quality and reading times. Check the phone and tablet layouts in either mode.
6. Open **Publish** and review **Design checks**. Each item opens the affected equipment or object at its data/action settings. Connect missing inputs or choose explicit fixed values where appropriate; partial equipment inputs leave operating state unknown. Fixed artwork is a review item, not a publication block. Use **Test this draft**, then **Publish this design**. **Open viewer** uses that fixed version. Later draft edits do not change it.

Your draft saves automatically. A save conflict means another editor changed the same draft: export your current work, reload, then review the changes. The studio never silently overwrites the other draft.

Live preview pins the saved revision. If another engineer edits it during testing, use **Reload saved draft** to load that version before continuing. Switching back to simulation restores your isolated test values. Preview never persists alarms or acknowledges production alarms; use a published test project to qualify alarm recording and acknowledgement. Live preview and published viewers expire old readings while a data request is delayed, using each source's configured stale time.

## Build and reuse a SCADA module

1. Open **Modules** in the project sidebar. Search and preview existing modules, or choose **New SCADA module**. Give it a name in the inspector.
2. Add equipment from **Symbols**. Use **Environment** for walls, floors, fences, racks and other site context. Drag to arrange; fixtures also have a resize handle, exact dimensions, colour and lock/visibility controls. **Layers** selects thin or hidden elements. Select an equipment outlet and a receiving inlet to connect. Selecting a connection exposes its measured-flow binding. Pipes avoid other equipment and captions; amber endpoint markers indicate an obstructed port.
3. Select equipment and connect its **Live inputs** to the same sources used by the rest of the project. **Customize symbol** opens state/input/port authoring and saves a reusable custom definition in this project.
4. Switch between **2D** and **3D** to arrange the two representations. The 3D controls move/rotate equipment; the inspector provides exact positions. Design-time sample values are explicitly labeled.
5. Choose **Add to page**, or choose a destination page in the module browser. The page library's **Place modules** tab also provides quick insertion. Move and resize a placement like any other page object. Add controls, charts and menus alongside it.
6. Set that placement's default 2D/3D mode and whether operators may switch. Double-click it or choose **Edit module** to edit the shared contents in the same view. Switching views while editing updates the referring placement, so **Back to page** shows the layout you just edited. Other placements retain their own view; shared equipment, inputs and connections update throughout the draft. Duplicate the module when different contents or data bindings are needed.

Use **Design module with AI** in the browser to create a module, or in the editor to refine the current one. The Orenda AI sidebar opens inside the designer. Describe the equipment, connections and available data. **Review draft** shows the proposal on the main canvas with 2D and 3D previews. **Apply changes** updates an existing module's placements, or creates and opens the module when the target is new. **Add as copy** keeps the original. Review the result, then publish when ready. Undo also works for AI application.

Modules save, undo, export and publish with the project. There is no separate equipment publication or source-project selection. Published versions remain immutable until a new project version is selected. A module can be removed from the library after its page placements have been removed.

## Arrange the page

Drag to move and use the resize handle to resize. Shift-click selects several objects. Arrow keys nudge the selection; Shift uses the grid step. Ctrl/Cmd-Z undoes, Ctrl/Cmd-Shift-Z redoes, Ctrl/Cmd-D duplicates, and Ctrl/Cmd-G groups. Alt-drag selects a member independently of its group. Delete removes unlocked objects. Text fields retain their normal keyboard behavior.

Use **Layers** to find, hide, lock and reorder objects. The inspector aligns selected objects. Phone/tablet placement changes the selected breakpoint; desktop geometry remains available. Responsive pages stack information and pair compact equipment objects. A canvas page preserves spatial relationships by scaling its coordinates. Preview is the final check for long text, rotated objects and custom breakpoint overrides.

Use **Project** in the designer's library panel to browse pages, their outgoing links and the modules they use. Open a linked page with its arrow, or select the link label to edit its existing Actions. Double-click a navigation control on the canvas to open its destination without executing machine actions.

Each page in **Project** has pencil **Rename** and trash **Delete** buttons. The same actions beside the bottom page tabs act on the current page; double-clicking a page tab also renames it. Renaming keeps its ID and navigation targets, and updates link captions that still match the old name. Custom captions remain yours. The Page name property commits on Enter or leaving the field.

Deleting a page opens a dialog showing which pages link to it. Redirect those links to another page, or remove only their navigation actions while keeping the objects and other actions. Deleting the home page requires choosing a new home page; the project must retain one regular page. Shared modules stay in the library. **Undo** restores the page, home setting and links together. These are draft edits; an existing published/HDMI version changes only after publishing.

Add pages from Project or the plus beside the page tabs. **Add navigation from… and a return link** connects the new page to the current page; uncheck it for an unlinked page. **Add navigation link** connects existing pages using ordinary editable navigation objects. New links and click-placed modules find free space instead of covering existing controls. A page may be a normal page or a dialog. Dialog actions open and close a dialog without losing the underlying page.

In the same **Orenda AI** sidebar, a page request can edit its underlying shared modules. Choose **Entire project** to design or refine several existing pages, shared modules and their navigation together. The draft lists affected pages and shared-module usage, and its review selector lets you inspect each page. Apply saves the complete set of changes as one undo step. **Add as copy** copies the changed pages/modules and reconnects their internal links, preserving the originals. Concurrent changes to a touched page/module block replacement. Publishing remains a separate action.

## Bindings and functions

The **Functions** workspace lists all 64 supported functions with examples and an expression playground. Expressions are bounded; they cannot execute JavaScript, access browser globals, load modules or issue network requests.

| Purpose | Expression example |
| --- | --- |
| Show a source | `source("temperature")` |
| Convert a 4–20 mA signal | `scale(source("current"), 4, 20, 0, 100)` |
| Show a local setpoint | `variable("setpoint")` |
| Conditional color | `if(source("temperature") > 80, "#b84258", "#247a45")` |
| Show availability | `quality("temperature")` |
| Format a caption | `concat("Batch ", variable("batch"))` |

Identifiers in these examples must match your Data entries. Missing or stale values stay unavailable; they are not treated as zero. Formula sources may depend on other formulas, and cycles are rejected. Preview calculates the same formula dependencies as live snapshots.

## Operator actions

Buttons, switches, numeric/text inputs, sliders and selectors use configured actions. Actions can set, toggle or increment a variable, apply an approved recipe, navigate, open/close a dialog, or write a selected PLC source. Optional conditions control whether each action runs.

To enable a PLC control, make its PLC source writable, choose numeric or boolean values, and configure numeric bounds in **raw PLC units**. The Box must separately approve `plc:write` and the specific machine/device/tag bindings. An operator or engineer confirms the command. A fresh good-quality reading is required. The complete action batch is validated before dispatch; an uncertain command is never automatically retried.

Recipes set screen variables. They do not implicitly write PLC registers. Configure explicit bounded PLC actions when the screen should submit those values. Each recipe control can apply only its configured recipes.

An archived project retains its versions but its controls are disabled. Restore it before operating it again.

## Database, trends and alarms

Database sources read app-owned MongoDB collections through the SDK. **Manage records** creates and edits JSON records, filters/paginates the table, exports the current page and asks before deleting. Stale edits require a reload. This namespace is specific to SCADA; another app's collections are not automatically shared.

Prometheus sources use approved metric/tag scopes and a bounded history window. Trends show up to eight returned series, use actual timestamps, provide cursor values, hide/show series and export visible samples as CSV. The range selector filters the loaded history. It does not fetch unapproved or unlimited history.

Alarm rules evaluate expressions against observed snapshots, support a delay and severity, and retain opened/cleared/acknowledged events per published version. Acknowledge from an alarm-list object in the operator viewer. Missing data cannot clear an active alarm. The studio is not an unattended alarm scheduler: keep a viewer running for these observed events, and keep continuous protection in the PLC or the host's alarm service.

## Use AI to create a page

Choose **Describe it. Design it.** and describe the operators, information hierarchy and layout you want. For example: “Make a touch-friendly water treatment overview with inlet flow, tank level, temperature, a trend and a menu to the maintenance page. Use the sources already in this project.”

The shortcut opens **Orenda AI** in the designer's right sidebar, beside the **Properties** tab. Choose a page or module in **Design target**, describe the result and use **Send**. The Agent can ask a question, inspect the project's equipment and data, validate a draft and correct it. Its actions appear in the conversation; **Stop** cancels a running turn. Closing the panel or visiting another project section keeps the conversation and unsent message. Saved conversations also recover after reopening that target. On phones, use **Orenda AI** above the canvas and close the sidebar to return to editing.

Choose **Review draft** to inspect the proposal on the main canvas, then **Apply changes** to save it and continue editing in place. **Add as copy** preserves the original target. **Show on canvas** returns to an already applied result, including after a reload, without duplicating it or overwriting later manual edits. If saving fails, **Retry save** completes the same operation. Page equipment is generated inside SCADA modules; direct legacy symbol objects are unavailable for new designs. Applying does not publish or execute machine actions. The Agent uses the Box-controlled inference broker and organization policy. If inference is unavailable, install/approve the Agent and check its hosted inference enrollment in Edge Console.

The left project navigation becomes an icon rail in Design. Hover over it or focus a button with the keyboard to see labels over the workspace; the canvas does not move. Other project sections keep their usual navigation. On phones, the menu button opens navigation.

## Display, export and housekeeping

Open **Publish**, choose **Browser viewer** or **Box HDMI display**, then publish. HDMI includes an independent language selector; **Publish to HDMI** saves the release and selects it for the monitor together. **Open viewer** opens the published version in the browser. Expand **Previous versions and export** to restore an older HDMI release or export a design.

Select SCADA Studio once in **Edge Console → Display** when configuring the Box. The host-owned `orenda-display` service opens the selected version using an app-scoped display session. The screen follows a newly selected version within about ten seconds. HDMI is a read-only viewer with navigation; machine controls require an authenticated operator session.

Export the current draft or an individual published version to an `.orenda.json` file. Imports verify its checksum and schema and create a separate project. Images, pages, SCADA modules, custom symbols, source definitions, recipes and alarms travel with it; credentials, grants, live values and history do not. Reapprove and remap sources on another Box. Earlier equipment-design packages can also be imported into this unified project model.

Archive projects you are not using. To remove one permanently, open Archive and confirm its full name. Published versions can be removed after export, except the latest version, the HDMI version, or a version with unresolved/unacknowledged alarms. Active viewers of a removed version must reopen another version.