Automap4 Operator Guide

This guide explains the automap4 main window, menus, and the standard workflow for PRBS identification, closed-loop control, recording, and reporting. For a full commissioning runbook, see Help → Tuning Procedure (F5) in the application.

Top Toolbar / Status Bar

Figure 1: automap4 main window (dark theme).

Primary control buttons

PRBS / Start PRBS / Stop PRBS (Ctrl+Space) — Starts or stops PRBS identification. When active the status badge shows PRBS ACTIVE. The mapping progress bar is orange while learning and turns green when quality reaches the control threshold; from that point the CD control button reads “Stop PRBS & enable control” for a direct hand-over.

CD control is disabled / CD control is allowed / Supervisory ON — Toggles closed-loop CD control. Enabled once mapping progress reaches the configured threshold (default 90%). When control is enabled with “Auto-tune controller when enabling control” checked, the controller derives its R/S tuning from the learned model — verify the derived values in Mapping Info (Ctrl+I).

Record / Stop — Starts or stops recording scan data to a CSV file (plus a companion .npz archive). The default filename depends on the current mode: tuning_log.csv during PRBS, control_log.csv during control, running_log.csv when idle.

Status badges

Connected / Disconnected — ZMQ connection state to machinedriver.py or modelstdcom.py.

IDLE / PRBS ACTIVE / CONTROL — Current operating mode.

Map: xx% — Effective mapping progress across all actuator zones.

Transport delay scans — Estimated or overridden transport delay in scans.

Scan number — Count of completed profile scans.

Figure 2: File menu.

Menu Reference

File

Save Mapping As... (Ctrl+S) — Saves the current learned mapping, shrinkage model, and controller settings to a .npz grade file.

Figure 3: Preferences dialog.

Save Grade (Ctrl+Shift+S) — Overwrites the currently loaded grade file with the latest mapping and tuning, e.g. after closed-loop refinement. The grade name is recorded on load or save and appears in the CSV log and report headers.

Load Mapping... — Loads a previously saved grade or mapping file.

Preferences... (Ctrl+,) — Opens the settings dialog.

Exit — Closes automap4.

Preferences dialog

Machine Configuration:

• Headbox width — Physical headbox width in millimetres.
• Actuator width — Width of one dilution actuator in millimetres.
• Response window multiplier — Half-width multiplier used during PRBS correlation (default 2.0).
• Control edge ignore — Number of databoxes ignored at each edge during supervisory control (default 25).
• Machine speed — Nominal machine speed in m/min, used for transport-delay display.
• Paper length — Paper path length from headbox to scanner in metres.
• Max databoxes / Max actuators — Maximum array sizes to accept.

General Settings:

• Stale scan timeout — Seconds without a scan before automap4 pauses identification/control.
• PRBS amplitude — Size of the {-1,0,1} PRBS moves in actuator units.
• ZMQ bind host/port — Where automap4 listens for machinedriver/modelstdcom connections.
• STEC host/port — Reserved for future STEC integration.

Figure 4: Grades menu.

Figure 5: Control menu.

• Edge availability — Whether left and/or right sheet-edge data is available.
• Wander frequency detect — Enable FFT-based sheet-wander detection.

Figure 6: View menu.

• Wander reliability threshold — Confidence level required before wander feed-forward activates.
• Refine mapping from control moves — Closed-loop identification that updates the model during control.
• Transport delay override — Force a fixed transport delay in scans; -1/0 means auto-estimate from PRBS.

Grades

• Use measured sheet edges for S-curve — Sizes the initial shrinkage model from the scanner's measured sheet edges (default on).

Controller Tuning:

• Q / R / S weights — Objective weights for target tracking, move suppression, and smoothing. R and S are derived automatically when auto-tune is enabled.
• Auto-tune controller when enabling control — Derives R from the measured process gain (g_dc) and S from the learned response width each time control is switched on. Q is kept as the operator's noise preference.
• Control aggressiveness — Single tuning knob α (default 0.6). Higher values give braver control moves; saved with the grade file.
• Use simple-zone control — Controls the 96-zone mapped BWT profile instead of the full databox profile.
• Tapered edge weighting — Linearly ramps control weight at the sheet edges instead of a hard on/off edge-ignore mask.
• Integral gain / decay / max — Slow integral correction for persistent profile error. Set the gain to 0 when edge detection is noisy (Thailand UTP2 recommendation).
• MPC horizon — Disabled; the controller is deliberately single-step with dead-time throttling.

The Preferences dialog also has two preset buttons: “Reset to PRBS defaults” loads the lab-validated identification settings, and “Reset to CD Control” loads the recommended control-mode settings. Presets change run-mode settings only — machine geometry, connections, and grade tuning are untouched, and nothing is applied until OK is clicked. The dialog is scrollable; OK/Cancel stay pinned at the bottom.

The Grades menu lists all grade_*.npz files found in the configured grade directory. Selecting one loads it immediately. Use Refresh to rescan the directory. Grade files store a complete mapping snapshot and can be copied between machines. File → Save Grade (Ctrl+Shift+S) overwrites the active grade, and when control is stopped after closed-loop refinement automap4 offers to update the loaded grade so the improved mapping is kept. A grade loaded before the first scan is preserved exactly — it is no longer overwritten by fallback curves on the first scan.

Control

Toggle PRBS (Ctrl+Space) — Starts or stops identification. PRBS cannot be started while supervisory control is active.

Toggle Control (Ctrl+C) — Enables or disables closed-loop supervisory control.

Figure 7: Help menu.

Toggle Recording (Ctrl+R) — Starts or stops CSV/NPZ logging.

View

Profile Chart / Actuator Chart — Show or hide the corresponding chart panels.

Manual Bump — Show/hide the manual bump bar for selecting zones and applying setpoint overrides.

Log Panel — Show/hide the Event Log panel where print messages appear.

Theme — Switch between Dark, Light, and Solar colour themes.

CSV Report... — Loads a recorded CSV and shows a printable HTML table summary.

Generate Field Report (PDF)... — Creates a professional PDF report from a recorded CSV.

Mapping Info... (Ctrl+I) — Shows mapping quality, controller tuning, and transport-delay estimates.

Figure 8: Mapping & Control Info dialog.

Mapped Actuator Profile — Shows the two mapped 96-zone BWT profiles (simple zone average and PRBS-weighted) together with the actuator feedback bar chart.

Mapping Heatmap — Visualises the learned mapping matrix; empty-state placeholder shown until mapping data is loaded.

Wander Trend — Opens a chart of sheet wander over time.

2-Sigma Trend — Opens a chart of profile 2-sigma over time.

Help

Playback Help (F2) — Overview of replaying recorded logs in the office.

ZMQ Playback Guide (F3) — Step-by-step guide for direct ZMQ playback.

Save Machine Run Help (F4) — Operator guide for recording and sending site logs.

Tuning Procedure (F5) — Complete operator runbook from machine setup through PRBS to steady control, including a rising-2σ troubleshooting checklist and a quick-reference of what each tuning knob does.

Context Help (F1) — Opens a short help dialog from the Wander Trend, 2-Sigma Trend, Mapped Actuator Profile, and Mapping Heatmap windows.

View Todo List — Shows the project todo list.

Help Qt / About Qt — Qt framework version information.

Setting up machinedriver.py

Figure 9: machinedriver main window.

machinedriver.py is the bridge between the real paper machine (via STEC/Multiverse) and automap4 (via ZeroMQ).

1. Launch machinedriver.py on the same PC or on a PC that can reach both the STEC server and automap4.

2. In the Connection group enter the ZMQ host/port where automap4 is listening (default automap4 port is 5555) and the STEC host/port for the Multiverse server.

Figure 10: machinedriver Connection Settings dialog.

3. Open the Subscription Mapping table and map each field to the correct STEC subscription name:

Figure 11: machinedriver Subscription Mapping table.

• actuator_positions — direction to_zmq
• actuator_setpoints — direction from_zmq
• profile — direction to_zmq
• left_edge / right_edge — direction to_zmq
• machine_speed — direction to_zmq

4. Click Save. machinedriver will auto-connect to automap4 and start forwarding scans.

5. Use the Profile Orientation checkboxes if the scanner orientation needs reversal or if edges should be auto-computed from the profile.

PRBS Identification Procedure

PRBS teaches automap4 the mapping between each actuator and the profile response.

1. Connect to the machine and wait for the status bar to show Connected and IDLE.

2. Verify machine configuration in Preferences (headbox width, actuator width, machine speed, paper length). The “Reset to PRBS defaults” preset loads the recommended identification settings.

3. Click PRBS / Start PRBS (or press Ctrl+Space). The mode badge changes to PRBS ACTIVE.

4. If recording is not already active, click Record; the default name will be tuning_log.csv.

5. Let PRBS run until the progress bar turns green (control threshold, default 90%); ~99% gives the best model. Check Mapping Info (Ctrl+I): response width, gain, and transport delay should be plausible for the machine.

6. Stop PRBS (or click “Stop PRBS & enable control” to go straight to closed-loop control). automap4 will ask whether to save the mapping. Click Save and choose a meaningful grade name, e.g. grade_site_line1.npz.

7. Stop recording if it is still running. You now have tuning_log.csv, tuning_log.npz, and the grade file.

Closed-Loop Control Procedure

1. Load the grade saved from PRBS (Grades menu or File -> Load Mapping).

2. Wait until the status bar shows CD control is allowed and Map: ~99%. The “Reset to CD Control” preset loads the recommended control-mode settings.

3. Click the CD control button (or press Ctrl+C). The first time you do this manually, a dialog asks whether to record the first N scans to control_log.csv.

4. Click OK to record, choose or accept control_log.csv, and edit the scan count if desired. automap4 will auto-stop recording after that many scans.

5. The mode badge changes to CONTROL. The actuator chart will show setpoints moving as the controller flattens the profile. With auto-tune enabled, R/S are derived from the learned model when control starts — verify the derived tuning in Mapping Info (Ctrl+I).

6. To stop control, click the CD control button again or press Ctrl+C. When control stops, automap4 offers to save any mapping refined during control back to the loaded grade — choose Yes to keep the improvements.

Recording to CSV / NPZ

Click Record to start logging. The default filename depends on the current mode:

• PRBS active -> tuning_log.csv (+ tuning_log.npz)
• Control active -> control_log.csv (+ control_log.npz)
• Idle / baseline -> running_log.csv (+ running_log.npz)

The CSV contains one summary row per scan. The NPZ contains the full profiles, actuator positions, setpoints, edges, machine speed, and a final mapping snapshot. Both files must be kept together and share the same basename.

Building a Field Report PDF

1. Select View -> Generate Field Report (PDF)...

2. Choose the recorded CSV file (tuning_log.csv, control_log.csv, or running_log.csv).

3. Choose where to save the PDF. The default name matches the CSV basename.

4. automap4 builds a professional PDF containing mapping heatmap, quality distribution, 2-sigma trend, wander trend, and recommendations.

5. The PDF can be emailed, printed, or archived alongside the CSV/NPZ files.

End of guide