Repository containing library and tools for working with Norsok SCD library (AML), developed based on IEC PAS 63131:2017, which has same content as Norsok I-005 rev.3.
Facilitation of standardized encoding/decoding and exchange of IEC 63131 designs (SCDs and sequence diagrams SFCs) in machine readable format is the scope of this repository.
Changes to the IEC 63131 standard itself is strictly excluded from the scope of this repository.
Issues shall be strictly limited to the defined scope of work.
If an issue is raised that falls outside the scope of work it shall be closed without further action (ie, void and null).
Standard reply to be given: "This falls outside the scope of this repo, please raise your issue via appropriate channels."
Git LFS is enabled in this repository and set up to track Excel files (.xlsx), see .gitattributes config file.
Git LFS locking is not configured (not expecting multiple people to edit same Excel file).
| Reference | Description |
|---|---|
| IEC PAS 63131:2017 | Pre standard "SYSTEM CONTROL DIAGRAM» |
| Norsok I-005 Edition 3, Mar 2013 | System control diagram |
| AutomationML | https://www.automationml.org/o.red.c/erste-schritte.html |
| ISO 5457 | Technical product documentation — Sizesand layout of drawing sheets |
| Norsok Z-005 Rev. 1, October 1997 | 2D-CAD drawing standard |
| Abbreviation | Description |
|---|---|
| AML | AutomationML |
| AML-Writer | The application that create the AML file with instances |
| AML-Reader | The application that read the AML file |
| CAEX | Computer Aided Engineering Exchange |
| DQM | Data Quality Management |
| GUID | Global Unique IDentifier |
| HW | Hardware |
| IEC | International Electrotechnical Commission |
| SAS | Safety and Automation System |
| SCD | System Control Diagram |
| SIS | Safety Instrumented System |
| SW | Software |
| UUID | Universal Unique Identifier |
Automation ML is the selected tool and format for exchange of control system information.
The SCD.AML file will only contain information that can be red from the drawing, and the focus is at the logical signal connections.
This project will set up a class library based on Norsok I-005 revision 3 - System Control Diagram (SCD)
The applied Norsok SCD-AML class library shall be used by the engineering company, to generate a AML file for one or several SCD's. The number of drawings contained in one AML file must be agreed in the individual projects. See recommendation in next sub chapter.
The individual SCD.AML file is shared with to the Control System Vendor, and the file contains the AML-library.
The control system vendor must have some kind of configuration to convert the SCD.AML file to proper control system format. The SCD does not include all information needed to set up the complete control system, so all relevant engineering documentation should be used in the configuration to add additional information that shall be part of the control system file.
Figure 1 Example of workflow
Following a standardized document workflow, each SCD has its own official version.
We recommend to deliver an AML version of the same SCD together in the document archive.
There will exist 2 files that should hold the same information regarding logic. If there are any discrepancies between the two files, then the signed version should be used.
AML file that is generated from a SCD contains the SCD and individuals and signal relations. It also contains the corresponding class-library, and the receiving application can use this to check the design.
It is recommended that the AML-generator in both source and destination application , create a log with errors and warnings.
This can be used to correct own design in engineering or configuration at the control system vendor.
It can be used as part of the feedback to the responsible part.
It is recommended to include this as a Data Quality Management - DQM check as part of the SCD check process before the drawing becomes official.
Proposal to implement use of checksum of the produced AML to check if the AML file was changed after it was produced.
The target for converting SCD to AML is to be able to import Function Block (FB) and Logic with signal connections into a neutral format that can be used by any control system vendor.
The content of what we get in the AML-file should be limited to what is displayed on the drawing.
The SCD is in some cases simplified for drawing purposes. These simplifications should normally be documented in a SCD legend or in the SCD-development guideline for the actual project.
NOTE: It is not a topic for the SCD-AML generator to add template information to the AML-file.
The control system vendor receives SCD.AML file's and must convert these into their own programming language. Each of the AML files contains the library and this must be mapped to the control system vendor's internal classes.
Additional missing information in the SCD.AML file can be collected added from relevant project engineering documents.
To be able to check existing control system design against incoming AML file, an extraction of existing design and converting this to the standard AML design will give an option for comparing the two AML files for discrepancies.
It is recommended that the vendor develop such solutions.
Editor and information about the tool can be found her:
https://www.automationml.org/o.red.c/erste-schritte.html
- Whitepaper AutomationML Part 1 - Architecture and general requirements
- Whitepaper Part 2 - Role class libraries
- Whitepaper Part 4 - Logic Description
Introduction to editor: https://www.youtube.com/watch?v=YBCVM3puKZU
Required Structure of AML file is defined in Part-1:
- chapter 5.3 "AML Document versions"
- The AML writer application should fill in the metadata ref chapter 5.4 "Meta information about the AML source tool"
Reference Part-1 chapter 5.5
| AML Classes | AML Object Instances | CAEX Interfaces |
|---|---|---|
| RoleClass InterfaceClasse SystemUnitClasse |
CAEX InternalElements CAEX ExternalInterface |
Identification of AML Classes shall be identified by their CAEX "Name"
Name shall be unique within the hierarchy level of the corresponding AML library
Reference to classes shall be done via full path.
Identification of AML Object Instances shall use CAEX tag: "ID"
The "ID" shall be Universal Unique Identifier - UUID
This can be implemented as a Global Unique Identifier – GUID
The UUID shall never change over the life time of the corresponding object within all participating tools.
Referencing instances shall use the "ID" and not the "Name", as this can change over time.
| Example of Child-Parent relation: AML Class with reference to the owner class full path. |  |
|---|---|
| Example of a InstanceClassLibrary object implemented as an individual in a SystemUnitClass. This individual has a requirement for use of "ID" and a global unique identifier GUID has been added |
 |
| Example of an Individual in the Instance Hierarchy. This object is an individual of a SystemUnitClass and has a requirement for "ID" and a "Name" Name = Tag number ID = unique ID in the source system. |
 |
ref Part-1 chapter 5.6
Parent-Child relations between AML object instances use AML "InternalElement" to represent hierarchical object structure.
Parent-Child relations between AML classes use a parent-child relations:
Class Inheritance relation to InterfaceClass
Singleton: AML Individual created without relation to a SystemUnitClass.
Normal AML individuals shall be created based on a SystemUnitClass. And will then get a complete copy of the structure and attributes from the SystemUnitClass object. The SystemUnitClass act as a "copy template" and there is no inheritance from the class to individuals.
_ Note _: according to ref 5.6.5 it is allowed to reduce and expand data copied from the SystemUnitClass.
_ Recommendation for use of the NorsokLibrary _: keep all function block interfaces as defined in the template library for easy check of changes and consistency.
ref Part-1 Ref 5.6.6
CAEX InternalLinks object hold relations between two instances. It shall be stored at the CAEX InternalElement which is the lowest common parent of the two connected objects.
In the Norsok SCD "InstanceHierarchy" model this will be below the SCD-Document.
| Name syntax: "Link-" + Number References is added to "RefPartnerSideA" and "RefPartnerSideB" Reference syntax: "ID" of the interface Owner + ":" + InterfaceName |
 XML: <InternalLink Name="Link35" RefPartnerSideA="744651ea-66d9-4133-5339-323932573949:Out" RefPartnerSideB="744651ea-66d9-4133-5341-303454413448:X" /> Navigator:  |
|---|
StructrueClassLibrary The SCD converted drawing(s) will be represented as an instance hierarchy in AML.
The instance is by default a copy of an AML class and then modified with instance properties and relations.
Proposed InstanceHierarchy:
Level 1: InstanceHierarchy individual: Project or Facility Name
Level 2: Document Structure
Level 3: Document Individual
Level 4: InternalLinks between individuals in Level 5
Grouping of SystemUnitClass information.
Level 5: Individuals of the different SystemUnitClasses Note: Individuals must have unique names in same folder.
The AML-Writer shall add individuals of different SystemUnitClassLib to the structure objects below the DocumentIndividual.
Individuals are defined with a header and properties.
| Field - description | |
|---|---|
| ID: Unique id for the individual from the source application **Name: **"Tag number" in the source application Description: Used where applicable e.g at On/OffPage references RefBaseSystemUnitPath: Reference to the SystemUnitClass |
 |
| Attributes are defined at the AML class and populated with values at the instance level. The AML-Writer Some attributes has got constraint and limitations of what can be set. See library for details. |
  |
If it is required to deliver symbol position:
A 2D-drawing has a Cartesian coordinate system in two dimensions (also called a rectangular coordinate system or an orthogonal coordinate system). Ref https://en.wikipedia.org/wiki/Cartesian_coordinate_system
The definition of the coordinate system and drawing orientation is set in the document individual.
It is mandatory that this is set so that the AML-reader knows how to use the information.
All symbols placed on a drawing has a symbol origo. The Symbol origo has a reference to the drawing origo.
Note: SignalInterface (Terminal names) has not got these attributes in this version of the AML.
| Attributes | Value | Unit |
|---|---|---|
| X | mm | |
| Y | mm |
If required by the project it is possible to add Layers defined by the standard or additional layers defined by the project.
To be able to hold this information all symbols placed on a drawing has got the following attribute
| Attributes | Value |
|---|---|
| Layer |
The SCD is an individual in the instance hierarchy with some attributes defined at the SCD – class.
Document properties:
| Header | Value | Example |
|---|---|---|
| Name | Document Number | C151-AS-J-XZ-43002-01 |
| Description | Document Title | LP flare KO drum |
| Version | Current Revision | 05 |
| ID | UUID | 744651ea-66d9-4133-4b44-4e51445a3838 |
| Attributes | Value | Restrictions |
|---|---|---|
| DrawingSize | A1 | |
| Orientation | Landscape | |
| CoordinateSystem | Cartesian coordinate system orientation: right-handed_ Note _: required if reference to symbol position is used. | |
| Scale | NA | |
| Area | ||
| System |
Class library of objects related to the document and general objects like Note and Revision Trinagle. 
The document revision matrix is treated as individual record set in the AML file. The columns in the matrix are properties at the record set.
In the example below this will be represented by 5 individuals in the AML document
Properties of RevisionRecord class
| Header | Value | Example |
|---|---|---|
| Name | "Rev-" + Version | Rev-01 |
| Description | "Reason for issue" | INTER DISCIPLINE CHECK |
| Version | Revision code | 01 |
| ID | UUID | ffefb00b-987c-47a8-a47c-500c64fed20d |
| Attributes | Value | |
| RevisionDate | 10.06.2015 | |
| CreatedBy | PB | |
| CheckedBy | Abi | |
| ApprovedBy | REK |
Note is a text placed somewhere at the drawing.
The individual symbols can have a reference to the note, and has a separate attribute for this purpose.
This can be used to find the actual note.
| Header | Value |
|---|---|
| Name | "Note-" + Number |
| Description | Note Description |
| Version | |
| ID | UUID |
| Attributes | Value | Unit |
|---|---|---|
| X | mm | |
| Y | mm |
Function Block properties
Control Function Integration:
| Header | Value | Example at individual |
|---|---|---|
| Name | Tag number | A-43LIC0135 |
| ID | UUID | 744651ea-66d9-4133-4c37-563433325255 |
| RefBaseSystemUnitPath | FunctionBlockLibrary/NorsokFunctionBlockClass/CA |
| Attributes | Value | Unit | Example |
|---|---|---|---|
| Layer | |||
| X | mm | ||
| Y | mm | ||
| ControlMode | DIR | ||
| ControlNode | A-U01 | ||
| ControlFunctionIntegration | I | ||
| AdditionalText | |||
| NoteRef |
The class library is defined based on the definition in the standard and one level where vendor specific Function Blocks can be created. If the AML-writer doesn't find the correct class in none of these two then the "NonStandardFunctionBlockClass" can be used. It will then be possible to find and handle these individuals.
| Class Library | Attributes |
|---|---|
 |
 |
FunctionBlock Terminal Names defined in the standard are realized in AML with use of ExternalInterface
Attributes belonging to these objects are defined in InterfaceClassLibrary ref. chapter 4.2.
Ref 5.1 Issue: SignalInterface – Names are omitted at many symbols
If no project agreement is made then these unnamed terminals at Function Block should be represented by the generic Interface Class "In" and "Out". Ref 4.5.5NorsokSignalClass.
NorsokElementaryFunctionClass and InputParameterClass
| Class Library | Attributes |
|---|---|
 |
 Additional attributes for Pulse and Timer:   |
Some of the NorsokElementary functions support expansion with n-number of input or output terminals.
The AML-writer shall add additional terminals and may (or shall) use the same RefBaseClassPath as the existing terminals (same RefBaseClassPath shall be used for interchangeable terminals, eg, split outputs).
Examples:
- Split: has a single input (X) and can have several interchangeable outputs (Y1, Y2, ..., Yn).
- Or, XOR, AND, Add and Mul: can have several interchangeable inputs (X1, X2, ..., Xn) and has a single output (Y).
- Opt has a single output (Y) and can have multiple inputs (but they are typically specialized and not interchangeable).
- BlackBox can have multiple inputs and outputs (but they are typically specialized and not interchangeable).
This class is defined as part of the ElementaryFunctionLibrary
| Class Library | Attributes |
|---|---|
 |
 |
Page reference symbols exist as a set of symbols pointing to each other.
The Page reference for Signal has a Unique identifier that can be used as Name.
The AML reader application should find the same Page reference Name in the DrawingReference - AML file and then the signal path can be followed at the opposite drawing.
| Header | Value | Example SignalOffPage | Example SignalOnPage |
|---|---|---|---|
| Name | Name | A4309 | A4309 |
| Description | Description | A-44XSV0544.XL | Not A-43ESV0046.BCL |
| ID | UUID | ……A.. | …..B.. |
| Attributes | Value | Example SignalOffPage | Example SignalOnPage |
|---|---|---|---|
| DrawingReference | DrawingNumber | C151-AS-J-XZ-44002-01 | C151-AS-J-XZ-43001-01 |
Shut-Down / SIS - References
| Header | Value | Example |
|---|---|---|
| Name | Name | SIS-1 |
| ID | UUID | ……. |
| Attributes | Value | Example |
|---|---|---|
| SIS-Notation | Control system Character | E |
| Reference | Reference to SIS-Level | 1.2 |
Sequence References :
| Header | Value | Example |
|---|---|---|
| Name | Name | SEQ.03 |
| ID | UUID | ……. |
| Attributes | Value | Example |
|---|---|---|
| Reference | Reference to sequence step numbers | 1 |
Reference to Electrical Equipment Control
| Header | Value | Example |
|---|---|---|
| Name | Name | MCC-Ref-TagNumber |
| ID | UUID | ……. |
| Attributes | Value | Example |
|---|---|---|
| ReferenceTagNo | Power reference Tag number | |
| ReferenceSystem | Power or Succeeding function | MCC |
| Typical |
The current version of the AML library has defined some common devices used by the SCD.
If devices shall be represented in the InstanceHierarchy or not is not decided yet.
| Header | Value | Example |
|---|---|---|
| Name | Name | A-43VD002 |
| ID | UUID | ……. |
 |
Default properties for all Devices  |
|---|
Some devices with additional properties
| Device with additional attributes | Device with additional attributes |
|---|---|
Damper  |
Actuated Damper  |
Valve  |
Actuated Valve  |
At the SCD, Termination points are given by name and signal directions are given by arrow.
In AML the termination point is defined as a "Signal Interface Class"
The individual Function Block and Logic classes are populated with legal combination of Signal Interface Classes.
The restrictions in the attributes can be used for quality check of the connections between two Interface Classes.
It is recommended that the AML-Writer do such quality check when creating InternalLink between Iterface Classes.
The AML-Reader should also perform such check to ensure legal connection.
This is a Boolean datatype and is used to indicate that the terminal is in use at the SCD.
When creating an instance of e.g. a Function Block then all interface classes from the library is copied to the individual. To know if e.g a warning is used is not possible without additional flag.
"Active = true" give an easy way to find terminals that the AML-Reader should evaluate.
This is type of information is additional information about the connection between the terminals.
The InternalLinks cannot have additional attributes. That is why this is added at each of the connectors.
Ref to Norsok I-005 "Positive logic":
The positive logic shall always be applied for function terminals i.e. there shall be no parameters to invert the signals inside the functions which negate the terminal meaning.
An exception is made for input X on MB where an inverter is added to make it possible to adapt to normally energised or non-energised input signal. The Attribute InvertSignal is used for this purpose and a variant of the "X" is created in the library.
This special class is then added to the MB function Block
Invert is also used at device and reference object and is indicated with double arrows at the SCD.
The library is developed with hierarchical structure with inheritance of attributes.
Attribute restriction are added at the different levels.
This class is created to be able to populate VendorFucntionBlockClass with vendor specific signalInterfaceClasses.
This library should use the same structure and restrictions as in the NorsokSignalClass library.
This is done to be able to run standard consistency checks at attribute level.
- Define the SystemUnitClass if it does not exist. E.g. a vendor specific function block
- Define InterfaceClass object if it don't exist
- Drag a InterfaceClass object onto the object a)
- Change name and description of the new object c)
- check that attribute definition for then new object is correct.
This interface Class is intended to be used by SystemUnitClass: ReferenceClassLibrary
These objects are passing signals and has limited attributes.
This connection class is of AutomationMLInterfaceClassLib PPRConnector.
Ref Part1 6.3: This class is intended for "Connector for interlinking products, resources or processes "
Modelling of Process Flow (Pipes) is not done in this AML library yet.
Some example classes is linked to these interface classes, must be developed more it this shall be used.
SFC is defined in the Norsok standard.
Section under work
