Guide: MappSafety SfDomain

[michael.bertsch]

Here are some notes which could be helpfull if you work with SfDomain

1. How to create a List of SafeApplication, SafeCommissioning on CF
2. SfDomainConnect
3. SfDomainTransfer
4. SfDomainCompletion
5. SfDomainExchange
6. SafeOptions
   6.1 SfDomainLoadSafeOptions
   6.2 SfDomainGetSafeOptionXXX
   6.3 SfDomainSetSafeOptionXXX
   6.4 SfDomainSaveSafeOptions
   6.5 Backup of modified Commissioning Files

1. How to create a List of SafeApplication, SafeCommissioning on CF
You can create a List of the Files from the CF-Card by using the DirRead from FileIO Library.

FileHandling.DirRead.pDevice := ADR('CFSafety');
FileHandling.DirRead.pPath := ADR('SafeCommissioning');
FileHandling.DirRead.option := fiFILE;
FileHandling.DirRead.pData := ADR(SafeDomain.DirReadData);
FileHandling.DirRead.data_len := SIZEOF(SafeDomain.DirReadData);
FileHandling.DirRead.entry := 0;
FileHandling.DirRead.enable := 0;

The Files are stored on the C-Partition of the CF-Card

C:\ADDONS\DATA\Safety\SafeApplication
C:\ADDONS\DATA\Safety\SafeCommissioning

Definition of FileDevice
The File Device needed for the Functionblock can be created by PLC-Configuration or via DevLink-Functionblock.

2. SfDomainConnect
EXIT-Task
The SfDomainConnect opens a connection to the SafePLCand is locking operation via other Safety-Services such as the Default HMI. In case of a Transfer of the Application the connection should be relesed.

REPEAT
// Disconnect from SafeDomain
Fb.Connect.Enable := 0;
Fb.Connect.SfDomain := SafeDomainAdr;
Fb.Connect();
UNTIL ((Fb.Connect.Busy = 0 AND Fb.Connect.Active = 0))
END_REPEAT

3. SfDomainTransfer
Progressbar

The Functionblock “SfDomainTransfer” is using its “StatusID” Output to show different states of the Transfer. It can be combined with the “Progress” Output which showes Values from 0 to 100. If you don’t wan’t to see your Progressbar running serveral times from 0 to 100 you must combine both Values to create a longer Progresbar from 0..700.

Fb.Transfer(Execute := 1);
// Progress Update for Hmi
CASE Fb.Transfer.StatusID OF
sfDOM_INF_TRAN_DATA: SafeDomain.Transfer.ProgressStep := 1;
sfDOM_INF_TRAN_VALIDAPP: SafeDomain.Transfer.ProgressStep := 2;
sfDOM_INF_TRAN_DOWNAPP: SafeDomain.Transfer.ProgressStep := 3;
sfDOM_INF_TRAN_VALIDCOMM: SafeDomain.Transfer.ProgressStep := 4;
sfDOM_INF_TRAN_DOWNCOMM: SafeDomain.Transfer.ProgressStep := 5;
sfDOM_INF_VALID_TABLES: SafeDomain.Transfer.ProgressStep := 6;
ELSE SafeDomain.Transfer.ProgressStep := 0;
END_CASE
SafeDomain.Transfer.ProgressValue := Fb.Transfer.Progress +
(SafeDomain.Transfer.ProgressStep * 100);
// As there are some gaps with StatusID 0 in between we only update the values if they
increase
IF SafeDomain.Transfer.ProgressValue > SfDomain.Transfer.ProgressValue THEN
SfDomain.Transfer.ProgressValue := SafeDomain.Transfer.ProgressValue;
END_IF
IF SafeDomain.Transfer.ProgressStep > SfDomain.Transfer.ProgressStep THEN
SfDomain.Transfer.ProgressStep := SafeDomain.Transfer.ProgressStep;
END_IF

After the transfer has finished the SafePLC will make a Restart. Considering this it makes sens to add a additional Step via the Application to show the progressbar for a longer time. Once the Progressbar is finished the SafePLC has had allready some time for its restart.

Fb.TONWait(IN:=1);
// Progress Update for Hmi (no StatusIDs)
SfDomain.Transfer.ProgressStep := 7;
SfDomain.Transfer.ProgressValue := SfDomain.Transfer.ProgressStep * 100 +
REAL_TO_UDINT(TIME_TO_REAL(Fb.TONWait.ET) / TIME_TO_REAL(Fb.TONWait.PT) * 100);
IF Fb.TONWait.Q THEN
// Reset Timer
Fb.TONWait(IN:=0);
// Next Step
SafeDomain.Step.Redo := 1;
SafeDomain.Step.Step := TSafe_SFDOMAIN_STEP_TRANSFER_D0;
END_IF

The Texts for the Visu can be created like this.

4. SfDomainCompletion
Progressbar

The Functionblock “SfDomainCompletion” is using its “StatusID” Output to show different states of the Transfer. It can be combined with the “Progress” Output which showes Values from 0 to 100. If you don’t wan’t to see your Progressbar running serveral times from 0 to 100 you must combine both Values to create a longer Progresbar from 0..400.

Fb.Completion(Execute := 1);
// Progress Update for Hmi
CASE Fb.Completion.StatusID OF
sfDOM_INF_COMP_APP: SafeDomain.Completion.ProgressStep := 1;
sfDOM_INF_COMP_COMM: SafeDomain.Completion.ProgressStep := 2;
sfDOM_INF_COMP_SETUPMODE: SafeDomain.Completion.ProgressStep := 3;
END_CASE
SafeDomain.Completion.ProgressValue := (SafeDomain.Completion.ProgressStep * 100);
IF SafeDomain.Completion.ProgressValue > SfDomain.Completion.ProgressValue THEN
SfDomain.Completion.ProgressValue := SafeDomain.Completion.ProgressValue;
END_IF
IF SafeDomain.Completion.ProgressStep > SfDomain.Completion.ProgressStep THEN
SfDomain.Completion.ProgressStep := SafeDomain.Completion.ProgressStep;
END_IF

After the completition has finished the SafePLC will make a Restart. Considering this it makes sens to add a additional Step via the Application to show the progressbar for a longer time. Once the Progressbar is finished the SafePLC has had allready some time for its restart.

Fb.TONWait(IN:=1);
// Progress Update for Hmi (no StatusIDs)
SfDomain.Completion.ProgressStep := 4;
SfDomain.Completion.ProgressValue := SfDomain.Completion.ProgressStep * 100 +
REAL_TO_UDINT(TIME_TO_REAL(Fb.TONWait.ET) / TIME_TO_REAL(Fb.TONWait.PT) * 100);
IF Fb.TONWait.Q THEN
// Reset Timer
Fb.TONWait(IN:=0);
// Next Step
SafeDomain.Step.Redo := 1;
SafeDomain.Step.Step := TSafe_SFDOMAIN_STEP_COMPLETE_D0;
END_IF

The Texts for the Visu can be created like this.

5. SfDomainExchange
Progressbar

The Functionblock “SfDomainExchange” is using its “StatusID” Output to show different states of the Transfer. It can be combined with the “Progress” Output which showes Values from 0 to 100. If you don’t wan’t to see your Progressbar running serveral times from 0 to 100 you must combine both Values to create a longer Progresbar from 0..200.

Fb.Exchange(Execute := 1);
// Progress Update for Hmi (no StatusIDs)
SfDomain.Exchange.ProgressStep := 1;
SfDomain.Exchange.ProgressValue := (SfDomain.Exchange.ProgressStep * 100) + 50;

After the exchange has finished the SafePLC will make a Restart. Considering this it makes sens to add a additional Step via the Application to show the progressbar for a longer time. Once the Progressbar is finished the SafePLC has had allready some time for its restart.

Fb.TONWait(IN:=1);
// Progress Update for Hmi (no StatusIDs)
SfDomain.Exchange.ProgressStep := 2;
SfDomain.Exchange.ProgressValue := SfDomain.Exchange.ProgressStep * 100 +
REAL_TO_UDINT((TIME_TO_REAL(Fb.TONWait.ET) / TIME_TO_REAL(Fb.TONWait.PT)) * 100);
IF Fb.TONWait.Q THEN
// Reset Timer
Fb.TONWait(IN:=0);
// Reset Progress
SfDomain.Exchange.ProgressStep := 0;
SfDomain.Exchange.ProgressValue := 0;
// Next Step
SafeDomain.Step.Redo := 1;
SafeDomain.Step.Step := TSafe_SFDOMAIN_STEP_SEQ;
END_IF

The Texts for the Visu can be created like this.

6. SafeOptions
SafeOption ID
Die SafeOptionID is required to work with the Functionblocks of the SafeDomain-Library in regards to Safe Commissioning Options.

SafeDesigner
This SafeOptionID can be found in the SafeCommissioning File in SafeDesigner

Automation Studio
This SafeOptionID can be found in the SafeCommissioning File in Automation Studio.
If you open the Commissioning File with a Texteditor you can see the values in the xml-File.

Automation Studio Hilfe
In the Automation Studio Help you can find a Description for the Syntax of the SafeOptionID.

6.1 SfDomainLoadSafeOptions
If the SafeDomain gets disconnected (SfDomainConnect.Active=FALSE), after you loaded the SafeOptions with the Functionblock “SfDomainLoadSafeOptions”, the data is discard in memory. After the next Connect you have to reload the Data from the OptionsFile before you can conntinue editing.

6.2 SfDomainGetSafeOptionXXX
If a SafeOptionID is marked as Visible=FALSE in the Commissioning File. You will get this error from the Functionblock, if you try to access it.

6.3 SfDomainSetSafeOptionXXX
If a SafeOptionID is marked as ReadOnly=TRUE in the Commissioning File. You will get this error from the Functionblock if you try to access it.

6.4 SfDomainSaveSafeOptions

• The CRC will change on every Save-Command. This is due to the fact that there is a timestamp in the file and it will change during Save-Command.
• It is possible to use a different name than the loaded file had. “Save As” is possible, it will create a new File on the CF-Card.
• You need at least one Commissioning file which is on the CF-Card to use the Save-Command, becuase you have to Load a File in advance. If there is no File Loaded you get this error message.

6.5 Backup of modified Commissioning Files
With the FileCopy Function from FileIO-Library you can Copy the Commissioning files from the PLC to an external Storage. This can be used to create an Im-/Export on the PLC.
There are some hints about writing to the c-Partition in the AS-Help. But it is still possible.

File Copy Beispielaufruf

// FileCopy
Fb.FileCopy.pSrcDev := ADR('CFSafety');
Fb.FileCopy.pSrc := ADR('SafeCommissioning/SCFile.sfopt');
Fb.FileCopy.pDestDev := ADR('Backup');
Fb.FileCopy.pDest := ADR('SCFile_Backup.sfopt');
Fb.FileCopy.option := fiOVERWRITE;
Fb.FileCopy(enable := 0);

[rafael.laury]

Hi @michael.bertsch, thanks for this in-depth guide, very helpful! I have a quick question/comment on the SfDomainTransfer. I noticed in the Help that it states that transferring is only possible when the SafePLC is in Setup mode ( B&R Online Help ):

A customer attempted to transfer the SafeAPPLICATION without doing this, and they saw errors in the Logger similar to those that show up when a SafeKEY has been formatted. They saw that after rebooting the SafePLC, the program finished transferring successfully. My question is: why would the transfer complete after a reboot? Does it automatically go into Setup mode after a restart?

I recommended to the customer to add the following ST code (see below, found in an internal knowledge base article) to force the SafePLC into Setup mode using the SfDomainControl function block and then check to make sure it has transitioned to Setup mode using the SfDomainInfo function block before transferring, see below. They have not confirmed this is working, but I wanted to mention it here in case you want to add a note to your guide on this point.

//////// TRANSFER TO SAFELOGIC ////////
COMM_STEP_ACT_SETUP_MODE:
	SfDomainControl_0.ControlCommand := sfDOM_ACT_SETUP_MODE;
	SfDomainControl_0.Execute := TRUE;
	IF SfDomainControl_0.Done THEN
		SfDomainControl_0.Execute := FALSE;
		CommStep := COMM_STEP_CHECK_SETUP;
	ELSIF SfDomainControl_0.Error THEN
		CommStep := COMM_STEP_ERROR;
	END_IF
	
COMM_STEP_CHECK_SETUP:
	SfDomainInfo_0.Execute := TRUE;
	IF SfDomainInfo_0.Done THEN
		SfDomainInfo_0.Execute := FALSE;
		SafeDomainInfo := SfDomainInfo_0.Info;
		IF SafeDomainInfo.Status.SetupModeActive THEN
			CommStep := COMM_STEP_TRANSFER_SAFECOMM;
		ELSE
		END_IF
	ELSIF SfDomainInfo_0.Error THEN
		CommStep := COMM_STEP_ERROR;
	END_IF
	
COMM_STEP_TRANSFER_SAFECOMM:
	SfDomainTransfer_0.SafeCommFilePath := SafeCommFile;
	SfDomainTransfer_0.Execute := TRUE;
	IF SfDomainTransfer_0.Done THEN
		SfDomainTransfer_0.Execute  := FALSE;
		CommStep := COMM_STEP_IDLE;
	ELSIF SfDomainTransfer_0.Error THEN
		CommStep := COMM_STEP_ERROR;
	END_IF

[valerio.manenti]

Interesting note Rafael, in my demo (I used mapp Safety 6.4.1 release) with X20SLX811 (where basically I followed the Program example in the Help) I didn’t call SfDomainControl FUB and I was able to transfer the safe application + commissioning file with no issue.
Ciao

Valerio

[michael.bertsch]

Hello,

Good notes, about some additional details of the Transfer-Functionblock.

If we read the second sentence of the Hint in AS-Help, you can explain the behaviour.

“If the SafePLC is not in SetupMode the SafeKey will be formated before the Transfer”.

If the SafeKey is formated the SafePLC will enter the SetupMode automaticaly after Reboot.
This can also be observed if you call the special Funtionblock to Format the SafeKey. Or if you Format the SafeKey with the HMI or Control Button on SafePLC.
With an empty SafeKey the SetupMode is active.

With the Default HMI the Button for Transfer is locked until SetupMode is enabled. With the use of the Functionblock i think this step is optional.
If you only want to change a Commissioning File and not change the SafeApplication you have to consider this, and enable the SetupMode in advance.

---

I am busy for a few days. I may think about how this can be integrated to the guide.

Greetings
Michael