Doc ¶ CODESYS J1939 Safety Basics Recommended Task context Limitations Examples Therms and Abbreviations Preconditions
CODESYS J1939 Safety Basics ¶ CODESYS J1939 Safety provides functions blocks to build a safe J1939 message transport chain: Safe_SDG_Producer to produce the J1939-76 Safety Data Group (SDG) message(s). J1939SafetyStd.Unsafe_SDG_Sender to send the SDG safety / data messages via CAN driver. J1939SafetyStd.Unsafe_SDG_Receiver to receive selected J1939 safety / data messages and join them to interrelated, unsafe “Safety Data Group” (SDG) data. Safe_SDG_Consumer to consume unsafe SDG data provided by a J1939SafetyStd.Unsafe_SDG_Receiver, check if they are consistent / safe and provide the transported J1939-76 SDG data to the application. The J1939 safety protocol is implemented in this library according to the SAE J1939 safety specification. However, to use the protocol in a CODESYS safety SIL2 application, it is necessary to consider the entire configuration of the system and to be familiar with the CODESYS Safety SIL2 user manual and the protocol specification. Recommended Task context ¶ To explain the recommended task context we assume a simple use case. One Safety PLC acts as a “J1939 Safety SDG Source” and a second one acts as “J1939 Safety SDG Sink”. In this case the pair Safe_SDG_Producer / Unsafe_SDG_Sender is supposed to reside on the first Safety PLC (let’s call it “J1939 Safety SDG Source PLC”). The related pair Unsafe_SDG_Receiver / Safe_SDG_Consumer is supposed to reside on second Safety PLC (let’s call ist “J1939 Safety SDG Sink PLC”). The best performance is achieved when sending SDGs by calling the “Safe PRG” with the Safe_SDG_Producer before the “Unsafe PRG” with the Unsafe_SDG_Sender in one task in this order. Analogous applies for the receive of SDGs the sequence “Unsafe PRG” with Unsafe_SDG_Receiver before the “Safe PRG” with Safe_SDG_Consumer in one Task in this order. In real world applications a PLC will eventually act as both “J1939 Safety SDG Source” and “J1939 Safety SDG Sink”. Limitations ¶ CODESYS J1939 Safety comes with the following limitations: SAE J1939-76 limits messages to fixed size (PG data length 8 bytes or less) SAE J1939-76 applies some constraints regarding PG Transmission Rate (see SAE J1939-76 APR2020 4.4.1 Applicable SAE J1939 Messages), but CODESYS J1939 Safety is limited to “Fixed Transmission Rate PG” CODESYS J1939 Safety (unsafe part) is utilizing an own CODESYS CAN low level driver instance, a driver instance used somewhere else can not be reused. Safe_SDG_Producer samples inputs S_dwPGN, S_tTransmissionRate, S_usiSrcAddr, S_usiSHMPriority and S_usiSDMPriority with the rising edge of xEnable, so that these parameters are set for the activated SDG production. Safe_SDG_Consumer samples inputs S_dwPGN, S_tTransmissionRate, S_usiSrcAddr, S_tSCT and S_tSRVT with the rising edge of xEnable, so that these parameters are set for the activated SDG consumption. By concept J1939 comes with the limitation that in one network a combination “Parameter Group Number” (PGN) / “Source Address” (of a SDG) needs to be unique. So there must be no SDG with the same combination PGN / “Source Address” within one network. Examples ¶ The CODESYS J1939 Safety library comes with examples to demonstrate usage. To get an idea about the data flow in general please take a look at J1939 Safety example.project -> device ExampleDataFlow -> FUNCTION_BLOCK J1939_example_CFC. To get an idea about how to deal with the separation of safe / unsafe code and relation to a task context please take a look at J1939 Safety example.project -> device J1939_Producer / J1939_Consumer -> Task Configuration -> MainTask. Therms and Abbreviations ¶ Therms and abbrevations see SAE J1939-76 APR2020 3 Definitions and Abbreviations
Preconditions ¶ The CODESYS J1939 Safety library implies preconditions to provide the required safety level. The CAN-mini-driver used with CAN-low-level (used in J1939SafetyStd.CL2Driver) has to provide a timestamp for receive messages (later referred to as “capture timestamp”). This is necessary to ensure receive order detection for Safety Header Message / Safety Data Message (SHM / SDM) pairs.
GetLibVersion (FUN) ¶ FUNCTION GetLibVersion : VERSION This function has been automatically generated from the project information. InOut: Scope Name Type Return GetLibVersion VERSION
GetLibVersionNumber (FUN) ¶ FUNCTION GetLibVersionNumber : DWORD This function has been automatically generated from the project information. InOut: Scope Name Type Return GetLibVersionNumber DWORD
IsLibReleased (FUN) ¶ FUNCTION IsLibReleased : BOOL This function has been automatically generated from the project information. InOut: Scope Name Type Return IsLibReleased BOOL
File and Project Information ¶ Scope Name Type Content FileHeader creationDateTime date 21.06.2023, 11:08:02 companyName string 3S-Smart Software Solutions GmbH libraryFile Generic String Base.library primaryProject True productName CODESYS productProfile CODESYS V3.5 SP18 Patch 3 contentFile Generic String Base.clean.json version version 2.0.0.0 ProjectInformation AutoResolveUnbound bool True Released True LastModificationDateTime date 21.06.2023, 11:08:00 LibraryCategories library-category-list Application|Strings Author string CODESYS Development GmbH Company CODESYS DefaultNamespace GSB Description See: Description DocFormat reStructuredText LanguageModelAttribute qualified-access-only Placeholder GenericStringBase Project Generic String Base Title Generic String Base UnitTestingDefine GenStringTesting Version version 4.0.0.0
Library Reference ¶ This is a dictionary of all referenced libraries and their name spaces. Immutable String Segments ¶ Library Identification ¶ Placeholder: StringSegs Default Resolution: Immutable String Segments, * (CODESYS) Namespace: STR Library Properties ¶ LinkAllContent: False Optional: False QualifiedOnly: True SystemLibrary: False Key: StringSegs String Builder ¶ Library Identification ¶ Placeholder: StringBuilder Default Resolution: String Builder, * (CODESYS) Namespace: SBD Library Properties ¶ LinkAllContent: False Optional: False QualifiedOnly: True SystemLibrary: False Key: StringBuilder String Builder Base ¶ Library Identification ¶ Placeholder: StringBuilderBase Default Resolution: String Builder Base, * (CODESYS) Namespace: SBB Library Properties ¶ LinkAllContent: False Optional: False QualifiedOnly: True SystemLibrary: False Key: StringBuilderBase String Conversions ¶ Library Identification ¶ Placeholder: StrConv Default Resolution: String Conversions, * (CODESYS) Namespace: SCV Library Properties ¶ LinkAllContent: False Optional: False QualifiedOnly: True SystemLibrary: False Key: StrConv UTF-8 Encoding Support ¶ Library Identification ¶ Placeholder: UTF8 Default Resolution: UTF-8 Encoding Support, * (CODESYS) Namespace: UTF8 Library Properties ¶ LinkAllContent: False Optional: False QualifiedOnly: True SystemLibrary: False Key: UTF8
Builder.Reset (METH) ¶ METHOD FINAL Reset Resets the Builder to be empty InOut: Scope Name Type Output eErrorID ERROR
Segments ¶ The handling of UTF-8 encoded strings without additional buffering The specification pbyData and udiSize can be used to describe a memory block that is to be considered for the processing of strings. Receiving Data eErrorID := itfPeer.Receive ( pbyData , udiSize , itfIPAddressFrom , uiPortFrom => uiPortFrom , udiCount => udiCount ); // UDP/IP eErrorID := itfConnection.Read ( pbyData , udiSize , udiCount => udiCount ); // TCP/IP udiCount := TO_UDINT ( SysFileRead ( hFile , pbyData , TO__XWORD ( udiSize ), ADR ( udiResult ))); // File Access udiCount := SysComRead ( hCom , pbyData , udiSize , ulTimeout , ADR ( udiResult )); // Serial Com Sending data eErrorID := itfPeer.Send ( itfIPAddress , uiPort , pbyData , udiSize , udiCount => udiCount ); // UDP/IP eErrorID := itfConnection.Write ( pbyData , udiSize , udiCount => udiCount ); // TCP/IP udiCount := TO_UDINT ( SysFileWrite ( hFile , pbyData , TO__XWORD ( udiSize ), ADR ( udiResult ))); // File Access udiCount := SysComWrite ( hCom , pbyData , udiSize , ulTimeout , ADR ( udiResult )); // Serial Com For all these use cases an IBuilder implementation offers the possibility to provide the buffer. This allows the corresponding IBuilder instance to be extended with the new content without a additional buffer and thus without additional effort for the management of the copy. Read content received by a a network connection to a ``IBuilder`` instance REPEAT eErrorID := itfBuilder.GetCurrentSegment ( pbyData => pbyData , udiSize => udiSize ); eErrorID := itfConnection.Read ( pbyData , udiSize , udiCount => udiCount ); IF eErrorID = ERROR.NO_ERROR AND udiCount > 0 THEN eErrorID := itfBuilder.ValidateSegment ( pbyData , udiCount ); IF eErrorID <> ERROR.NO_ERROR THEN // Handle Error EXIT ; END_IF END_IF UNTIL udiCount = 0 END_REPEAT Write the content of a ``IBuilder`` instance to a network connection pbyData := itfBuilder.GetFirstSegment ( udiSize => udiSize , eErrorID => eErrorID ); WHILE pbyData <> 0 AND eErrorID = ERROR.NO_ERROR DO eErrorID := itfConnection.Write ( pbyData , udiSize , udiCount => udiCount ); IF eErrorID <> ERROR.NO_ERROR OR udiCount <> udiSize THEN // Handle Error EXIT ; END_IF pbyData := itfBuilder.GetNextSegment ( pbyData , udiSize => udiSize , eErrorID => eErrorID ); END_WHILE GetCurrentSegment (Method) GetFirstSegment (Method) GetNextSegment (Method) ValidateSegment (Method)
