Draw an equipment diagram

This guide draws an editable diagram, such as a pumping station or a room layout, with dashboard graphics. The drawing model, editor behavior, symbols, and API are described in Editable dashboard graphics. You need the Editor, Admin, or Owner role, and a desktop browser for editing.

Start a drawing

1. In Setup → Dashboards, select Create dashboard and choose the Canvas template.
2. Open the dashboard and select Edit drawing in the bar above the drawing.

To put a drawing in a dashboard you develop in code, see Mount a drawing in code.

Draw the equipment and lines

1. Select Symbols, find the equipment by name, tag, or abbreviation, choose a variant, and select Insert. Click the drawing to place it. To place several copies, turn on Place multiple first.
2. Keep equipment and its connection points on the drawing grid. Editors can then drag equipment away and restore straight connections by snapping it back. Line up connected ports, so lines run straight.
3. Select the Line tool (L) and drag from one port to another. To branch a line, drop a line end on another line.
4. Draw busbars and distribution trunks with ordinary lines and junctions.
5. For light text on a dark box, give the box a light stroke, or place a text object on it.
6. Use an image as a background or reference photograph, and draw editable elements over it.
7. Use plain text for equipment tags and units; they read the same in every language.

Bind the drawing to live readings

1. Select an object and select the link button beside a property in Properties.
2. Choose the parameter in the binding card. Every binding that uses the same slot takes that parameter; to bind only this property, choose No shared slot under Shared slot.
3. Bind each symbol’s essential properties first; Properties lists them under Key properties.
4. For a symbol’s level, bind a percentage reading with a value binding, or a scale binding with an explicit input range.
5. To map a controller’s state codes to a symbol’s states, use a states binding.
6. For logic that combines several readings, create a calculated parameter and bind to it.
7. For agitator speed, direction, or fault on a process vessel, place an hmi.agitator beside it.

Make states readable

1. Keep operating controls together, and use the same layout for every reading panel.
2. Distinguish equipment states with labels as well as color.
3. Animate only while readings are fresh, and keep connection paths visible when the animation stops.

Add operator controls

1. To give a symbol a control, assign an action to its named control, such as the built-in hmi.button’s activate.
2. For on/off operation, use a toggle. Bind its source to the writable command parameter and its status to the feedback parameter. For hmi.button, bind active to the same status.
3. For resets, use a fixed command. For a numeric setpoint, use a write action, which opens an input dialog. Use explicit controls for every operation; value readouts are passive.
4. If a setpoint form resets while you review it, because its action or target changed, enter the value again against the current target before you write.
5. Let an enable control read back its command register, and let the equipment artwork read the actual running feedback separately. An operator can then cancel an enabled request while a fault holds the equipment stopped, and clearing the fault respects the current request.

Choose the frame and save

1. Pan, zoom, or fit the drawing until it shows the frame viewers should see. Leave room for bound size and rotation changes.
2. Select Save. If Save names an invalid value, correct the field it selects and save again.
3. Check the drawing on a phone: it keeps its layout and opens at a legible minimum scale, with its own panning and zoom.

Mount a drawing in code

1. Render DashboardGraphics with workspaceId, dashboardId, and a UUID drawingId. Use a different drawing ID for each drawing in the dashboard.
2. Keep those IDs stable. Changing one opens a new session, and a draft is not carried over.
3. Optionally pass defaultDocument for the drawing before its first save, and maxWidth and maxHeight to limit its size in view mode.
4. When you generate a document, give each element, connector, and slot a UUID, and keep those IDs when you correct an existing drawing.

Save a drawing through the API

1. Read the drawing with graphics.get, passing workspaceId, dashboardId, and the drawingId that the dashboard’s DashboardGraphics mounts. A drawing saved under another ID does not show; a new drawing needs its own mount. Keep its revision; for an unsaved drawing, both document and revision are null.
2. Validate the changed document with graphicsDocumentSchema, or check it with graphics.validate.
3. Save it with graphics.save, using the same IDs and passing the revision as expectedRevision (null for the first save).
4. If the save fails with graphics_conflict, keep the draft, read the current document again, and review the differences before you save again. Do not resubmit the old draft with the new revision: it overwrites the other edit.
5. To change one drawing, use graphics.save rather than dashboard.update; it keeps the rest of the configuration. A dashboard.update must send expectedConfiguration from the read it is based on; keep that baseline while the form is open.
6. Before a local workspace push that includes the dashboard, pull to take in the API edit; otherwise the push fails with push_conflict.

Related

• Editable dashboard graphics
• Author a workspace symbol
• Create and publish a dashboard