Creating Files on CF Card with SIMOTION Scout Runtime Functions

Engineer's field reference for the SIMOTION Scout runtime file system library (available since Scout V4.4). Covers CF card file creation, CSV writing, the full set of _file* system functions, error handling with _getStateOfFile, and downstream TCP transport to a PC or Excel. Use this document when you need to log axis states, recipe data, or any 2D array of process values to a non-volatile medium on a SIMOTION D4x5 / C240 / P320 platform.

1. When to Use the Runtime File API

SIMOTION controllers expose a DOS-like file system on the CompactFlash card (D4x5) or the SSD/HDD storage (C240, P320, P350). The runtime file API is the right tool when:

• You need a low-level, programmatic CSV/TXT writer inside the controller, with no extra HMI or WinCC tag logging required.
• You want to capture data only on the controller and pull it later (replacement recipes, fault snapshots, axis traces).
• You are building a small to medium data set (a few hundred kB up to tens of MB). For very high-rate streaming, prefer the trace or a buffered Ethernet producer instead.

If the goal is real-time visualisation, use WinCC / TIA Portal HMI tags. If the goal is continuous 1 kHz data acquisition, use the SIMOTION trace and export via SCOUT. The runtime file API is best for event-driven logging, history archives, and recipe management.

2. Prerequisites and Compatibility

3. The File System Function Library

The library exposes the following system functions. All are declared in the SIMOTION system library and may be called from any cyclic or sequential task with the correct priority.

For directory creation, the related _directoryPathCreate function is available in V4.5+.

4. Project Setup in Scout

1. Open the SIMOTION project in Scout, select the controller in the project tree.
2. Add a new program source (ST) under Programs → Sources, for example fb_FileLogger.
3. Declare an FB instance, for example instFileLogger, in the unit's data block.
4. Insert the FB call into a suitable task. The BackgroundTask is the safe default for low-rate logging. For sub-millisecond determinism, use a synchronous IPO task (only if writing is rare and bounded).
5. Compile and download. Verify the device's CF card is recognised in Target system → Diagnostics → File system.

5. Writing a CSV File: Step-by-Step

Typical use case: capture a 6-column by 500-row process matrix on a state change (for example, a recipe change or a fault) and persist it as DATA.CSV on the CF card for offline analysis. The approach is identical for a 1-D array or a struct-of-arrays, only the loop body changes.

5.1 Declaration block

FUNCTION_BLOCK fb_CsvLogger
VAR
    hFile        : DINT;        // file handle
    sPath        : STRING[255]; // full path incl. filename
    sLine        : STRING[255]; // single CSV row buffer
    nRow         : DINT;        // loop index
    nCol         : DINT;        // column index
    nBytes       : DINT;        // bytes written per line
    nState       : DINT;        // return of _getStateOfFile
    bBusy        : BOOL;
    bDone        : BOOL;
    bError       : BOOL;
    nErrorCode   : DINT;
END_VAR
VAR CONSTANT
    ROWS         : DINT := 500;
    COLS         : DINT := 6;
    SEPARATOR    : STRING[1] := ';';
    CRLF         : STRING[2] := '$R$N';  // CR LF, depends on locale
END_VAR

5.2 Open and write header

// Compose path: /CF_CARD/LOG/<timestamp>.CSV
sPath := '/CF_CARD/LOG/DATA.CSV';

// Probe: do not overwrite an existing file in append mode without checking
nState := _getStateOfFile(sPath := sPath);

IF (nState = 0) THEN
    // file does not exist - create new and write header
    hFile := _fileOpen(sPath := sPath, nMode := 'w');
ELSIF (nState = 1) THEN
    // file exists - append
    hFile := _fileOpen(sPath := sPath, nMode := 'a');
ELSE
    bError := TRUE;
    nErrorCode := nState;
    RETURN;
END_IF;

IF (hFile <= 0) THEN
    bError := TRUE;
    nErrorCode := hFile;
    RETURN;
END_IF;

bBusy := TRUE;
_fileWriteLn(hFile := hFile, sString := 'Col1;Col2;Col3;Col4;Col5;Col6');

5.3 Write the 6 × 500 data block

FOR nRow := 1 TO ROWS DO
    sLine := '';
    FOR nCol := 1 TO COLS DO
        sLine := CONCAT(sLine, REAL_TO_STRING(aData[nRow, nCol]));
        IF (nCol < COLS) THEN
            sLine := CONCAT(sLine, SEPARATOR);
        END_IF;
    END_FOR;
    nBytes := _fileWriteLn(hFile := hFile, sString := sLine);
    IF (nBytes < 0) THEN
        bError := TRUE;
        nErrorCode := nBytes;
        EXIT;
    END_IF;
END_FOR;

5.4 Close and signal completion

_fileClose(hFile := hFile);
bBusy := FALSE;
IF (NOT bError) THEN
    bDone := TRUE;
END_IF;

5.5 State machine overview

6. Reading and Appending

To resume a previous log or pre-load parameters, use _fileOpen with mode "r" and a sequential _fileReadLn loop until the function returns 0 or a negative code.

hFile := _fileOpen(sPath := '/CF_CARD/LOG/PARAMS.CSV', nMode := 'r');
IF (hFile > 0) THEN
    WHILE (_fileReadLn(hFile := hFile, sString := sLine) > 0) DO
        // parse sLine, populate variables
    END_WHILE;
    _fileClose(hFile := hFile);
END_IF;

For random access (for example, patching one record out of 10,000), use _fileSetPosition to seek to an absolute byte offset, then _fileWrite / _fileRead. Records must be fixed length or the position must be computed from an index table.

7. Error Handling and State Codes

Always wrap file operations in a state machine and check return values. The exact numeric codes returned by _getStateOfFile and the file functions are version-dependent; treat the categories below as canonical:

Mirror every _fileOpen with a guaranteed _fileClose in a finally-like state, otherwise the next open will fail because of the leaked handle. A simple pattern is to use a state variable eStep with cases IDLE, OPEN, WRITE, CLOSE, DONE, ERROR.

8. File Size, Performance, and Power Loss

• CF card write latency on a D4x5 is typically 1 to 8 ms per block, but can spike to >100 ms on heavily fragmented or near-full cards. Buffer a 4 kB block in ST and call _fileWrite once per block, not per row.
• File system type is FAT16 or FAT32 (per SIMOTION). Maximum single file size is 2 GB (FAT16) or 4 GB - 1 B (FAT32). 500 rows of 6 doubles with header is well under 100 kB.
• On power loss the FAT may be inconsistent. Add a small header record (sequence number, checksum) and an integrity stamp written after _fileClose in a separate marker file (e.g. DATA.CSV.OK) so the PC importer can detect partial writes.
• Do not log at the IPO/IPO_2 task level. Use BackgroundTask (default 1× or 8× base) or a slow ServoSynchronousTask to avoid overruns.

9. TCP Transfer to a PC or Excel

The runtime file API stores the data locally. To move it to a PC:

1. Direct read via Scout. Open the controller online, navigate to Target system → File system, browse the CF card, and copy the file to the engineering station.
2. FTP or SMB share. SIMOTION D controllers with the appropriate firmware option support FTP; consult the controller manual for the exact firmware function block. Mount a shared folder on the engineering PC and use _fileCopy to push the file across.
3. Custom TCP. Program a TCP server on the SIMOTION side (using the TCP / UDP system function blocks) and a client on the PC (a .NET, Python, or LabVIEW application). Stream the file in 1 kB chunks after _fileOpen with mode "r". The PC client writes the stream directly to .csv and opens it in Excel without any format conversion - Excel interprets the ; separator when launched with the right locale, or via Data → From Text/CSV.
4. Web server / OPC UA. On SIMOTION D455-2 with OPC UA server option, expose the latest log file as a method that returns a ByteString.

For a robust upload, send a small JSON or CSV header containing the file name, size, and a CRC, then the raw bytes. The PC can then verify integrity before deleting the file on the controller via the same TCP channel.

10. Diagnostics and Field-Proven Caveats

11. Integration with WinCC and TIA Portal

When the project is part of a TIA Portal V17 / V18 build with the SIMOTION SCOUT TIA add-in, the file system functions remain identical. The CF card appears as a node of the SIMOTION device. Recommended integration:

• Expose a trigger tag (BOOL) from WinCC that calls the FB instance via the connection configured in Device configuration → Communication.
• Display the resulting file size as an HMI tag by reading FILE_SIZE via the standard diagnostics screens.
• After upload to the PC, archive the file under a WinCC Audit or a SQL-backed tag logging database, in line with the plant's compliance regime.

12. Quick-Reference Checklist

• [ ] Scout version ≥ V4.4 installed and matched to the controller's RT version.
• [ ] Target directory created (use _directoryPathCreate or the Scout file browser).
• [ ] Industrial-grade CF card inserted, write-protect tab off, <80% full.
• [ ] STRING buffers declared as STRING[255] or larger.
• [ ] Mode string spelled correctly ("r", "w", "a", with the leading and trailing quotes in the literal).
• [ ] _getStateOfFile called before _fileOpen when overwriting is undesirable.
• [ ] Every _fileOpen is paired with a _fileClose on a dedicated state.
• [ ] Logging task is the BackgroundTask or a slow synchronised task, never the fast Servo.
• [ ] Integrity stamp file written after _fileClose to detect power-loss truncation.
• [ ] TCP/FTP transfer path tested end-to-end before the first production shift.

For a complete cross-reference of the function block set, open the Scout F1 help, navigate to System functions → File system. The Siemens Industry Online Support entry SIMOTION communication & programming (entry 102754925) is the umbrella document for related runtime libraries and is regularly updated when new Scout versions ship.

Frequently Asked Questions