Supported platforms: CODESYS 3.5 SAFETY
NVMem (PRG)
Description
This program reads and writes OD parameters and user values from/to non-volatile memory and application variables.
All parameters and user values are read once from NV-memory during initialization.
SSeriesHardware version 1.0.0.5SSeriesHardware version 1.0.0.5
Following table defines the NV-memory layout when using default library parameters.
|
Usage
|
Start address
|
Size
|
|
OD parameters
|
At the start of unit nv-memory
|
Total NVMem size – user value size * 2
|
|
User values
|
NVMem size – 512 bytes
|
256 bytes (*)
|
|
User values backup
|
NVMem size – 256 bytes
|
256 bytes (*)
|
* Note that usable user values size is reduced by parameter handler header size.
SSeriesHardware version 1.1.3.0SSeriesHardware version 1.1.3.0
Following tables define the NV-memory layout used by the library. Parameter area sizes can be adjusted with library parameters.
If total area size is less than actual NVRAM size, then the NVRAM area after library areas is left unused.
Application can use the unused area with NVRAMCOPY (FB) (EXT).
Library includes optional OD parameter backup area.
Application can take OD backup in use with library parameter G_PARAM_BACKUP_IN_USE which is used by code template.
Following areas are used if OD parameter backup is not in use:
|
|
G_PARAM_AREA_MAX_SIZE + 2x G_USER_VALUE_AREA_MAX_SIZE shall not exceed control unit’s actual NVRAM size reported by firmware. Init error is given if required size is too large.
|
|
Usage
|
Start address
|
Size
|
|
OD parameters
|
At the start address of unit’s nv-memory
|
G_PARAM_AREA_MAX_SIZE (bytes)
|
|
User values
|
Start of nv-memory + G_PARAM_AREA_MAX_SIZE
|
G_USER_VALUE_AREA_MAX_SIZE (bytes) (*)
|
|
User values backup
|
Start of nv-memory + G_PARAM_AREA_MAX_SIZE + G_USER_VALUE_AREA_MAX_SIZE
|
G_USER_VALUE_AREA_MAX_SIZE (bytes) (*)
|
* Note that usable user values size is reduced by parameter handler header size.
Following areas are used if OD parameter backup is in use:
|
|
2x G_PARAM_AREA_MAX_SIZE + 2x G_USER_VALUE_AREA_MAX_SIZE shall not exceed control unit’s actual NVRAM size reported by firmware. Init error is given if required size is too large.
|
|
Usage
|
Start address
|
Size
|
|
OD parameters
|
At the start address of unit’s nv-memory
|
G_PARAM_AREA_MAX_SIZE (bytes)
|
|
OD parameters backup
|
Start of nv-memory + G_PARAM_AREA_MAX_SIZE
|
G_PARAM_AREA_MAX_SIZE (bytes)
|
|
User values
|
Start of nv-memory + G_PARAM_AREA_MAX_SIZE +
G_PARAM_AREA_MAX_SIZE
|
G_USER_VALUE_AREA_MAX_SIZE (bytes) (*)
|
|
User values backup
|
Start of nv-memory + G_PARAM_AREA_MAX_SIZE +
G_PARAM_AREA_MAX_SIZE +
G_USER_VALUE_AREA_MAX_SIZE
|
G_USER_VALUE_AREA_MAX_SIZE (bytes) (*)
|
* Note that usable user values size is reduced by parameter handler header size.
SSeriesHardware version 1.1.4.0SSeriesHardware version 1.1.4.0
DM2 log is read/write from/to non-volatile memory if valid DM2 parameters given in NVMem.Init method.
The following tables define the NV-memory layout used by the library. Parameter area sizes can be adjusted from MultiTool Creator.
If the total area size is less than the actual NVRAM size, then the NVRAM area after library areas is left unused.
Application can use the unused area with NVRAMCOPY (FB) (EXT).
Library includes optional OD parameter backup area.
The following areas are used if OD parameter backup is not in use:
|
|
G_PARAM_AREA_MAX_SIZE + 2x G_USER_VALUE_AREA_MAX_SIZE+ G_DM2_AREA_MAX_SIZE shall not exceed control unit’s actual NVRAM size reported by firmware. Init error is given if required size is too large.
|
|
Usage
|
Start address
|
Size
|
|
OD parameters
|
At the start address of unit’s nv-memory
|
G_PARAM_AREA_MAX_SIZE (bytes)
|
|
User values
|
Start of nv-memory + G_PARAM_AREA_MAX_SIZE
|
G_USER_VALUE_AREA_MAX_SIZE (bytes) (*)
|
|
User values backup
|
Start of nv-memory + G_PARAM_AREA_MAX_SIZE + G_USER_VALUE_AREA_MAX_SIZE
|
G_USER_VALUE_AREA_MAX_SIZE (bytes) (*)
|
|
DM2 log
|
Start of nv-memory + G_PARAM_AREA_MAX_SIZE + 2*G_USER_VALUE_AREA_MAX_SIZE
|
G_DM2_AREA_MAX_SIZE (bytes)
|
* Note that usable user values size is reduced by parameter handler header size.
The following areas are used if OD parameter backup is in use:
|
|
2x G_PARAM_AREA_MAX_SIZE + 2x G_USER_VALUE_AREA_MAX_SIZE+ G_DM2_AREA_MAX_SIZE shall not exceed control unit’s actual NVRAM size reported by firmware. Init error is given if required size is too large.
|
|
Usage
|
Start address
|
Size
|
|
OD parameters
|
At the start address of unit’s nv-memory
|
G_PARAM_AREA_MAX_SIZE (bytes)
|
|
OD parameters backup
|
Start of nv-memory + G_PARAM_AREA_MAX_SIZE
|
G_PARAM_AREA_MAX_SIZE (bytes)
|
|
User values
|
Start of nv-memory + G_PARAM_AREA_MAX_SIZE +
G_PARAM_AREA_MAX_SIZE
|
G_USER_VALUE_AREA_MAX_SIZE (bytes) (*)
|
|
User values backup
|
Start of nv-memory + G_PARAM_AREA_MAX_SIZE +
G_PARAM_AREA_MAX_SIZE +
G_USER_VALUE_AREA_MAX_SIZE
|
G_USER_VALUE_AREA_MAX_SIZE (bytes) (*)
|
|
DM2 log
|
Start of nv-memory + 2*G_PARAM_AREA_MAX_SIZE +
2*G_USER_VALUE_AREA_MAX_SIZE
|
G_DM2_AREA_MAX_SIZE (bytes)
|
* Note that usable user values size is reduced by parameter handler header size.
Limitations
|
|
This program is automatically added to code template when using MultiTool Creator.
|
|
|
Error during nv-memory read will set init to ready but it will activate init error and disable parameter writing during normal operation.
|
|
|
Safety parameters can be saved only once and then reboot is required.
When safety parameter authentication status is TRUE, then OD parameter image is disabled after parameter save is executed.
|
|
|
All memory areas use Parameter Handler library for handling the images between RAM and NVRAM. Parameter handler also checks the image integrity.
|
|
|
User values data is reset to application default values if both NVRAM memory areas become corrupted.
Default values are also used when NVRAM is empty (new unit).
|
Init (METHOD) SseriesHardware version 1.1.3.0 and olderInit (METHOD) SseriesHardware version 1.1.3.0 and older
Init method is used to
initialize the necessary parameters for program.
OD parameter area and user value area
in RAM are given to PRG as initialization parameters.
If an area is not given, the corresponding
functionality is disabled. This is not considered as an error.
User value area and struct sizes are
checked that max size is not exceeded.
This
method sets the parameters to PRG for operation.
Init method is not considered ready
until OD parameter and user values are read from non-volatile memory.
Error during nv-memory read will set
init to ready but it will activate init error and disable parameter
writing during normal operation.
|
Input variable name
|
Data type
|
Description
|
|
i_NVMemoryIndex
|
UDINT
|
Index number of used non-volatile
memory.
|
|
i_pParameters
|
POINTER TO BYTE
|
Pointer to OD parameters image
|
|
i_ParameterAreaSize
|
UDINT
|
OD parameter image size.
|
|
i_pParameterHandler
|
POINTER TO EPEC_PH.ParameterHandler
|
Pointer to OD parameter handler
FB.
|
|
i_pUserValuesArea
|
POINTER TO BYTE
|
Pointer to user value image.
|
|
i_UserValueAreaSize
|
UDINT
|
User value image size.
|
|
i_pUserValueHandler
|
POINTER TO EPEC_PH.ParameterHandler
|
Pointer to user values handler
FB.
|
|
i_pUserValues
|
POINTER TO BYTE
|
Pointer to user parameter struct
|
|
i_UserValuesSize
|
UDINT
|
User value struct size
|
|
i_ParHandlerKeyword
|
UDINT
|
Keyword for both handlers.
|
|
Output
variable name
|
Data
type
|
Description
|
|
o_InitReady
|
BOOL
|
Init has been executed
|
Init (METHOD) SseriesHardware version 1.1.4.0 and newerInit (METHOD) SseriesHardware version 1.1.4.0 and newer
Init method is used to
initialize the necessary parameters for program.
OD parameter area, user value area and DM2 in RAM are given to PRG as initialization parameters. If an area is not given, the corresponding functionality is disabled. This is not considered as an error. User value area and struct sizes are checked that max size is not exceeded. This method sets the parameters to PRG for operation.
Init method is not considered ready until OD parameter, user values and DM2 log (if exists) are read from non-volatile memory. Error during nv-memory read will set init to ready but it will activate init error and disable parameter writing during normal operation.
|
Input variable name
|
Data type
|
Description
|
|
i_NVMemoryIndex
|
UDINT
|
Index number of used non-volatile
memory.
|
|
i_pParameters
|
POINTER TO BYTE
|
Pointer to OD parameters image
|
|
i_ParameterAreaSize
|
UDINT
|
OD parameter image size.
|
|
i_pParameterHandler
|
POINTER TO EPEC_PH.ParameterHandler
|
Pointer to OD parameter handler
FB.
|
|
i_pUserValuesArea
|
POINTER TO BYTE
|
Pointer to user value image.
|
|
i_UserValueAreaSize
|
UDINT
|
User value image size.
|
|
i_pUserValueHandler
|
POINTER TO EPEC_PH.ParameterHandler
|
Pointer to user values handler
FB.
|
|
i_pUserValues
|
POINTER TO BYTE
|
Pointer to user parameter struct
|
|
i_UserValuesSize
|
UDINT
|
User value struct size
|
|
i_pDM2Area
|
POINTER TO BYTE
|
Pointer to J1939 DM2 log image.
|
|
i_DM2AreaSize
|
UDINT
|
J1939 DM2 log area size.
|
|
i_pDM2Handler
|
POINTER TO EPEC_PH.ParameterHandler
|
Pointer to J1939 DM2 log area handler FB.
|
|
i_ParHandlerKeyword
|
UDINT
|
Keyword for both handlers.
|
|
Output
variable name
|
Data
type
|
Description
|
|
o_InitReady
|
BOOL
|
Init has been executed
|
SetParameterBackup (METHOD)SetParameterBackup (METHOD)
I
|
|
Requires library version 1.1.3.0 or later.
Code template executes this method automatically.
|
Method is used to enable OD parameter backup functionality.
If i_Enable is TRUE, the OD parameter backup is in use.
By default OD parameter backup is not in use.
Method shall be called before Init method.
|
Input variable name
|
Data type
|
Description
|
|
i_Enable
|
BOOL
|
TRUE = OD parameter backup in use
|
IsBackupLoaded (METHOD)IsBackupLoaded (METHOD)
|
|
Requires library version 1.1.3.0 or later.
Code template executes this method automatically.
|
Method is used to check if backup image has been loaded during initialization.
Outputs return TRUE if corresponding primary image is corrupted and valid backup image has been taken in use.
|
Output variable name
|
Data type
|
Description
|
|
o_ParameterBackupLoaded
|
BOOL
|
Valid OD parameter backup has been taken in use because primary image is corrupt. Output is FALSE if primary image is in use or both images are corrupt.
|
|
o_UserValueBackupLoaded
|
BOOL
|
Valid user value backup has been taken in use because primary image is corrupt. Output is FALSE if primary image is in use or both images are corrupt.
|
Operation
SseriesHardware version 1.1.3.0 and olderSseriesHardware version 1.1.3.0 and older
Writing new values to NV-memory is triggered by rising edge of input parameters i_WriteParameters and i_WriteUserValues.
Inputs
|
Input variable name
|
Data type
|
Description
|
|
i_WriteParameters
|
BOOL
|
Trigger OD parameters’ writing sequence.
|
|
i_WriteUserValues
|
BOOL
|
Trigger user values’ writing sequence.
|
|
i_Authentication
|
BOOL
|
Safety parameter authentication status.
|
Outputs
|
Output variable name
|
Data type
|
Description
|
|
o_InitError
|
BOOL
|
Init not called before calling the main PRG.
|
|
o_InputError
|
BOOL
|
Size of an area given without pointer to the area or user parameter size too large
|
|
o_ParameterError
|
EPEC_PH.ParamHandlerStatus
|
Error returned by OD parameter handler.
|
|
o_UserValueError
|
EPEC_PH.ParamHandlerStatus
|
Error returned by user value parameter handler.
|
|
o_NVMemError
|
EPEC_SYSTEM.SYSTEM_ERROR_CODES
|
Error returned by low-level NV-memory function.
|
|
o_ParSaveBusy
|
BOOL
|
Saving OD parameters to NV-memory.
|
|
o_ParSaveDone
|
BOOL
|
OD parameters saved to NV-memory successfully.
|
|
o_ParSaveError
|
BOOL
|
Error occurred in saving OD parameters to NV-memory.
|
SseriesHardware version 1.1.40 and newerSseriesHardware version 1.1.40 and newer
Writing new values to NV-memory is triggered by rising edge of input parameters i_WriteParameters and i_WriteUserValues. Writing DM2 log to NV-memory is triggered by setting input i_WriteDM2 to TRUE.
Inputs
|
Input variable name
|
Data type
|
Description
|
|
i_WriteParameters
|
BOOL
|
Trigger OD parameters’ writing sequence.
|
|
i_WriteUserValues
|
BOOL
|
Trigger user values’ writing sequence.
|
|
i_WriteDM2
|
BOOL
|
Trigger DM2 writing sequence
|
|
i_Authentication
|
BOOL
|
Safety parameter authentication status.
|
Outputs
|
Output variable name
|
Data type
|
Description
|
|
o_InitError
|
BOOL
|
Init not called before calling the main PRG.
|
|
o_InputError
|
BOOL
|
Size of an area given without pointer to the area or user parameter size too large
|
|
o_ParameterError
|
EPEC_PH.ParamHandlerStatus
|
Error returned by OD parameter handler.
|
|
o_UserValueError
|
EPEC_PH.ParamHandlerStatus
|
Error returned by user value parameter handler.
|
|
o_DM2Error
|
EPEC_PH.ParamHandlerStatus
|
Error returned by DM2 parameter handler.
|
|
o_NVMemError
|
EPEC_SYSTEM.SYSTEM_ERROR_CODES
|
Error returned by low-level NV-memory function.
|
|
o_ParSaveBusy
|
BOOL
|
Saving OD parameters to NV-memory.
|
|
o_ParSaveDone
|
BOOL
|
OD parameters saved to NV-memory successfully.
|
|
o_ParSaveError
|
BOOL
|
Error occurred in saving OD parameters to NV-memory.
|
Example code
|
|
This program is automatically added to code template when using MultiTool Creator.
|
See also
Source file topic100541.htm
Last updated 13-Jun-2024