File Transfer

Introduction

File Transfer is used to download files from an IEC 61850 server. The file transfer function, as implemented by the WinCC OA client, uses MMS services and is format independent, i.e. it can handle any format used by the server.

The WinCC OA client provides detailed information about the status of the ongoing file transfer in the internal data point element _IEC61850_IED.State.FileTransferResponseCode, in the following denoted as State DPE.

Important:
In a redundant WinCC OA project, files are always downloaded to the directory of the project where the currently active IEC61850 driver is running.

Provided Functions

The WinCC OA client provides the following functions:

  • Read directory – gets a list of files available for download.
  • Download file – downloads a specific file.
Note:
Any kind of file transfer requires the exchange of several messages between client and server. A file transfer therefore may take anywhere from between a few milliseconds to a few minutes.

Read Directory

Calling this function sends a read directory request to the server. The server responds by sending a list of files available for download.

The function can be called either from the File transfer panel (see Get list of files) or by setting the respective internal data points (see Check for new files).

The function requires to specify the directory on the server which the client wants to read (see also Destination Path). If you pass a / to the function, the driver will read the directory, which on the server has been configured as the root directory for file services. Defining this root directory is a server configuration issue. It is transparent for the client. Reading the root directory will return a list of all files available for download.

You can read a specific directory on the server by passing the path starting at the file services root directory, e.g.: /anysubdirectory/ will return a list of all files stored in /anysubdirectory/ and all directories below /anysubdirectory/.

Note:
Please note that you also need to pass the trailing "/".

Upon sending the request, the driver writes FILE_READ_DIRECTORY_IN_PROGRESS (100) to the State DPE.

While a file download request is in progress, any other request will be rejected.

The driver writes the list of received file names to the internal DPE _IEC61850_IED.FileTransfer.FileList. File names are written to this DPE using the full path on server side, e.g. \COMTRADE\FRA00001.cfg.

Upon successful completion, the driver writes FILE_DIRECTORY_SUCCESS (0) to the State DPE. In case an error occurs, an appropriate error code is written to the State DPE.

Download File

Calling this function starts the process of downloading a specific file. The driver will send the sequence of requests necessary to download the specified file and will store the file in the specified location on WinCC OA side (see also Destination Path below). In the following, the specified location is denoted as target directory.

Note:
An IEC 61850 server has a directory structure such as any other computer. When storing a downloaded file, the driver will use the file name only, ignoring the full path used on the server, e.g. A file FRA00001.cfg stored as \COMTRADE\FRA00001.cfg on the server will be simply stored as FRA00001.cfg in the target directory on client side.

Upon sending the request, the driver writes FILE_DOWNLOAD_IN_PROGRESS (101) to the State DPE.

While a file download request is in progress, another file download request will be queued by the driver, and read directory requests will be rejected.

Upon successful completion, the driver writes FILE_DOWNLOAD_SUCCESS (51) to the State DPE. In case an error occurs, an appropriate error code is written to the State DPE.

In the target directory, the file which is currently downloaded is opened with the appendix ".MMSdownload". This appendix remains during the download process and is removed upon completion.

Example: When downloading the file FRA00001.cfg, you will see the following file names in the target directory:

  • FRA00001.cfg.MMSdownload => The file FRA00001.cfg.MMSdownload has been opened locally (on client side) for downloading \COMTRADE\FRA00001.cfg from the server. The download of the file is in progress.
  • FRA00001.cfg => The download of the file \COMTRADE\FRA00001.cfg has been successfully completed.

Consider that if you see a file with the ending .MMSdownload in your target directory this can mean that:

  • The file download is in progress.
  • An error has occurred during the file download. In this case the file is corrupted and very likely unusable.

If a file has already been downloaded, the driver will deny another download attempt. If it is necessary to download a specific file anew, please remove or rename the previously downloaded file.

Important:

File download is a service which consumes a lot of resources and puts a high load on all components involved (client, server, network). It needs to be considered that

  • If the file list is long, the server will send it in several segments. That means that even downloading the file list might require the exchange of several messages between client and server.
  • Downloading a large file might require the exchange of several hundred messages between client and server.

For this reason, file service requests must not be sent in too quick succession.

Configuration

Destination Path

This defines the target directory on the client side, i.e. the directory where the downloaded files will be stored. The default directory is <project directory>\data\IEC61850\DR\.

The destination path is device-specific. It is recommended to change the default path to a path specific for the respective device, e.g. <project directory>\data\IEC61850\DR\iec61850_srv\.

Manual File Download

For downloading files manually, please use the File Transfer Panel (System Management > IEC Driver > File Transfer).

Figure 1. File Transfer Panel

Server

Server name
Use this drop-down list to select the IEC 61850 server from which you want to download the files. The server names shown in this list are the names of the IEC 61850 devices configured in your WinCC OA project.

Client Configuration

Destination path
Defines the target directory on client side, i.e. the directory where the files downloaded from the server will be stored(see also Destination Path). Please use the file selector next to the text field for setting the path.

File List

Source path
Defines the path to the directory on the server you want to read. (see also Read Directory).
Get list of files
The list of file names returned by the server will be displayed in the main text field below. The file names are shown using the full path on server side, e.g. \COMTRADE\FRA00001.cfg.
Download selected file
Select any file in the main text field above and click this button. This will download the selected file from the server to the target directory defined by destination path.

Automated File Download

This section provides a guideline how to implement a user application to automatically download files from an IEC 61850 server.

Requirements

The application must meet the following requirements:

  • It must periodically check whether new files are available on the server.
  • The result of this check will be a List of new files, which may or may not be empty.
  • The application must initiate a download for each item of this List of new files,.
  • The application must keep track of correctly downloaded files by holding or dynamically generating a List of downloaded files.
  • The List of downloaded files must store the file names using the full server path, e.g. \COMTRADE\FRA00001.cfg.
  • The application must be able to handle errors. To be able to do this, it must connect to the State DPE. Please consider that the values of this DPE are transient and may be available for only a few milliseconds.

The driver provides two functions, read directory and download file, described under Provided functions. These functions together with the data point interface of the driver can be seen as an API for realizing the automated file download.

Recommended Implementation

Check for New Files

  1. Set the path to the directory you want to read on the server at the internal DPE _IEC61850_IED.FileTransfer.SourcePath.
  2. Set the internal DPE _IEC61850_IED.Command.FileTransfer.ReadDirectory to TRUE. This will initiate the read directory request.
  3. Check the State DPE.
    • After initiating the read request, its value will be FILE_READ_DIRECTORY_IN_PROGRESS (100).
    • When the file list has been downloaded successfully, FILE_DIRECTORY_SUCCESS (0) is written to the State DPE.
      • Read the received list of files from the internal DPE _IEC61850_IED.FileTransfer.FileList.
      • Compare this list with the List of downloaded files. The difference between those lists will be the List of new files.
      • The List of new files must store the file names using the full path on server side, e.g. \COMTRADE\FRA00001.cfg.
    • If an error is reported, the error code is written to the State DPE, nothing is written to _IEC61850_IED.FileTransfer.FileList.
    • Consider:
      • In case of an error, the list stored at _IEC61850_IED.FileTransfer.FileList is the list received from the previous read directory request.
      • If the directory read request fails once, it does not matter, since the application sends this request periodically. If request fails repeatedly, there is most likely a problem with the server and human intervention is required. How to application notifies of this request is a design issue.
Note:
  • It is necessary to set a distinct root directory for each IEC 61850 device configured in WinCC OA, e.g. <project directory>\data\IEC61850\DR\iec61850_srv\.
  • If the value at the State DPE is >= 100, a read directory request is not allowed and will be rejected.
  • The time span between two directory read requests must not be shorter than 4 seconds.
  • Keeping track of which files have been correctly downloaded is in the domain of the user application.
  • Even if your application always reads the same directory of the server, you need to set the source path at _IEC61850_IED.FileTransfer.SourcePath every time before setting TRUE at the internal DPE _IEC61850_IED.Command.FileTransfer.ReadDirectory. The reason for this is that after the last automated check of your application, a read from another directory could have been triggered either manually or by another application.
  • You can read a specific directory on the server. E.g. if you set /COMTRADE/ as the source path, your application would download only this type of fault files automatically. All other files available on the server must then be downloaded manually or by another application. This opens the possibility to check for fault files periodically with higher frequency than for operational logs (e.g. every 4 seconds vs. only once a day).

Download New Files

In case the List of new files is not empty, i.e. new files have been detected on the server, the application must go through this list and request the download for each of these files. For each item of the list, the user application must:

  • Set the file name to the internal DPE _IEC61850_IED.FileTransfer.SelectedFileName. The file name must be set using the full path, e.g. \COMTRADE\FRA00001.cfg.
  • Set the internal DPE _IEC61850_IED.Command.FileTransfer.DownloadFile to TRUE.
  • Check the State DPE.
    • After initiating the download, the value will be FILE_DOWNLOAD_IN_PROGRESS (101).
    • When the file has been downloaded successfully, FILE_DOWNLOAD_SUCCESS (51) is written to the State DPE.
      • If the application holds a List of downloaded files and does not generate this list dynamically, update the List of downloaded files.
      • The application may now request the next item of the List of new files.
    • If an error is reported, the error code is written to the State DPE.
    • Consider that the application must contain a List of error files, i.e. files which have not been correctly downloaded.

Please find further important information on how to proceed in case of a file download error under Files where errors occurred during download.

Note:
  • Downloading a file puts a high load on all components involved (client, server, network). It requires the exchange of at least three messages between client and server but may require the exchange of several hundred messages in case of larger files. Therefore, the download of a file may take anywhere from a few milliseconds to several minutes.
  • If the value of the State DPE is 100, a file download request is not allowed and will be rejected.
  • If the value of the State DPE is 101, the file download request will be queued by the driver.
  • If an error occurs, the driver reports the error to the State DPE. It does not report for which file this error occurs to the internal data point. This can only be seen in the log. For this reason, it is recommended to download the files one by one and not let the driver cue them.

If your application repeats steps 1 and 2 in a loop, i.e. requests several files without waiting for each of them to be downloaded, the driver will queue the requests and automatically download one requested file after the other. This is not recommended however, since error tracking in this case will be harder (see above).

Other File Downloads

Files Where Errors Occurred During Download

In case a file could not be correctly downloaded, the file name must be added to the List of error files. As in the List of new files, the List of error files must store the file names using the full path on server side, e.g. \COMTRADE\FRA00001.cfg.

Scheduling when this List of error files is processed is a configuration issue.

Errors reported at the State DPE can be either protocol-specific errors or distinct file services errors. For protocol-specific errors please see IEC 61850 Client Errors for file services errors please see File Transfer Response Code.

Consider the following:

  • If the error is caused by a general server issue, e.g. in case there is no connection to the server, the application may continue requesting files as soon as the issue has been resolved.
  • If the error occurs with a specific file and happens repeatedly, human intervention is required. How the application notifies the user of this requirement is a configuration issue.
  • In case of an error during file download you should consider two scenarios:
    • The local file has not yet been created: In this case adding the file name to the List of error files is all that needs to be done.
    • The local file has already been created: In this case a, file with the suffix .MMSdownload, e.g. FRA00001.cfg.MMSdownloadexists in the target directory. Regarding a new attempt to download this file, this is of no relevance. The driver will simply overwrite the incorrectly downloaded file and restore its name, to e.g. FRA00001.cfg, after correctly downloading it.
    • If a specific file repeatedly causes a download error, human intervention is required. How the application notifies the user of this requirement is a configuration issue.

Historical Files

If WinCC OAconnects to an IEC 61850 server which has been in service for some time already for the first time, there might be a lot of files available on this server. Downloading such a large number of files must be considered as an engineering issue and must not be done during normal operation.