Saving/Restoring Parameters

Epec Programming and Libraries Manual

Click here to see this page in full context

Supported platforms: CODESYS 2.3, CODESYS 3.5, CODESYS 3.5 SAFETY

Saving/Restoring Parameters

Code examples depend on the used platform and library versions. Same functionalities exist in all.

CODESYS 2.3
CODESYS 3.5 using CANopenODSave V3 (library manual applies also to CODESYS 2.3)
- 5050 C3.5
- 6000 series with device description 1.2.0.X or older
CODESYS 3.5 using CANopenODSave V4
- S Series/ E Series
- 5050 C3.5 with device description 1.2.0.X or newer
- 6000 series with device description 1.3.1.X or newer

CANopenODSave V4 uses Parameter Handler library instead of Filesys library for handling parameter images. The difference is that OD save uses pointer to parameter handler instance and group number instead of filename.

S Series/ E Series only: Before changing communication parameters (2150h), password protection must be unlocked (see Unlocking SW protection). This procedure will trigger safe state. This is not required when handling application parameters.

The CANopen standard defines two indexes for parameter handling: store and restore default parameter. The standard provides also manufacturer specific sub-indexes which are used in MultiTool Creator to define application specific storing and restoring index ranges.

Saving parameters into the device's non-volatile memory is done by store parameters index (1010h). By restore default parameters index (1011h) the default values of parameters are taken into use. The selected sub-index defines the parameter range to be saved / restored:

Sub-index 0 the amount of sub-indexes
Sub-index 1 refers to all parameters that can be stored on the device
Sub-index 2 refers to communication related parameters (Index 1000h - 1FFFh manufacturer specific communication parameters)
- Epec devices have communication parameters in index 2003h or 2150h, using sub-index 2 saves also these communication parameters when MultiTool code template is used (except S-Series)
Sub-index 3 refers to application related parameters (Index 2000h - FFFFh using MultiTool Creator code template)
Sub-indexes 4-127 manufacturers may define their own parameter groups
- In Epec units, sub-index 4 saves/restores all parameters in all ODs
- The application can use sub-indexes 5-127 to define the application specific store/restore areas. The application specific sub-indexes can be defined in MultiTool Creator, for more information see MultiTool Creator manual (available in Epec extranet).
Sub-indexes 128-254 are reserved for future use

S Series/ E Series only: Due to the unlock mechanism, communication parameter save / restore is always handled by firmware's CANopen OD. Use always 1010h / 1011h sub-index 1 when changing communication parameters from CAN bus to S Series/ E Series. Also CODESYS node-ID needs to be used.

Without user application, the unit supports only 1010h/1011h sub-index 1.

There are two ways to save/restore parameters:

Sending the save command through CANopen to index 1010h/1011h (this can be used for other devices on the bus)
Use CANopenODSave library functions in application code (this can be used for a unit's own parameters)

When MultiTool Creator is used to create CANopen devices and ODs, it automatically offers interface for indexes 1010h (save) and 1011h (restore).

The location of index' definition depends on used platform:

Code_Template_globals in CODESYS 2.3 or CODESYS 3.5 with CANopenODSave V3
G_CANopen_CANx in CODESYS 3.5 with CANopenODSave V4 (e.g. S-Series)

The difference between CANopen devices is:

CAN-number changes 1,2,3,.. ,
Depending on platform either filename or parameter handler group number changes

CODESYS 2.3:

G_CAN1_CANopenDevice_SaveData:ARRAY [0..3] OF sSaveIndexData :=

(StartIndex:=16#1000, EndIndex:=16#FFFF, FileName:='Device1.Par'), (*save all*)

(StartIndex:=16#1000, EndIndex:=16#1FFF, FileName:='Device1.Par'), (*save communication parameters*)

(StartIndex:=16#2000, EndIndex:=16#FFFF, FileName:='Device1.Par'), (*save application parameters*)

(StartIndex:=16#0000, EndIndex:=16#0000, FileName:='Device1.Par'); (*save manufacturer specific parameters*)

G_CAN1_CANopenDevice_SaveSubData1010h:sODSave:= (SubService:=Save,Sub1Count:=0,pNext:=0,NumOfEntrys:=4,SaveIndexData:=0,SaveSigns:=0,NextOD:=0);

CODESYS 3.5 (using CANopenODSave V3):

G_CAN1_CANopenDevice_SaveData: ARRAY[0..3] OF SaveODSubIndexDescription := [

(StartIndex := 16#1000, EndIndex := 16#FFFF, FileName := 'Device1.Par'), (*save all*)

(StartIndex := 16#1000, EndIndex := 16#1FFF, FileName := 'Device1.Par'), (*save communication parameters*)

(StartIndex := 16#2000, EndIndex := 16#FFFF, FileName := 'Device1.Par'), (*save application parameters*)

(StartIndex := 16#0, EndIndex := 16#0, FileName := 'Device1.Par')]; (*save manufacturer specific parameters*)

G_CAN1_CANopenDevice_SaveSubData1010h: SaveODSubService :=

(SubService := Save, Sub1Count := 0, pNext := 0, NumOfEntrys := 4, pSaveIndexData := 0, pSaveSigns := 0, pNextOD := 0);

CODESYS 3.5 (using CANopenODSave V4):

SaveData: ARRAY[0..3] OF EPEC_ODSave.SaveODSubIndexDescription := [

(StartIndex := 16#1000, EndIndex := 16#FFFF, GroupNum := 1), (*save all*)

(StartIndex := 16#1000, EndIndex := 16#1FFF, GroupNum := 1), (*save communication parameters*)

(StartIndex := 16#2000, EndIndex := 16#FFFF, GroupNum := 1), (*save application parameters*)

(StartIndex := 16#0, EndIndex := 16#0, GroupNum := 1)]; (*save manufacturer specific parameters*)

SaveSubData1010h: EPEC_ODSave.SaveODSubService;

Storing and restoring parameters functionality is only executed when a specific signature is written to the appropriate sub-index.

The signatures are "save“ and "load“ in ASCII, see the following tables.

Saving signature:

	MSB			LSB
ASCII	e	v	a	s
hex	65h	76h	61h	73h

Restoring signature:

	MSB			LSB
ASCII	d	a	o	l
hex	64h	61h	6Fh	6Ch

Handling Application Parameters

This section describes different functions for saving/restoring the unit's own parameters from CODESYS application.

Also example of saving parameters on another unit using CSDO is included.

S Series/ E Series only: To save / restore communication parameters (e.g. 2150h) using CODESYS application, always use S Series/ E Series hardware specific int libraries, for example, SafeSC52int SystemParameters (FB).

S Series only: See also, How to use & save parameters in Safety Control Unit for application parameter handling.

Save All Parameters from CODESYS applicationSave All Parameters from CODESYS application

To save all parameters in all CANopen devices, call:

CODESYS 2.3: SaveODAll program
CODESYS 3.5: SaveODSaveAll function block instance's Callback method

CODESYS 2.3:

IF saveAll THEN

saveAll:= FALSE;

SaveODAll();

END_IF

CODESYS 3.5 functionality is same for CANopenODSave V3 & V4 but the instance's location in code template differs.

CODESYS 3.5 (using CANopenODSave V3):

IF saveAll THEN

saveAll:= FALSE;

G_CAN1_CANopenDevice_SaveAll.Callback();

END_IF

CODESYS 3.5 (using CANopenODSave V4):

IF saveAll THEN

saveAll:= FALSE;

G_CANopen_CAN1.SaveAll.Callback();

END_IF

Save All Parameters to another control unit using CANopen CSDOSave All Parameters to another control unit using CANopen CSDO

CANopen libraries can be used to send save or restore commands through CAN bus.

The following gives an example of the save all parameters command to CAN1 bus using different platforms.

Using restore is similar, but the OD index and command's string value needs to be changed.

When using 6000-series unit with Parameters V4 library, it is recommended to use ParametersSave (FB) for sending save command instead of directly using CSDO. This FB will also handle save procedure for safety parameters (see also How to adjust safety parameters from display).

CODESYS 2.3 definitions:

csdohandler: CANopenCSDOTransfer;

csdo_error: CANopenCSDOErrors;

csdo_state: CANopenCSDOTransferStates;

csdo_abort: DWORD;

csdo_enable: BOOL;

csdo_ready: BOOL;

csdo_cmd: STRING(4) := 'save';

CODESYS 2.3 code:

csdohandler(

i_Enable := csdo_enable,

i_Channel := 0,

i_NodeID := 1,

i_Index := 16#1010,

i_SubIndex := 1,

i_Data := ADR(csdo_cmd),

i_Size := UDINT#4,

i_Write := TRUE,

i_Stop := FALSE,

i_TimeOut := T#1s,

i_DontChgByteOrd := FALSE,

i_TimeOut_ReqResp := T#1s,

o_State => csdo_state,

o_Ready => csdo_ready,

o_AbortCode => csdo_abort,

o_Size => ,

o_Error => csdo_error

);

CODESYS 3.5 definitions using CANopen V3:

csdohandler: EPEC_CSDO.CANopenCSDOTransfer;

csdo_error: EPEC_CSDO.CANopenCSDOErrors;

csdo_state: EPEC_CSDO.CANopenCSDOTransferStates;

csdo_abort: DWORD;

csdo_enable: BOOL;

csdo_ready: BOOL;

csdo_cmd: STRING(4) := 'save';

CODESYS 3.5 code using CANopen V3:

csdohandler(

i_Enable := csdo_enable,

i_itfChannel := G_CAN1_Channel,

i_NodeID := 1,

i_Index := 16#1010,

i_SubIndex := 1,

i_pData := ADR(csdo_cmd),

i_Size := UDINT#4,

i_Write := TRUE,

i_Stop := FALSE,

i_TimeOut := T#1s,

i_DontChgByteOrd := FALSE,

i_TimeOut_ReqResp := T#1s,

o_State => csdo_state,

o_Ready => csdo_ready,

o_AbortCode => csdo_abort,

o_Size => ,

o_Error => csdo_error

);

CODESYS 3.5 definitions using CANopen V4:

csdohandler: EPEC_CANopen.CANopenSDOClient;

csdo_error: EPEC_CANopen.Errors;

csdo_state: EPEC_CANopen.CSDOTransferStates;

csdo_abort: DWORD;

csdo_enable: BOOL;

csdo_ready: BOOL;

csdo_cmd: STRING(4) := 'save';

CODESYS 3.5 code using CANopen V4:

csdohandler(

i_Enable := csdo_enable,

i_pDevice := ADR(G_CANopen_CAN1.Device),

i_NodeID := 1,

i_Index := 16#1010,

i_SubIndex := 1,

i_pData := ADR(csdo_cmd),

i_Size := UDINT#4,

i_Write := TRUE,

i_Stop := FALSE,

i_TransferTimeOut := T#1S,

i_DontChgByteOrd := FALSE,

i_MessageTimeOut := T#1S,

o_State => csdo_state,

o_Ready => csdo_ready,

o_AbortCode => csdo_abort,

o_Size => ,

o_Error => csdo_error

);

Restore All Parameters from CODESYS applicationRestore All Parameters from CODESYS application

To restore all parameters to default values, call:

CODESYS 2.3: SaveODDeleteAll program
CODESYS 3.5: SaveODDeleteAll function block instance's Callback method

The parameters are restored to default values in the next boot-up.

CODESYS 2.3:

IF restoreAll THEN

restoreAll := FALSE;

SaveODDeleteAll();

END_IF

CODESYS 3.5 functionality is same for CANopenODSave V3 & V4 but the instance's location in code template differs.

CODESYS 3.5 (using CANopenODSave V3):

IF restoreAll THEN

restoreAll:= FALSE;

G_CAN1_CANopenDevice_DeleteAll.Callback();

END_IF

CODESYS 3.5 (using CANopenODSave V4):

IF restoreAll THEN

restoreAll:= FALSE;

G_CANopen_CAN1.DeleteAll.Callback();

END_IF

Save Specific Indexes from CODESYS applicationSave Specific Indexes from CODESYS application

To save specific indexes in specific OD, call function SaveODSave. Function interface depends on platform.

Saving operation can be made only for certain indexes but restore command is always made for defined set.

The example below shows how to save the following indexes:

5000h for CANopen device 1
2200h for CANopen device 2

CODESYS 2.3:

IF saveIndex5000hCAN1 THEN

saveIndex5000hCAN1 := FALSE;

SaveODSave(

i_pOD := ADR(G_CAN1_CANopenDevice_OD),

i_StartIndex := 16#5000,

i_EndIndex := 16#5000,

i_Filename := 'Device1.Par'

);

END_IF

IF saveIndex2200hCAN2 THEN

saveIndex2200hCAN2 := FALSE;

SaveODSave(

i_pOD := ADR(G_CAN2_CANopenDevice_OD),

i_StartIndex := 16#2200,

i_EndIndex := 16#2200,

i_Filename := 'Device2.Par'

);

END_IF

CODESYS 3.5 (using CANopenODSave V3):

IF saveIndex5000hCAN1 THEN

saveIndex5000hCAN1 := FALSE;

EPEC_ODSave.SaveODSave(

i_pOD := ADR(G_CAN1_CANopenDevice_OD),

i_StartIndex := 16#5000,

i_EndIndex := 16#5000,

i_Filename := 'Device1.Par'

);

END_IF

IF saveIndex2200hCAN2 THEN

saveIndex2200hCAN2 := FALSE;

EPEC_ODSave.SaveODSave(

i_pOD := ADR(G_CAN2_CANopenDevice_OD),

i_StartIndex := 16#2200,

i_EndIndex := 16#2200,

i_Filename := 'Device2.Par'

);

END_IF

CODESYS 3.5 (using CANopenODSave V4):

IF saveIndex5000hCAN1 THEN

saveIndex5000hCAN1 := FALSE;

EPEC_ODSave.SaveODSave(

i_pOD := ADR(G_CANopen_CAN1.OD),

i_StartIndex := 16#5000,

i_EndIndex := 16#5000,

i_ParamGroup := 1,

i_pParamHandler := ADR(G_Common.ParHandler)

);

END_IF

IF saveIndex2200hCAN2 THEN

saveIndex2200hCAN2 := FALSE;

EPEC_ODSave.SaveODSave(

i_pOD := ADR(G_CANopen_CAN2.OD),

i_StartIndex := 16#2200,

i_EndIndex := 16#2200,

i_ParamGroup := 2,

i_pParamHandler := ADR(G_Common.ParHandler)

);

END_IF

Save/Restore Parameter Sets from CODESYS applicationSave/Restore Parameter Sets from CODESYS application

To save parameter sets, call:

CODESYS 2.3 function SaveODLinesByDesc
CODESYS 3.5 function SaveODSaveLinesByDesc

To restore parameter sets, call:

CODESYS 2.3 function SaveODDeleteLinesByDesc
CODESYS 3.5 function SaveODDeleteLinesByDesc

Function interfaces depend on the used platform.

Default parameters are taken into use in the next boot-up.

The parameter sets are defined in the code template's SaveData arrays (see at the beginning of this guide).

Line numbering starts from 0,1,2,3 (sub1, sub2,..)

The following examples shows how parameters are saved / restored for CANopen device 1.

If the line number is 3, parameters for all CANopen devices are saved/restored.

CODESYS 2.3:

IF saveByUsingLines THEN

saveByUsingLines := FALSE;

SaveODLinesByDesc(

i_pOD := ADR(G_CAN1_CANopenDevice_OD),

i_SaveLine := lineNumber

);

END_IF

IF restoreByUsingLines THEN

restoreByUsingLines := FALSE;

(*Restore all parameters to default values for CAN device 1*)

SaveODDeleteLinesByDesc (

i_pOD := ADR(G_CAN1_CANopenDevice_OD),

i_SaveLine := 3

);

END_IF

CODESYS 3.5 (using CANopenODSave V3):

IF saveByUsingLines THEN

saveByUsingLines := FALSE;

EPEC_ODSave.SaveODSaveLinesByDesc(

i_pOD := ADR(G_CAN1_CANopenDevice_OD),

i_SaveLine := lineNumber

);

END_IF

IF restoreByUsingLines THEN

restoreByUsingLines := FALSE;

(*Restore all parameters to default values for CAN device 1*)

EPEC_ODSave.SaveODDeleteLinesByDesc(

i_pOD := ADR(G_CAN1_CANopenDevice_OD),

i_SaveLine := 3

);

END_IF

CODESYS 3.5 (using CANopenODSave V4):

IF saveByUsingLines THEN

saveByUsingLines := FALSE;

EPEC_ODSave.SaveODSaveLinesByDesc(

i_pOD := ADR(G_CANopen_CAN1.OD),

i_SaveLine := lineNumber,

i_pParamHandler := ADR(G_Common.ParHandler)

);

END_IF

IF restoreByUsingLines THEN

restoreByUsingLines := FALSE;

(*Restore all parameters to default values for CAN device 1*)

EPEC_ODSave.SaveODDeleteLinesByDesc(

i_pOD := ADR(G_CANopen_CAN1.OD),

i_SaveLine := 3,

i_pParamHandler := ADR(G_Common.ParHandler)

);

END_IF

Load Parameters from CODESYS applicationLoad Parameters from CODESYS application

To load the saved parameters when the system is running, call function SaveODLoad or SaveODLoadODLinesByDesc.

Function interfaces depend on the used platform.

The following example shows how the function SaveODLoad is used.

CODESYS 2.3:

IF loadIndices THEN

loadIndices := FALSE;

(*Load saved parameter index 5000h*)

SaveODLoad(

i_pOD := ADR(G_CAN1_CANopenDevice_OD),

i_StartIndex := 16#5000,

i_EndIndex := 16#5000,

i_Filename := 'Device1.Par'

);

END_IF

CODESYS 3.5 (using CANopenODSave V3):

IF loadIndices THEN

loadIndices := FALSE;

(*Load saved parameter index 5000h*)

EPEC_ODSave.SaveODLoad(

i_pOD := ADR(G_CAN1_CANopenDevice_OD),

i_StartIndex := 16#5000,

i_EndIndex := 16#5000,

i_Filename := 'Device1.Par'

);

END_IF

CODESYS 3.5 (using CANopenODSave V4):

IF loadIndices THEN

loadIndices := FALSE;

(*Load saved parameter index 5000h*)

EPEC_ODSave.SaveODLoad(

i_pOD := ADR(G_CANopen_CAN1.OD),

i_StartIndex := 16#5000,

i_EndIndex := 16#5000,

i_ParamGroup := 1,

i_pParamHandler := ADR(G_Common.ParHandler)

);

END_IF

Keyword - Protecting Application Parameters

Code template using CANopenODSave V4 (e.g. S Series / E Series) do not use the same variable names defined in this chapter. In that case the keyword is given to the parameter handler instance, not filesys library. However, the functionality is the same.

MultiTool Creator automatically creates a keyword protection for each application so that it is not possible to use of another application's parameters. The keyword is a fixed numeric value, stored in a global variable G_FileSysKeyWord. The keyword is created for each device that is added to a MultiTool Creator project. This value is saved to non-volatile memory together with parameters.

When the file system is initialized, this value is given for the file system and checked if it corresponds to the saved value. The keyword can mismatch, if a different application is downloaded to the device. If there is a mismatch, the file system is formatted and all parameters reset to their default values. Keyword mismatches can be seen after file system initialization in a Filesys librarys global variable G_FileSysFileSystem, as seen in the following image.