Skip to content

Guided Maintenance

Commercial

Included in the public demo Compare editions

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 maintenance procedure runs A drive's running distance or running time counts up. When it reaches the interval, a Maintenance due tile appears in the message panel. You open the tile and choose Start Step-by-Step. Each step then focuses on its part, moves the camera close, shows symbol markers and offers the operating manual at the right page. When all steps are done, the counter is reset and starts counting towards the next interval. Trigger km or hours of a drive Maintenance due tile in the message panel Start Step-by-Step start dialog Each step Next / Prev, confirm to advance Focus the rest fades and turns grey Camera close-up view of the part Markers symbols, arrows, hidden parts Manual opens at the authored page Done all steps confirmed Reset counter starts again at 0 next interval
A procedure becomes due, you start it from its tile, work through the steps, and finishing it resets the counter.

The standard Demo includes Coolant Nozzle Cleaning, a nine-step procedure with an estimated working time of 19 minutes.

  1. 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.
  2. Choose Start Step-by-Step. The guide replaces the messages on the right and pauses the simulated cell.
  3. 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.
  4. Use Prev, Next, or select a reachable step in the list to move around.
  5. 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 demo cell with the Coolant Nozzle Cleaning start screen on the right: 9 steps, about 19 minutes, with the buttons Overview Flythrough, Start Step-by-Step and Cancel

The start screen of the Coolant Nozzle Cleaning procedure.

The machine performs each demonstration when you enter the step, before you confirm it.

StepWhat you see and doConfirmation
1. Cell stoppedThe 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 switchThe 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 doorThe fence door swings open and the CNC door slides open. Both animations start together.Doors open
4. Look insideThe housing becomes transparent so you can see the spindle and its coolant nozzle below the black elbow.Done button
5. Check spray patternThe nozzle is highlighted and sprays only weakly: its tip is clogged.Done button
6. Unscrew nozzle tipSpray 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 airRead 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 sprayThe 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 lockoutSpray 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

The guide panel at step 5, Check spray pattern, with steps 1 to 4 completed; in the 3D view the highlighted coolant nozzle sprays only weakly

Step 5: the clogged nozzle sprays only weakly.

Step 6, Unscrew nozzle tip: a turning arrow and an out arrow at the nozzle tip below the black elbow, and the Tip removed checkbox in the guide panel

Step 6: arrows show how the tip unscrews.

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.

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.

The Festo demo cell in the HMI with two tiles in the message panel: an orange tile Maintenance due: Schlitten schmieren with the counter 3.000 / 3.000 km and the time Now, and a blue information tile Maintenance: Endlagendämpfung PPV einstellen

A due procedure (orange) and a procedure that is always listed (blue).

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.

Step 5 of Schlitten schmieren in the Festo demo: the machine is faded and grey, the slide of the linear drive is highlighted in blue, two oil can markers labelled LUB-E1 mark the lubrication holes, and the guide panel shows step symbols and the button Betriebsanleitung, p. 18

Focus on the slide, with two lubricate markers at the grease holes.

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.

SymbolMeaningIcon in the panel3D marker
MoveByHandMove a part by handPanTool (hand)Hand with SwapHoriz; with Animate it moves back and forth along the marker’s +X
LubricateGrease or oil a pointOilBarrel (oil can)Oil can
TurnScrewTurn a screw or valveBuild (wrench)Wrench with RotateRight; add a RotateCW or RotateCCW arrow to show the direction
InspectLook at or check somethingVisibility (eye)Eye
MeasureMeasure a valueStraighten (ruler)Ruler
CleanClean a partCleaningServicesCleaning brush
SafetySafety step, lockoutLockLock with Warning
DoneRelease, final checkCheckCircleCheck mark

Step 7 of Schlitten schmieren: the rest of the cell is faded, a hand marker with a back-and-forth arrow sits above the slide, and the guide panel shows a red warning to move the slide slowly

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

Step 4 of Endlagendämpfung PPV einstellen: a close-up of the end cap with a wrench marker labelled PPV zu, 1 U auf, a turning arrow over the adjusting screw, and the button Betriebsanleitung, p. 15 in the guide panel

A TurnScrew marker with a turning arrow. The adjusting screw is a hidden part that shows only in this 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:

  1. 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.
  2. The document address you entered. {lang} in the address is replaced by the UI language, for example de or en.

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 into docs/aas/ and writes docs/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 built-in PDF viewer over the 3D view, titled Betriebsanleitung, open at page 18 of 24 with the section Lubricating slide with guide KF

The manual opens inline at page 18, because the project has a copy of the PDF.

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.

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.

  1. Open the asset in Editor mode. On a hierarchy node, choose Add maintenance procedure. This creates a child named Maintenance with a LogicStep_MaintenanceProcedure component.
  2. Fill in the procedure fields (first table below). A model can have several procedures. Each one gets its own tile.
  3. On the procedure node, choose Add maintenance step for each instruction. Each step is a direct child with a LogicStep_MaintenanceStep component. The order of the children is the order of the steps. Reorder them in the hierarchy to change it.
  4. Fill in the step fields (second table below).
  5. 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.
  6. 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.
  7. For a marker, create an Empty Child on the step and add LogicStep_Arrow to it. Move and turn the child to place the marker.
  8. Save the asset as GLB, then open it in viewer mode to try the procedure.
Procedure fieldsWhat to enter
ProcedureName, EstimatedMinutesThe 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, MessageTextWhenDue 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, TriggerUnitThe drive that counts, and km (distance travelled) or h (time the drive moves). Leave the drive empty for no trigger.
TriggerInterval, TriggerAccelerationThe 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 fieldsWhat to enter
Title, InstructionA short heading and the work to do. An empty title uses the node name.
WarningNote, SeverityWarning text and a severity: Info, Warning, Error or Success. A warning note alone does not block the next step.
CompletionType, CheckboxLabelCheckbox, 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.
EstimatedMinutesWorking time for the step, in minutes.
SymbolThe step symbol in the guide panel, see Step symbols. None shows no symbol.
CameraPosition, CameraTarget, CameraDurationThe saved camera view and how long the camera takes to get there, in seconds. Save current view fills in position and target.
HighlightTargetsThe parts to highlight while the step is active.
DocumentTitle, DocumentPageThe button text, for example Betriebsanleitung, and the page to open. An empty title means no button. Page 0 opens the first page.
DocumentSource, DocumentKeywordA part with an AAS link, and a word from the document title or kind, for example Betriebsanleitung|Operating. Use | to separate alternatives.
DocumentUrlThe address of the document, used without a source or when the AAS has no match. {lang} is replaced by the UI language.

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.

ActionComponent to addSettings
Focus on a partLogicStep_SetTransparencySet 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 transparentLogicStep_SetTransparencyKeep 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 doorLogicStep_DriveTo or LogicStep_AnimateTransformUse a drive for a driven door, or movement and rotation for a hinged or sliding part. There is no separate door component.
Show coolant sprayLogicStep_EffectSet 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 partsLogicStep_AnimateTransformChoose Targets, PositionOffset, RotationAxis, RotationAngle, Duration, Easing, ScrewMotion and StartDelay. Screw motion combines rotation and travel; 720 degrees gives two turns.
Move a driveLogicStep_DriveToPick the drive, enter Destination and choose Relative if needed. The destination uses the drive’s units: millimetres or degrees.
Show a motion arrowLogicStep_Arrow on a child node of the stepSet 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 markerLogicStep_Arrow on a child node of the stepSet 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 signalLogicStep_SetSignalBoolPick 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.

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.

StepComponents on the step node
1. Stop the cellStep with Symbol Safety and an overview camera view
2. Switch off and secure the compressed airSymbol Safety, CompletionType ConfirmWarning
3. Secure the slideSymbol Safety, CompletionType ConfirmWarning
4. Show the linear driveSymbol Inspect; LogicStep_SetTransparency with Mode AllExceptTargets on the drive body and the slide; close camera view
5. Find the lubrication holesSymbol Lubricate; two child nodes with LogicStep_Arrow Type Symbol, Symbol Lubricate, Label LUB-E1; highlight on the slide; manual page 18
6. Apply the greaseSymbol Lubricate, the same two markers, grease type and tool in the instruction
7. Move the slide slowly by handSymbol MoveByHand, a hand marker with Animate, a warning note, LogicStep_DriveTo moves the slide out slowly
8. Push the slide backSymbol MoveByHand, LogicStep_DriveTo back to the start position
9. Check the grease film on the railSymbol Inspect, CompletionType Observation, an Inspect marker, manual page 17
10. ReleaseSymbol Done; LogicStep_SetTransparency with Mode AllExceptTargets and no targets ends the focus
  • 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.