Configuring CreateScreenshot on SIMATIC WinCC Unified MTP1500

Configuring CreateScreenshot on SIMATIC WinCC Unified MTP1500

The CreateScreenshot system function on the SIMATIC HMI MTP1500 Unified Comfort Panel captures the current screen content and writes it to a file. On Comfort Panels (V15.1 and earlier, WinCC Comfort/Advanced) the function was tightly coupled with the panel's print system, and a "Print to PDF" device was often added in a single configuration step. On WinCC Unified V17/V18/V19/V20, the function behaves differently: it writes a raster file (PNG or JPG) to a Linux-style path, and PDF export is not built in. The runtime does not contain a system print function; PDF generation must be assembled from a CUPS printer, a JavaScript trigger, and a StartProgram call that invokes lp or lpr. The path that the function writes to must be a complete Linux path, not a Windows-style UNC or relative path, and it must point at a mount that the runtime user can write to. This reference describes the exact path conventions, CUPS configuration, and script wiring required to make CreateScreenshot on an MTP1500 produce a usable screenshot on a USB stick, and optionally convert that screenshot into a PDF.

MTP1500 Unified Comfort Hardware and Runtime

The MTP1500 is part of the SIMATIC HMI Unified Comfort family introduced with TIA Portal V17 and expanded through V18, V19, and V20. It runs a Linux-based runtime (based on the SIEMENS Industrial Edge / Yocto distribution) and exposes a configurable set of storage interfaces that the WinCC Unified runtime can write to. The relevant hardware features for screenshot export are summarized below.

CreateScreenshot Function Reference

The system function CreateScreenshot is documented in the official WinCC Unified system functions reference. Per the TIA Portal V20 online help entry "CreateScreenshot (RT Unified)":

• Syntax: CreateScreenshot(StoragePath : String) : Void
• Parameter: StoragePath – complete, fully qualified path including filename and extension.
• Output format is determined by the file extension (e.g. .png, .jpg, .bmp).
• If a file already exists at the target path, it is overwritten without prompt.
• If the target path cannot be accessed (mount missing, permissions, or non-existent directory), an error is reported in the runtime diagnostics and the function returns without writing a file.
• The function is synchronous in V17/V18 and asynchronous in V19/V20 (returns immediately; file appears within 200-500 ms typically).

The official KB "CreateScreenshot – SIMATIC HMI WinCC Unified V19" (ID 109828368) explicitly states: "The system function 'CreateScreenshot' is only available for WinCC Unified Comfort Panel. The system outputs a compiler warning if the function is used on a non-Comfort target."

Problem Symptoms on the MTP1500

Three failure modes are observed in the field:

1. No file is written. The runtime triggers the function on a button press, the HMI does not report an error, and the USB stick contains no new file. Existing alarm logs and trend exports on the same stick work, ruling out a general USB issue.
2. Runtime error in the diagnostics viewer. StoragePath is rejected with a generic "path cannot be accessed" message (HMI event log ID 13100 - 13110 range, depending on firmware).
3. PNG is written, but PDF export is missing. The image is on the USB stick, but the user wanted a PDF (as was trivially possible on Comfort V15 panels by adding a PDF printer).

Root Cause Analysis

The Comfort V15 print system and the Unified runtime print system are completely different. On V15, a "PDF Drucker" was registered through the panel control panel and a system print function was invoked from the project. On Unified:

• There is no system print function in the runtime. The print subsystem is CUPS, and the project has no native hook into it.
• The Printer Configuration entry in the "Apps" menu opens a browser pointing at the embedded CUPS web interface. The page only loads configuration options if the URL is the privileged /admin/ path, not the default / path.
• JavaScript on the panel can call HMIRuntime.Screens.System.CreateScreenshot(path), but cannot directly invoke a print job. A print job must be issued through StartProgram with the CUPS lp client.
• USB mount points on Unified follow the Linux convention /media/simatic/<interface>/, not the Windows-style /usb/ or USB:\ used in legacy Comfort projects.

Storage Path Mapping

The mount points used by the WinCC Unified runtime on the MTP1500 are fixed. Use the values below verbatim.

For a USB stick plugged into the X61 (front) port, a valid full path is:

/media/simatic/X61/screenshot.jpg

Do not include a Windows drive letter, do not use a UNC path, and do not rely on the runtime to create the directory tree. The directory /media/simatic/X61/ is created by the runtime when the USB stick is mounted.

Prerequisites

• SIMATIC HMI MTP1500 Unified Comfort Panel with firmware V17.0.0.3 or later (V18+ recommended).
• TIA Portal V18, V19, or V20 with WinCC Unified option installed.
• Project compiled for the MTP1500 device type (verify in the Devices & Networks editor; the panel must show "Unified Comfort" in the device classification).
• USB stick, FAT32 or ext4, with at least 32 MB free.
• Engineering access to the panel's CUPS admin interface (no separate password on early V17 firmware; V19+ may require the panel's service user).

Configuring the USB Storage Path

1. Insert the USB stick in the front X61 port. Wait for the panel's "USB device connected" notification.
2. On the engineering station, in TIA Portal, open the HMI project for the MTP1500.
3. Open the screen that will host the screenshot button (e.g. Screen_1).
4. Add a button. In the Properties pane, go to Events > Press.
5. From the system function list, select CreateScreenshot.
6. Set the StoragePath parameter to /media/simatic/X61/screenshot.jpg (or .png for lossless).
7. Compile the project and download to the panel.
8. Test the button. The file should appear in the USB root within one second. If it does not, check the runtime event log on the panel under Diagnostics > System Events.

Verifying the Mount on the Panel

If the path is rejected, open the panel's service shell (Settings > Apps > Service) and verify the mount:

ls -la /media/simatic/X61/
mount | grep X61

If the directory is empty or does not exist, the USB stick was not auto-mounted. Re-seat the stick, or check the file system: exFAT on a stick larger than 32 GB may require a firmware >= V18 Update 2 to mount reliably.

CUPS PDF Printer Configuration

The Unified runtime ships with CUPS installed. The default printer list is empty. To add a "Print to PDF" device, the privileged CUPS admin URL must be opened.

1. On the panel, tap Apps on the launcher bar.
2. Open the Printer Configuration tile. The default landing page is the public CUPS root.
3. Change the URL in the browser address bar to http://localhost:631/admin/. The administrative page will load. (The default root URL http://localhost:631/ is read-only; the /admin/ path is the only one that exposes the "Add Printer" form on the panel.)
4. Tap Add Printer. If prompted, supply the panel's service credentials. On firmware V17 / V18 the service user is admin with the password set during initial panel commissioning.
5. Choose Local Printers: CUPS-PDF (Virtual PDF Printer) as the device.
6. Name the printer Virtual_PDF_Printer (or any string that your script can reference). Avoid spaces in the name; the lp command may require quoting if spaces are used.
7. Make: Generic. Model: Generic Color PDF (en) or the equivalent locale variant.
8. Confirm. The printer appears in the CUPS home page and in the panel's Printer Configuration tile.

Scripting PDF Conversion with StartProgram

After the PDF printer is registered, the runtime can convert a screenshot to PDF by invoking lp against the saved PNG. The cleanest approach is to combine CreateScreenshot with a JavaScript function that calls StartProgram with the CUPS command line.

JavaScript on the Button Press

// Function called by the button's "Press" event
export function SaveScreenshotAsPdf() {
    const path = "/media/simatic/X61/screenshot.png";
    HMIRuntime.Screens.System.CreateScreenshot(path);

    // Wait briefly for the file to flush, then submit the print job.
    // The delay is necessary because CreateScreenshot is async on V19/V20.
    setTimeout(function() {
        HMIRuntime.Systems.StartProgram(
            "lp",
            "-d",
            "Virtual_PDF_Printer",
            "-o",
            "output-format=PDF",
            "-o",
            "print-color-mode=color",
            "-o",
            "fit-to-page",
            path
        );
    }, 500);
}

Configuring the Button

1. In TIA Portal, on the button's Press event, choose Add new function > Script and paste the function body above.
2. Compile and download.
3. Test: press the button, wait ~1.5 s, then verify that screenshot.pdf appears in the CUPS spool directory (mounted by default under /var/spool/cups-pdf/<user>/ and on some firmware versions written back to /media/simatic/X61/).

CUPS Spool to USB Directly

By default, cups-pdf writes its output to a spool directory that may not be on the USB stick. To force the PDF to land on the USB, edit /etc/cups/cups-pdf.conf on the panel:

Out /media/simatic/X61
AnonUserName simatic

After editing, restart CUPS:

systemctl restart cups

Verify with a manual test job from the panel shell:

lp -d Virtual_PDF_Printer -o output-format=PDF /media/simatic/X61/screenshot.png
ls -la /media/simatic/X61/

If the PDF is empty or zero bytes, the cups-pdf backend cannot write to the destination. Check directory ownership and the SELinux-equivalent AppArmor profile on the runtime (V19+ enforces a strict AppArmor profile for the CUPS backend; the /media/simatic/X61/ path is whitelisted, but custom paths are not).

Firmware and TIA Portal Compatibility

Verification Procedure

1. Insert a freshly formatted FAT32 USB stick in X61.
2. Press the configured button on the MTP1500.
3. Within 1 second, verify screenshot.jpg exists on the USB root. File size for a 1366x768 capture is typically 200-600 kB for JPG, 1.5-3 MB for PNG.
4. If a PDF step is configured, wait an additional 1-2 seconds and verify screenshot.pdf appears.
5. Open the file on a PC and confirm the screen content is correctly captured. Watch for the system time bar to confirm recency.
6. Verify a second press overwrites the file (no prompt). If the file is not overwritten, check that the runtime user has write permission on the existing file (CUPS will fail to overwrite read-only files).

Troubleshooting Matrix

Common Error Codes

On the CUPS side, the relevant log is at /var/log/cups/error_log on the panel. Look for entries containing Virtual_PDF_Printer and the timestamp of the last print job. A failed job will leave a client-error-document-format-not-supported or client-error-bad-request entry.

Alternative Export Methods

If the CUPS PDF route is too fragile, three alternatives are available without third-party tools:

1. Save as PNG only. Skip the PDF step. PNG is the native CreateScreenshot output and is lossless. The MTP1500 captures at full 1366x768, which is sufficient for documentation purposes.
2. Save with timestamped filename. Use a script to build the filename with Date.now() to avoid overwriting:

   const ts = new Date().toISOString().replace(/[:.]/g, '-');
   const path = "/media/simatic/X61/" + "shot_" + ts + ".png";
   HMIRuntime.Screens.System.CreateScreenshot(path);

3. Network drive export. Configure a network share in TIA Portal under Runtime settings > Network drives. CreateScreenshot will then accept a UNC-equivalent path like /mnt/net/archives/screenshot.png and write the file to a CIFS share. This is the cleanest approach for unattended documentation collection.

Performance and Storage Considerations

A single full-screen capture on the MTP1500 at 1366x768 takes 200-500 ms (V18/V19 runtime; V20 is faster). PNG output is typically 1.5-3 MB; JPG quality-90 is 300-700 kB. The runtime does not delete old screenshots; if the button is pressed repeatedly, the USB stick will fill up. Implement a retention policy in the project (a separate scheduled task that prunes files older than N days from /media/simatic/X61/) for production deployments.

Security Notes

• The CUPS admin interface is bound to localhost:631 and is not externally accessible. Do not change the listen address in /etc/cups/cupsd.conf without considering the operational security impact.
• The service shell that gives access to cups-pdf.conf and the CUPS admin page is protected by the panel's service user password. Keep that password different from the runtime user password.
• Screenshots may contain operator credentials or process values. Treat the contents as confidential and do not export to unencrypted shares.

Best-Practice Checklist

• Use /media/simatic/X61/ for the front USB port, not a relative path.
• Add a 300-500 ms delay between CreateScreenshot and any subsequent file operation to absorb the async write.
• Configure a unique PDF printer name in CUPS; the future default name from Siemens may differ, so hard-coding the name in the script is acceptable as long as the script is reviewed on firmware upgrades.
• Test on the same firmware build that will run in production. Behavior of CreateScreenshot changed between V17 and V20.
• Always test with the same USB stick model that will be used in the field; some sticks with proprietary controllers do not mount reliably on the MTP1500.