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

[Omer_Vaserman]

Hello,

I have a question regarding SfDomainConnect function: what should be the UserName and Password, please?

I’ve assumed that Password should be equal to Safety password, but didn’t find any mentioning of UserName.

Empty UserName causes the error sfDOM_ERR_CONN_CHECKINPUT (-1073552099) - Username or password too long or no username given.

Any other UserName causes the error sfDOM_ERR_CHECK_AUTH (-1073552128) - User authentification failed: Username/password combination invalid.

Thanks a lot

[michael.bertsch]

Hello,

The SfDomainConnect function Requires same Username and Password combination like the defaul HMI.

For MappSafety 4.x it is a User with the Role defined in the Settings.sfcfg File.

For MappSafety 6.x it is a User with the Role defined in the Settings.sfcfg File or the Default Role BR_SafetyAdmin

A users can be created in the AccessAndSecurity Section of Automation Studio.
Username and Password can be selected by the Developer.

Greetings
Michael

[Omer_Vaserman]

Hi again, after defining the Users and Roles as

I’ve succeeded to connect Safety using SfDomainConnect and to read the current Safety status via SfDomainInfo.

The general domain status is OK (see below) but unfortunately the Safe Application looks like isn’t ExistOnSafeLogic and isn’t Acknowledged,

that doesn’t allow to continue to SETUP mode and to run SfDomainTransfer.

Any idea why the Safe application doesn’t exist on our domain?

[michael.bertsch]

Hello,
nice to hear that you made it to the login.

After Compiling the SafeApplication in the SafeDesigner your Application will be shown here in the Configuration View.

With a Transfer of the grey Application this File is send to the CF-Card on the PLC.

From there you have to Transfer it to the SafePLC part with the SfDomainTransfer.
This should be possible in your state, if no Application is shown on SafePLC.
For the SafeAppFilePath you must use the Name of the File in ConfigurationView.
In picture above “SEM515_Test.sfapp”

If you need to switch to setup Mode you can use the Functionblock SfDomainControl

Greetings
Michael

[Omer_Vaserman]

Your fast response is highly appreciated

But I have few more questions:

1. Is Setup Mode is prerequisite for activating SfDomainTransfer?

2. Currently switch to Setup mode fails with the error SFDOM_ERR_CTRL_ACT_SM_FAILED ( -1073552092)

3. The only precondition from the list of possible failure reasons that doesn’t exist is: SafeAPPLICATION is not acknowledged

4. Note that PLC project including SafeApplication was already transferred to CFast, and Safety project was compiled and transferred via SafeDesigner remote control,

5. Isn’t it mean that Safe domain should already include Safe Application?

6. So the main question is: how to transfer initial Safe Application for the 1st time, to enable future SfDomainTransfer?

[michael.bertsch]

Hello,

I try to have some more answers:

1. Is Setup Mode is prerequisite for activating SfDomainTransfer?

   • As far as i know it is a requirement in the Default HMI (Formatted or SetupMode)
     But for the SfDomainTransfer i think i have tested it once without beeing in SetupMode and it worked. The Documented Requirement is only to have a SfDomainConnect.Active = TRUE ( which means to be logged in)

2. Currently switch to Setup mode fails with the error SFDOM_ERR_CTRL_ACT_SM_FAILED ( -1073552092)

• See AS-Help -1073552092
  I have never used it before but it looks like the SafePLC must be in a good state to use this function.

4. The only precondition from the list of possible failure reasons that doesn’t exist is: SafeAPPLICATION is not acknowledged

• I was not aware of this preCondition of this Functionblock. It looks like it can only Enable SetupMode if the SafePLC is in good state.

5. Note that PLC project including SafeApplication was already transferred to CFast, and Safety project was compiled and transferred via SafeDesigner remote control

• SafeDesigner Remote Control is a legacy Transfer which should only be used while Development in mappSafety. This Download does not entry the correct Diagnosis Data which is read by SfDomainInfo. This is a known issue and will not be changed.
  If you are familiar with the Remote Control you can use the Buttons there in parallel to the Functions of SfDomain.
  A SafeApplication Transfered with Remote Control will not be listed in SfDomainInfo.
  The Status Displayed in RemoteControl is Valid.

6. Isn’t it mean that Safe domain should already include Safe Application?

• I think Answer could be from 5. “A SafeApplication Transfered with Remote Control will not be listed in SfDomainInfo.”

8. So the main question is: how to transfer initial Safe Application for the 1st time, to enable future SfDomainTransfer?

• Recommended way to Initialy Transfer SafeApplication is via Default HMI which internaly used SfDomain Library or Application with SfDomain Library.

Even if you use the Remote Control you should be able to use the Transfer from SfDomain Library only the Diagnosis Data is invalid for the Application.
Just fill the Inputs of the Transfer Functionblock and Execute.

If there are still questions i have no issue with another list from you…

Greetings
Michael