Panel Instruction Editor — User Manual

Build interactive, multilingual step-by-step instruction guides for any machine control panel. Operators scan a QR code stuck to the equipment, open the guide on their phone, and tap through the action they need (Start, Clean, Reset) with the relevant buttons flashing on a photo of the panel itself.

What this tool is

Panel Instructions turns a photo of a machine control panel into a hands-on guide for the people who operate that machine. You drop coloured markers on each button or switch in the photo, write the steps for each action in up to four languages (English, Polish, Russian, Romanian), and the tool produces a single self-contained HTML file you can host anywhere — or share via QR code stuck on the machine.

Three things it solves:

Operator onboarding — no more paper laminated cards that get lost or go out of date. Update the guide in the editor, re-deploy, the new version is live.
Language barriers — write each step once per language. Operator picks their language at runtime.
Visual clarity — operators see the actual panel photo with the relevant button flashing. No translation of "the red button near the top-left of the second row."

Designed for: food-manufacturing supervisors authoring guides on a PC; operators consuming them on a phone via QR code on the equipment.

Quick start (5 minutes)

Open editor.html in Chrome or Edge (double-click on Windows).
You land on the welcome screen. Click Connect a folder and pick any folder on your PC. The editor will read your starter templates and save panels you create directly into that folder.
Click New in the header. Type an equipment name (e.g. "Conveyor Line 3B"). Click Create.
Click the dashed upload box on the left. Pick a photo of the panel. The image appears in the centre.
Click + Place Hotspot, then click on a button or switch in the photo. A coloured numbered circle appears. Repeat for every button you'll reference.
Click + Add Action on the left. Give it a label like "Start Equipment". Click the action to open its step editor on the right.
Click + Add Step. Write a bold title (e.g. "Press the green button"). Write a description. Pick an animation (e.g. "Press Button"). Tap the hotspot chip to link this step to the right hotspot.
Repeat for every step in this action. Switch languages with the tabs at the top of each step to translate the title and description into PL / RU / RO.
Click Play in the header to preview. Click your action button. Tap through the steps.
Click Export. The browser downloads a single HTML file with the panel image, all the steps, and all four languages embedded. Drop it on Netlify (or any web host).
Click QR, paste the URL where you hosted the HTML, download the QR image, print it, stick it on the actual equipment.

That's the entire authoring loop. Everything else in this manual is detail.

The welcome screen

The welcome screen appears every time you open the editor. It has three or four big buttons:

Connect a folder — recommended. The editor reads your starter templates from templates/ and auto-saves every panel into panels/ as both a .json (data) and a .html (the deployable player) inside the folder you pick. Works in Chrome and Edge (uses the File System Access API).
Download offline pack — gives you a zip with the editor, starter templates, and READMEs. Unzip somewhere, open editor.html, connect to that folder. You're then fully offline.
Just start editing — in-memory only. Nothing is saved to disk unless you manually Export.
✓ Reconnect to your folder (returning users only) — if you've connected to a folder before, this green button appears and reconnects in one click.

Click the small ? button in the top-right of the editor at any time to reopen the welcome screen.

Connecting a folder

This is the recommended flow. Pick any folder on your PC the first time, and the editor:

Reads templates/colors.json, templates/actions.json, templates/comments.json if they exist. These customise the hotspot colour palette, the action label suggestions in the dropdown, and the per-animation comment presets.
Reads panels/ and lists existing saved panels in the left rail under "Recent Panels" — click any to reopen for editing.
Auto-saves every change you make. Three-second debounce — you stop typing, three seconds pass, the panel saves silently to panels/<id>.json and panels/<id>.html.

Auto-save overwrites without confirmation. If you hand-edit a saved .html file outside the editor and then edit the same panel inside the editor, the editor's auto-save will clobber your hand-edits.

To change the connected folder: click ? in the header to reopen the welcome screen, then pick a new folder. The auto-save timer cancels itself on folder switch so a queued save doesn't leak into the new folder.

Folder layout

your-panels-folder/
├── templates/
│   ├── colors.json          ← your hotspot palette
│   ├── actions.json         ← your common action labels
│   ├── comments.json        ← your favourite step comments
│   └── animations/          ← (v4.1) drop SVGs here
└── panels/
    ├── conveyor-3b.json     ← editable data
    └── conveyor-3b.html     ← deployable player

Building a panel

0. Create the equipment

Click New in the header. Type the equipment name (e.g. "Conveyor Line 3B") — the ID auto-derives below as you type. Click Create. The editor scaffolds the equipment with one panel named "Panel 1" already active. Add more panels via the tab strip above the canvas (see the Multi-panel equipments section).

1. Upload the panel photo

Click the dashed "Click to upload" box in the left rail. Pick a PNG, JPG, or WebP. The photo appears in the centre canvas and gets stored against whichever panel is currently active. Aim for a clear, well-lit, straight-on shot of the panel — the alignment tool can fix mild distortion but a clean photo always works best.

2. Place hotspots

Click + Place Hotspot in the left rail, then click on a button or switch in the photo. A coloured numbered circle appears. To move a hotspot, drag the circle. To resize, drag the small white handle at the bottom-right of the circle. Each hotspot has a colour, label, and opacity — edit them in the "Hotspot Markers" panel on the left.

New hotspots inherit the previous one's size and opacity automatically. Only the colour cycles through the palette. So if you set up the first hotspot exactly how you want it, the next ten will match without further tweaking.

3. Create actions

An action is one operator task — "Start Equipment", "Daily Cleanup", "Emergency Stop". Click + Add Action. Give it a label and pick a colour. The colour is what appears on the operator's home screen as a big tappable button.

4. Build steps inside each action

Click an action to open the step editor on the right. Click + Add Step. Each step has:

Title — bold one-liner the operator reads first.
Description — longer explanation. Two or three sentences max.
Animation — one of 12 baked-in SVG animations (Press Button, Switch Left/Right/Middle, Joystick, Knob Left/Right, Light On/Off, E-Stop Press/Release). Shown beside the title.
Animation comment — optional short tip like "hold for 3 seconds". Pre-populated with a suggestion when you pick an animation; pick a different suggestion from the dropdown or type your own.
Hotspots — tap up to two hotspot chips to link this step to the relevant button(s) in the photo. Linked hotspots pulse during this step.

5. Translate

Each step has language tabs (EN / PL / RU / RO) for the title and description. Click a tab to switch the editor input to that language. Translate the title and description for each language you care about. Untranslated languages fall back to English at runtime.

6. Preview

Click Play in the header. The full-screen play overlay appears with your action home buttons. Click one. Tap through the steps. Esc exits play mode.

Multi-panel equipments (v5)

Many machines have more than one panel — a main control cabinet, a sensor cabinet, an HMI screen, an electrical isolator. From v5 the editor lets one equipment guide span multiple panels, and a single action's steps can move between them ("step 1 on the main panel, step 2 on the sensor cabinet, step 3 back on main").

How the data is shaped

An equipment now contains a list of panels, each with its own image and its own set of hotspots. Actions sit at the equipment level (not the panel level). Each step inside an action says "I live on panel X" and links to hotspots on that specific panel. Old single-panel guides auto-upgrade on load — they become an equipment with one panel called "Panel 1".

The panel tab strip

Above the canvas toolbar you'll now see a row of pill-shaped tabs, one per panel, plus a dashed + Add Panel button at the end. The active tab is highlighted blue. Click another tab to switch — the canvas, the upload zone, the hotspot list, the alignment state all update to that panel. Switching panels never loses data; you're just looking at a different one.

Each tab has two small icons that appear inline:

✎ rename — click to edit the panel name inline. Press Enter to commit, Escape to cancel. The name also commits if you click away.
× delete — removes the panel. You can't delete the last remaining panel (the editor blocks it and suggests clearing instead). If steps were referencing the panel you're deleting, those steps get reassigned to the first remaining panel and their hotspot links are cleared — the editor warns you about this before doing it.

Adding a new panel

Click + Add Panel at the end of the tab strip.
Give it a name (e.g. "Sensor Cabinet"). Press Enter.
The new panel becomes active. The canvas shows an empty "No diagram loaded" placeholder.
Upload an image using the left-rail upload box exactly as you would for the first panel.
Place hotspots — they belong to this panel only, won't appear on the other panels.

The hotspot list on the left always shows hotspots for the active panel only. When you switch panels you'll see the new panel's hotspots. None of them are gone — just hidden from view of the wrong panel.

Building steps that span panels

Open an action's step editor (right rail). Each step now has an On Panel dropdown at the top. When you create a new step it defaults to whichever panel is currently visible in the canvas. To put a step on a different panel:

Open the step.
Change the On Panel dropdown to the panel you want.
The hotspot chips below the step body refresh to show only that panel's hotspots.
Click the chips you want for this step (up to 2).

If a step was already linked to hotspots when you change its panel, those links get cleared (the old hotspot ids don't exist on the new panel). The editor toasts you when this happens so you know to re-pick.

How Play mode looks with multi-panel

When the operator taps through steps, the canvas shows whichever panel image the current step lives on. If the next step is on a different panel, the canvas image fades out (200ms) and the new panel image fades in, then the hotspot dots and bubble render on top. There's a small "⤷ Panel 2: Sensor Cabinet" tag in the bubble's top row whenever the current step is on a different panel from the previous step — it's the one quick visual cue that says "look at a different physical panel now".

For single-panel guides nothing changes — no fade, no panel badge, identical experience to v4.

Exporting

The single exported HTML file now embeds all panel images as base64. File size grows roughly linearly with panel count — a 3-panel guide is about three times the size of a 1-panel guide. Operators still need to load just one URL; everything's in that one file.

The data JSON export now also embeds all panel images so the JSON itself is fully round-trippable — no sidecar PNGs.

Aligning a distorted photo

If your panel photo was taken at an angle, the panel will look like a trapezoid rather than a rectangle. The alignment tool fixes this in one pass.

Upload the photo and decide on the panel boundaries.
Click Align Corners in the canvas toolbar. Four numbered draggable handles appear at the corners of the photo, connected by a yellow dashed quadrilateral.
Drag each handle to a real corner of the panel in the photo (top-left, top-right, bottom-right, bottom-left in clockwise order).
Click Apply. The photo warps into a clean rectangle showing just the panel area, with a small frame of surrounding context preserved.
If you mis-clicked, click Revert Alignment to restore the original. Revert disappears once you've placed your first hotspot — at that point you're committed.

If you'd already placed hotspots before aligning, you'll see a confirmation modal. Aligning resets the hotspot coordinate space so existing hotspots must be cleared. The modal asks before doing this.

Alignment is per-panel from v5 onwards. The original photo and the "Revert Alignment" button track each panel independently — aligning Panel 1 doesn't change Panel 2.

Export & QR codes

Export HTML

Click Export (header) or Export HTML (footer of the right rail). The browser downloads a single <equipment-id>.html file. This file contains:

The full player runtime (no external dependencies)
The panel image embedded as a base64 data URL
All actions, steps, hotspots, and four-language text
All 12 SVG animations

This file is the deployable. Drop it on any static host — Netlify, GitHub Pages, AWS S3, even just a OneDrive shared link. The URL you get is what operators scan.

Export JSON

If you want just the data (not the HTML wrapper), use Data JSON in the right rail footer. You get the panel JSON + a sidecar PNG of the image. Useful for backups or transferring panels between editors.

QR code

Click QR in the right rail footer. A modal appears. Paste the URL where you've hosted the HTML (e.g. https://panels.example.com/conveyor-3b.html). The QR code regenerates as you type. Click ⬇ Download to save the QR as a PNG. Print at a comfortable size (5cm square works on most equipment), laminate, and stick it where operators will see it.

For operators (the deployed HTML)

This is the experience your operators get when they scan a QR code or open the deployed URL:

Home screen — equipment name at the top, big coloured action buttons (one per action you built). Tap the action you need.
Step view — panel photo fills most of the screen with one or two coloured hotspots pulsing on the relevant buttons. A bubble shows the step title, description, animation icon, language tabs. A dashed connector line points from each pulsing hotspot to the bubble.
Language switch — tap EN / PL / RU / RO inside the bubble to switch the displayed language for this step. The choice persists for the rest of the play session.
Navigation — big Back and Next buttons at the bottom. Progress dots show position in the action. Exit returns to the home screen.

The deployed HTML works fully offline once loaded. An operator who scans the QR with a flaky factory wi-fi can still tap through the guide if the first load completes.

Customising templates

When you connect to a folder, the editor reads any of these files if present. Edit them in Notepad and refresh the editor to apply changes.

templates/colors.json

Replaces the default hotspot colour palette. Hex strings only:

["#1a73e8", "#dc2626", "#16a34a", "#d97706", "#7c3aed"]

templates/actions.json

Adds suggestions to the action label dropdown:

[
  {"label": "Start Equipment", "color": "#16a34a"},
  {"label": "Daily Cleanup",   "color": "#2563eb"},
  {"label": "Emergency Stop",  "color": "#dc2626"}
]

templates/comments.json

Extends the per-animation comment suggestions:

{
  "press_btn": ["Press once", "Hold for 3 seconds", "Press until light comes on"],
  "switch_left": ["Move to OFF", "Move to position 0"]
}

Animation keys: press_btn, switch_left, switch_right, switch_mid, joystick, knob_left, knob_right, light_on, light_off, estop_press, estop_release.

Troubleshooting

The Connect Folder button doesn't work

You're on Firefox or Safari. The File System Access API is currently Chrome/Edge only. Use Download offline pack or Just start editing instead. Your work won't auto-save but Export still works.

The editor looks tiny on my phone

The editor is built primarily for desktop. On a phone the layout collapses to a single column with collapsible sections, but if it still doesn't fit, rotate to landscape or use a tablet/PC for authoring. The play view (what operators see) is fully optimised for phone.

QR code shows but won't download

The QR library failed to load — usually a network issue. Refresh the page and try again. If you're on a strict corporate network, the cdnjs CDN may be blocked; in that case use the offline pack which bundles the library.

I uploaded an image and nothing happened

Make sure the file is PNG, JPG, or WebP. HEIC and AVIF aren't supported in all browsers. Convert to JPG first if needed.

My step descriptions disappeared after switching languages

Each language has its own title and description — they're saved per-language. Switch back to the original language tab and your text is still there.

I want to delete a panel from the connected folder

Manually delete the .json and matching .html files from panels/ in your file manager. The editor will refresh the Recent Panels list next time you reconnect.