Guided maintenance takes you through a procedure step by step while the machine follows along. Doors open, the rest of the machine fades out, symbols show where to grease or which screw to turn, and the operating manual opens at the right page. Each step combines an instruction with a camera view, highlighted parts and a confirmation.
A procedure is a sequence of steps. Each step is a node in the model with a LogicStep_MaintenanceStep component and the actions you add to it. You build it in the Web Editor. Unity is not required.
The open-source viewer includes the guide with instructions, camera views, highlights, confirmations, step symbols, message tiles, the running-distance trigger and the manual link. Animated actions, the focus fade and the 3D markers are commercial features.
How a procedure runs
Section titled “How a procedure runs”Try it in the demo
Section titled “Try it in the demo”The standard Demo includes Coolant Nozzle Cleaning, a nine-step procedure with an estimated working time of 19 minutes.
- Open the standard Demo and select Maintenance, or open Maintenance Due in the message panel on the right. Its message reads Coolant pressure low at nozzle 3 — cleaning due.
- Choose Start Step-by-Step. The guide replaces the messages on the right and pauses the simulated cell.
- Read the active instruction and any warning. Select its checkbox or confirmation button when you are finished. This records the step and moves to the next one.
- Use Prev, Next, or select a reachable step in the list to move around.
- Confirm Main switch locked out before you go past the safety step. Until then, the guide shows Confirm the safety step first.
You can skip ordinary steps with Next. They stay Open. Next is disabled for a moment while the camera moves.
Choose Overview Flythrough instead for an automatic preview of the procedure. It plays the views and machine actions without recording confirmations. Cancel closes the start screen.

The start screen of the Coolant Nozzle Cleaning procedure.
The nine steps
Section titled “The nine steps”The machine performs each demonstration when you enter the step, before you confirm it.
| Step | What you see and do | Confirmation |
|---|---|---|
| 1. Cell stopped | The simulated cell is paused and the CNC axes move to their maintenance position. The camera shows the cell and highlights the CNC screen. Check that the machine is idle. | Machine is idle |
| 2. Lockout / tagout main switch | The camera approaches and highlights the main switch. The switch lever turns a quarter turn to OFF, and a turning arrow shows the direction. Attaching your personal padlock and tag is not animated. | Main switch locked out |
| 3. Open safety fence and machine door | The fence door swings open and the CNC door slides open. Both animations start together. | Doors open |
| 4. Look inside | The housing becomes transparent so you can see the spindle and its coolant nozzle below the black elbow. | Done button |
| 5. Check spray pattern | The nozzle is highlighted and sprays only weakly: its tip is clogged. | Done button |
| 6. Unscrew nozzle tip | Spray stops. The tip turns two turns and moves out, while a turning arrow and a straight arrow show the motion. | Tip removed |
| 7. Clean tip with compressed air | Read the cleaning and inspection instructions and the eye-protection warning. The tip remains removed; cleaning itself is not animated. | Tip clean |
| 8. Refit tip and test spray | The tip screws back into position, with arrows showing the direction. After about two seconds, the nozzle sprays a full, even jet. | Done button |
| 9. Close doors and release lockout | Spray stops, the housing becomes opaque, both doors close and the main switch lever turns back to ON. Removing the lock and tag is not animated. | Cell ready |

Step 5: the clogged nozzle sprays only weakly.

Step 6: arrows show how the tip unscrews.
Going back and leaving
Section titled “Going back and leaving”Prev moves the machine back into the state of the selected step. For example, going back from nozzle removal to the spray check refits the tip and restores the weak spray. Confirmations you already recorded stay completed.
Selecting a step directly also brings the machine into that step’s state. Going back and jumping do not replay the start delays.
Use the back arrow beside Back to Overview to leave the guide. Leaving or finishing the guide restores the machine to its state from before the guide and lets the cell run again.
Unfinished step-by-step progress is saved in your browser, so you can resume it.
The summary shows Passed and Open, and Failed when there are failed steps. Check these counts: the heading All Steps Completed also appears when you skipped ordinary steps. A flythrough does not mark steps as passed.
Message tiles and due procedures
Section titled “Message tiles and due procedures”Each procedure can have its own tile in the message panel. The tile shows in every mode, not only in the HMI. Click it to open the start dialog of exactly that procedure.
- Maintenance: name is an information tile. You get it when the procedure is set to show its tile always.
- Maintenance due: name is a warning tile with the time Now. It appears when the procedure’s trigger is reached. Below the title, the tile shows your message text, or the counter, for example 3.000 / 3.000 km.
A procedure becomes due through a running-distance trigger. You pick a drive. The viewer adds up how far the drive travels (km) or how long it moves (hours). When the counter reaches the interval, the procedure is due. An acceleration factor speeds up the counter, so a demo reaches thousands of kilometres within a minute. The counter lives in memory only: a page reload starts it again at 0. When you finish the procedure step by step, the counter is reset. A flythrough does not reset it.

A due procedure (orange) and a procedure that is always listed (blue).
Focus, symbols and markers
Section titled “Focus, symbols and markers”A step can focus on the part you work on. Everything else fades and turns grey, so the part stands out even inside a full machine. The focus stays until a later step changes it. A focus step without targets ends it. Going back before the focus step, or leaving the guide, brings the normal view back.
Each step can also move the camera to its own close-up view, and show markers in the 3D view. A marker is a step symbol with an optional short label, or a motion arrow. It shows only while its step is active.
A marker can also reveal hidden parts. If you hide a part in the editor and place it below a marker, the part is visible only while that marker’s step is shown. Use this for parts the CAD model does not contain, such as an adjusting screw.

Focus on the slide, with two lubricate markers at the grease holes.
Step symbols
Section titled “Step symbols”You set a symbol per step. It appears in front of the step title in the guide panel. The same symbols are available for 3D markers. They use the Material icons of the HMI.
| Symbol | Meaning | Icon in the panel | 3D marker |
|---|---|---|---|
| MoveByHand | Move a part by hand | PanTool (hand) | Hand with SwapHoriz; with Animate it moves back and forth along the marker’s +X |
| Lubricate | Grease or oil a point | OilBarrel (oil can) | Oil can |
| TurnScrew | Turn a screw or valve | Build (wrench) | Wrench with RotateRight; add a RotateCW or RotateCCW arrow to show the direction |
| Inspect | Look at or check something | Visibility (eye) | Eye |
| Measure | Measure a value | Straighten (ruler) | Ruler |
| Clean | Clean a part | CleaningServices | Cleaning brush |
| Safety | Safety step, lockout | Lock | Lock with Warning |
| Done | Release, final check | CheckCircle | Check mark |

A MoveByHand marker: the hand moves back and forth to show the motion.

A TurnScrew marker with a turning arrow. The adjusting screw is a hidden part that shows only in this step.
Operating manual per step
Section titled “Operating manual per step”A step can link to a page of a document, usually the operating manual. The button appears in the step, for example Betriebsanleitung, p. 18. The page number is part of the button text: p. in English, S. in German.
The viewer looks for the document in this order:
- The handover documentation of a part’s Asset Administration Shell (AAS). It picks a document whose title or kind matches your keyword, in the UI language. If there is none, it takes German, then English, then any match.
- The document address you entered.
{lang}in the address is replaced by the UI language, for exampledeoren.
How the document opens depends on where it is:
- A PDF inside the AASX opens in the built-in PDF viewer at the page.
- A PDF on another website opens in a new browser tab at the page. Most manufacturer sites do not allow the viewer to load their files directly.
- If the project has a copy of that PDF, it opens in the built-in PDF viewer at the page instead. To make copies, run
node scripts/mirror-aas-documents.mjs --project <project folder>in the realvirtual folder. The script downloads every external PDF that the project’s AAS files link to intodocs/aas/and writesdocs/aas/mirror.json. The viewer uses copies only when that file exists.
If the document cannot be found, the button is disabled and shows Document not available.

The manual opens inline at page 18, because the project has a copy of the PDF.
Live connection
Section titled “Live connection”With a live industrial connection, the guide shows Live connection — machine is not moved by the guide.
Instructions, camera views and highlights stay available, but the guide does not pause or move the connected machine. Connecting live during a guide stops its demonstration actions. Disconnecting again does not restart them in the same guide.
Confirming a step records your acknowledgement. It does not check that the machine is really locked out or that the work on the real machine is done.
Build your own procedure
Section titled “Build your own procedure”Create procedures in the commercial Web Editor. You can build them by hand as described below, but the faster way is to let an AI assistant do it.
- Open the asset in Editor mode. On a hierarchy node, choose Add maintenance procedure. This creates a child named Maintenance with a
LogicStep_MaintenanceProcedurecomponent. - Fill in the procedure fields (first table below). A model can have several procedures. Each one gets its own tile.
- On the procedure node, choose Add maintenance step for each instruction. Each step is a direct child with a
LogicStep_MaintenanceStepcomponent. The order of the children is the order of the steps. Reorder them in the hierarchy to change it. - Fill in the step fields (second table below).
- Move the camera to a close view of the part and select Save current view. Select Clear view if the step should leave the camera where it is.
- Use Add component on the step to add actions (third table below). The maintenance components are in the group Logic ▸ Maintenance. Pick the affected parts with the reference picker.
- For a marker, create an Empty Child on the step and add
LogicStep_Arrowto it. Move and turn the child to place the marker. - Save the asset as GLB, then open it in viewer mode to try the procedure.
| Procedure fields | What to enter |
|---|---|
| ProcedureName, EstimatedMinutes | The name shown in the tile and the guide, and the working time. An empty name uses the node name. Zero minutes uses the sum of the step times. |
| Message, MessageText | WhenDue shows the tile only when the trigger is reached. Always lists it all the time as information and turns it into a warning when due. The text appears below the tile title. Empty shows the counter. |
| TriggerDrive, TriggerUnit | The drive that counts, and km (distance travelled) or h (time the drive moves). Leave the drive empty for no trigger. |
| TriggerInterval, TriggerAcceleration | The value at which the procedure is due, in the trigger unit. Zero means no trigger. The acceleration speeds up the counter. 1 counts real distance or time. |
| Step fields | What to enter |
|---|---|
| Title, Instruction | A short heading and the work to do. An empty title uses the node name. |
| WarningNote, Severity | Warning text and a severity: Info, Warning, Error or Success. A warning note alone does not block the next step. |
| CompletionType, CheckboxLabel | Checkbox, ConfirmWarning for a safety step that must be confirmed before you can go on, or Observation for a confirmation button. Set the wording of the checkbox or button. |
| EstimatedMinutes | Working time for the step, in minutes. |
| Symbol | The step symbol in the guide panel, see Step symbols. None shows no symbol. |
| CameraPosition, CameraTarget, CameraDuration | The saved camera view and how long the camera takes to get there, in seconds. Save current view fills in position and target. |
| HighlightTargets | The parts to highlight while the step is active. |
| DocumentTitle, DocumentPage | The button text, for example Betriebsanleitung, and the page to open. An empty title means no button. Page 0 opens the first page. |
| DocumentSource, DocumentKeyword | A part with an AAS link, and a word from the document title or kind, for example Betriebsanleitung|Operating. Use | to separate alternatives. |
| DocumentUrl | The address of the document, used without a source or when the AAS has no match. {lang} is replaced by the UI language. |
Actions
Section titled “Actions”Actions on different parts start together unless StartDelay staggers them. Their result stays in later steps until another action changes it. Use separate steps for actions that follow each other on the same part.
| Action | Component to add | Settings |
|---|---|---|
| Focus on a part | LogicStep_SetTransparency | Set Mode to AllExceptTargets and pick the parts to keep in Targets. RestOpacity sets how visible the rest stays (default 0.08, 0 hides it). RestDesaturation sets how grey it turns (default 1, fully grey). You set the strength per step; there is no slider in the viewer. |
| Make a housing transparent | LogicStep_SetTransparency | Keep Mode at Targets, pick the parts and set Opacity from 0 to 1. 0 hides the parts, 1 restores their normal look. Set Duration and StartDelay. You can combine it with a focus on the same step. |
| Open or close a door | LogicStep_DriveTo or LogicStep_AnimateTransform | Use a drive for a driven door, or movement and rotation for a hinged or sliding part. There is no separate door component. |
| Show coolant spray | LogicStep_Effect | Set Type to CoolantSpray. Choose Anchors, Intensity, ReducedAnchors, ReducedIntensity, Length, Angle and StartDelay. Intensity goes from 0 to 1; 0 switches the spray off. |
| Move, rotate or unscrew parts | LogicStep_AnimateTransform | Choose Targets, PositionOffset, RotationAxis, RotationAngle, Duration, Easing, ScrewMotion and StartDelay. Screw motion combines rotation and travel; 720 degrees gives two turns. |
| Move a drive | LogicStep_DriveTo | Pick the drive, enter Destination and choose Relative if needed. The destination uses the drive’s units: millimetres or degrees. |
| Show a motion arrow | LogicStep_Arrow on a child node of the step | Set Type to Linear, RotateCW or RotateCCW, the Size (edge length in metres) and Animate. The arrow lies in the node’s local XY plane: a linear arrow points along local +X, a turning arrow turns about local +Z as seen from the +Z side. |
| Show a symbol marker | LogicStep_Arrow on a child node of the step | Set Type to Symbol, pick the Symbol and enter an optional Label, for example a grease type. The symbol always faces the camera. Hidden parts below this node show while the step is active. |
| Set a Boolean signal | LogicStep_SetSignalBool | Pick the Signal and set SetToTrue. Signals under external control are not changed. |
Durations and start delays are in seconds, angles in degrees. Position offsets and spray length use scene units. Position offsets and relative drive destinations refer to the machine state at the start of the guide. They do not add to the movement of the previous step.
Example: lubricating a linear drive
Section titled “Example: lubricating a linear drive”The Festo demo cell has two procedures for its DGC linear drive, built from the same parts. Schlitten schmieren (lubricate the slide) has ten steps and becomes due after 3000 km of the slide drive. Endlagendämpfung PPV einstellen (set the end-position cushioning) has seven steps and is always listed. Both link each step to the manufacturer’s operating manual at the right page.
| Step | Components on the step node |
|---|---|
| 1. Stop the cell | Step with Symbol Safety and an overview camera view |
| 2. Switch off and secure the compressed air | Symbol Safety, CompletionType ConfirmWarning |
| 3. Secure the slide | Symbol Safety, CompletionType ConfirmWarning |
| 4. Show the linear drive | Symbol Inspect; LogicStep_SetTransparency with Mode AllExceptTargets on the drive body and the slide; close camera view |
| 5. Find the lubrication holes | Symbol Lubricate; two child nodes with LogicStep_Arrow Type Symbol, Symbol Lubricate, Label LUB-E1; highlight on the slide; manual page 18 |
| 6. Apply the grease | Symbol Lubricate, the same two markers, grease type and tool in the instruction |
| 7. Move the slide slowly by hand | Symbol MoveByHand, a hand marker with Animate, a warning note, LogicStep_DriveTo moves the slide out slowly |
| 8. Push the slide back | Symbol MoveByHand, LogicStep_DriveTo back to the start position |
| 9. Check the grease film on the rail | Symbol Inspect, CompletionType Observation, an Inspect marker, manual page 17 |
| 10. Release | Symbol Done; LogicStep_SetTransparency with Mode AllExceptTargets and no targets ends the focus |
Limits
Section titled “Limits”- The standard demo’s maintenance message is predefined. It does not report a measured coolant-pressure fault.
- Coolant spray is a visual effect, not a fluid simulation. No other effect type is available.
- Procedures support the actions listed above. Waiting for signals and general logic sequences are not supported maintenance actions.
- Authoring and playback use separate modes. There is no procedure preview inside the Editor.
- The Maintenance entry opens the first procedure in the model. Use the message tiles to open the others.
- The running-distance counter is not saved. A page reload starts it again at 0.
- Render-mode switching is locked while animated maintenance runs.
- A transparent or faded housing can still block selection of parts behind it.
- Without the commercial animation feature, instructions, views, highlights, symbols, tiles and the manual link stay available, but the machine does not move, fade or show 3D markers.
For the surrounding interface, see HMI overview, Operator panel and Asset Administration Shell.