SDD specifications

The SDD consists of a configuration file (.conf in JSON format) and additional files such as images, documents, etc.

Naming scheme of the configuration file:

Format:

<VendorName>-<ProductName>-<Date>-SDD<SDDrevision>.conf

Example:

Schmalz-SCPSt-20200416-SDD1.1.conf

Field	Data type	Remark
VendorName	String	The vendor name of the manufacturer (is not checked)
ProductName	String	The ProductName as assigned by the manufacturer (is not checked)
Date	JJJJMMTT	Creation date of the file (checked by Sicon)
SDDrevision	major.minor, each decimal	Currently 1.1 (under review by Sicon)

The associated images (icon and picture) should be in PNG or JPEG format. All other documents should be in PDF or TXT format.

Naming of the additional files:

Picture (large product picture): <VendorName>-<ProductName>-pic.png

Icon (small product image): <VendorName>-<ProductName>-icon.png

Operating instructions (long): BAL_<Schmalz Art.No.><language><index>.pdf

Operating instructions (short): BAK_<Schmalz art.no.><language><index>.pdf

Where <language> is selected from { en-EN, de-DE, es-ES, it-IT, fr-FR }.

The index is a file revision and must be known when the SDD is created.

Beispiel: BAL_10.06.02.00570_en-EN_00.pdf

The SDD and the additional files are packed as a ZIP (flat - no subdirectories) according to the following naming scheme:

<VendorName>-<ProductName>-<Date>-SDD<SDDrevision>.zip

For IOL add-on SDDs, the naming scheme of the configuration file follows the following format:

<VendorName>-<ProductName>-<Date>-IOLSDD<SDDrevision>.conf

1. Main structure of the configuration file

The main structure of the SDD is as follows:

JSON

{
  "Document": { required },
  "Source": { required },
  "Vendor": { required },
  "BasicInformation": { required },
  "DeviceControl": { optional },

  "Identification": { required },
  "Parameter": { required },
  "Observation": { required },
  "Diagnosis": { required
    "Device status": { optional },
    "Condition monitoring": { optional },
    "Counters": { optional },
    "Timing": { optional },
    "Energy monitoring": { optional },
    "Predictive maintenance": { optional }
  },

  "Events": { optional },

  "XConfig": { optional },
  "Replay": { optional },
  "Reporting": { optional },
  "Updater": { optional },

  "OPCUA": { only for OPCUA - TO BE DEFINED
    "Subdevices": { optional },
    "Events": { optional },
    "Replay": { optional },
    "Reporting": { optional }
  },

  "CyclicData": { optional
    "ProcessDataIn": { optional },
    "ProcessDataOut": { optional },
  }
}

2. Main structure of the configuration file - detail

JSON

{
  "Document": {
    "SDDRevision": "1.1"
  },
  "Source": {
    "SoftwareAdapter": required
    "RootPath": required/optional (only if Schmalz/Generic OPC UA)
  },
  "Vendor": {
    "Name": required
    "Text": required
    "URL": optional
    "Logo": optional
  },
  "BasicInformation": {
    "VendorID": required
    "DeviceID": required
    "ProductName": required
    "ArticleNumber": optional (only if Generic OPC UA)
    "SerialNumber": optional (only if Generic OPC UA)
    "UID": optional (only if Generic OPC UA)
    "LocationTag": optional
    "LocationPos": optional
    "AssetID": optional
    "PictureFileName": optional
    "IconFileName": optional
    "DocumentationNames": optional
    "Description": optional
    "FirmwareUpdatePossible": optional
  },
  "DeviceControl": {
    "Commands": {
      "SystemCommand": {
        "Size": required
        "ParameterDescriptor": required
        "Value": required/optional (required if Schmalz/Generic OPC UA, otherwise optional),
        "Remark": optional
        "Range": required
      }
    }
  },
  "Identification": {
    "Gruppierung1": {
      "Parameter": {
        "Index": required
        "DataType": required
        "BitLength": required/optional (required for DataType = "UIntegerT", "IntegerT")
        "Access": required
        "Label": required
        "ParameterDescriptor": optional 
        "Range": optional 
        "Gradient": optional 
        "Resolution": optional 
        "Offset": optional 
        "Unit": optional
        "Remark": optional
        "Value": optional (only if Schmalz/Generic OPC UA)
        "DefaultValue": optional
      }
    }
  },
  "Parameter": {
    "Gruppierung1": {
      "Gruppierung2": {
        "Gruppierung3": {
          "Gruppierung4": {
            ...
          }
        }
      }
    }
  },
  "Diagnosis": {
    "Device status": { optional },
    "Condition monitoring": { optional },
    "Counters": { optional },
    "Timing": { optional },
    "Energy monitoring": { optional },
    "Predictive maintenance": { optional },
  },
  "Observation": {
  },
  "Events": {
    "EventNumber": {
      "Name": required
      "Remark": required
      "Type": required
      "Description": optional
      "Cause": optional
      "Impact": optional
      "Solution": optional
    }
  },
  "XConfig": {
    "XIndices": required
    "AutomaticReadForEvents": required
    "AutomaticReadForReporting": required
  },
  "Replay": {
    "YIndices": required
    "Triggers": required
  },
  "Reporting": {
    "Trigger": {
      "type": required
      "Code": required/optional (required if type "event", otherwise optional)
      "mode": required/optional (required if type "event", otherwise optional)
    },
    "YIndices": required
  },
  "Updater": {
    "Interval": required
    "Indices": required
  },
    "OPCUA": { only for OPCUA - TO BE DEFINED
      "Subdevices": {
        "p1": {
          "VendorID": required
          "DeviceID": required
          "SerialNumber": required
          "DeviceType": required
          "RootPath": required
          "Parent": required
          "ParentInfo": required
          "LocationTag": optional
          "LocationPos": optional
          "AssetID": required
        },
        "p2": {
        .
        .
        }
      },
    "Events": { optional },
    "Replay": { optional },
    "Reporting": { optional }
  },
  "CyclicData": {
    "ProcessDataIn": {
      "ProcessDataParameter": {
        "Index": required
        "DataType": required
        "Access": required
        "Size": required/optional (required for DataType = "UIntegerT", "IntegerT")
        "Label": required
        "ParameterDescriptor": optional 
        "Range": optional 
        "Gradient": optional 
        "Resolution": optional 
        "Offset": optional 
        "Unit": optional
        "Remark": optional
        "Value": optional
        "DefaultValue": optional
      }
    }
  }
}

3. Description of the configuration file

3.1 Document

The SDD version of the document is entered here. The following format is used:

JSON

"Document": {
    "SDDRevision": "1.1"
  }

3.2 Source

The SoftwareAdapter entry is required. Keys Host and DefaultPort are optional. Key RootPath is required if it is an OPC UA device.

JSON

"Source": {
    "SoftwareAdapter": required
    "RootPath": required/optional
  }

With version 0.5, the value of Software Adapter can be: "OPC_UA" (SICON PLUG Control and Generic) or "MAINDEV" (for main devices).
In SDDs for SICON PLUG adapters, the initial path of all NodeIDs is stored as a string under RootPath. This NodeID is fixed for the PLC: ns=4;s=.p0

All other NodeIDs can be described as strings with the following format:

Path with RootPath → "§§.PathToNodeID"

Path without RootPath → "ns=<number>;s=PathToNodeID"

Example:

OPC UA (SICON PLUG Control [Schmalz] & Generic)

JSON

"Source": {
    "SoftwareAdapter": "OPC_UA",
    "RootPath": "ns=4;s=.SPZiFassgreifer"
  }

Example:

MAINDEV (Schmalz-SCTSi)

JSON

  "Source": {
    "SoftwareAdapter": "MAINDEV"
  }

3.3 Vendor

Contains all important information about the manufacturer.

CODE

"Vendor": {
    "Name": required
    "Text": required
    "URL": required
    "Logo": required
  }

All values must be entered as strings.

Example:

CODE

"Vendor": {
    "Name": "J. Schmalz GmbH", 
    "Text": "www.schmalz.com",
    "URL": "www.schmalz.com",
    "Logo": "Schmalz-logo.png"
 }

3.4 BasicInformation

Keys VendorID, DeviceID and ProductName are required. All others (SerialNumber, LocationTag, LocationPos, AssetID, PictureName, IconName, DocumentationNames and Description) are optional.

JSON

"BasicInformation": {
    "VendorID": required
    "DeviceID": required
    "ProductName": required
    "SerialNumber": optional
    "LocationTag": optional
    "LocationPos": optional
    "AssetID": optional
    "PictureFileName": optional
    "IconFileName": optional
    "DocumentationNames": optional
    "Description": optional
    "FirmwareUpdatePossible": optional
  }

All values - except for "FirmwareUpdatePossible" - must be entered as strings. "FirmwareUpdatePossible" must be entered as true/false.

Key VendorID → VendorID according to the number range system of GPS

Key DeviceID → DeviceID

With an SDD for OPC UA adapters (SICON PLUG Control and Generic), all other values can also be defined as NodeID paths.

Key SerialNumber → Serial number of the device

Key LocationTag → Attachment

Key LocationPos → Place

Key AssetID → Equipment labelling. This key is required for an SDD for SICON PLUG Control

Key ProductName → String for recognising the device

Key PictureFileName → Name of the attached image

Key IconFileName → Name of the attached icon

Key DocumentationNames must be entered as a JSON string in the following format:

Key UsersGuide_[XX] → Operating instructions in [XX] language

Key Datasheet_[XX] → Data sheet in [XX] language

Key InstallationGuide_[XX] → Installation instructions in [XX] language

All names of the existing documents in the SDD .zip file should be described.

Example:

JSON

"DocumentationNames": "{\"UsersGuide_EN\":\"SDD-5000001-BA_EN.pdf\",\"UsersGuide_DE\":\"SDD-5000001-BA_DE.pdf\"}",

Key Description → Device description in plain text (ProductText in IOL)

Key FirmwareUpdatePossible → false or true, describes whether a firmware update can be carried out from Sicon for the device (default = false)

3.5 DeviceControl

This parent key should be defined for devices that support device commands.

The Size, ParameterDescriptor, Range and Value keys must be defined here (Key Value only in the case of an SDD for OPC UA adapters). The rest is entered automatically by the system (Index = 2, Label = "Standard Command", Remark = "Runs the different commands on this device", DataType = "UIntegerT", Access = "w").

JSON

  "DeviceControl": {
    "Commands": {
      "SystemCommand": {
        "Size": required
        "ParameterDescriptor": required
        "Value": required/optional,
        "Range": required,
      }
    }
  }

Size describes the bit length (as an integer).

Range describes all existing commands. These should be formatted as follows:

„[Value 1], [Value 2],..., [Value N]“

Or for value ranges:

„[Value min]-[Value max]“

Or a mixture of both:

„[Value 1], [Value 2],..., [Value N], [Value min]-[Value max]“

Example entry from Range:

NONE

"0,1,4-7"

ParameterDescriptor defines the appropriate description (as a string) for all existing commands. Each command has a specific value and meaning. These should be formatted as follows:

„[Value 1]=[Meaning 1],[Value 2]=[Meaning 2],...,[Value N]=[Meaning N]“

Example entry from ParameterDescriptor:

NONE

"0=Reset erasable counters,1=Calibrate sensor"

Example entry from Value:

NONE

"§§.Parameter.DeviceSettings.Commands"

3.6 Identification, Parameter, Observation & Diagnosis

3.6.1 Nesting for grouping variables

For each of the following parent keys (Identification, Parameter, Observation & Diagnosis), nesting is permitted up to the fourth level. This allows different parameters to be grouped up to four levels deep. The first level starts directly after the parent key.

E.g.: by key parameter

JSON

  "Parameter": {
    "Gruppierung1": {
      "Gruppierung2": {
        "Gruppierung3": {
          "Gruppierung4": {
          
          }
        }
      } 
    }
  }

Once the groupings have been defined, the parameters can be entered.

There are four main areas in which variables are defined:

Identification → Information for identifying the device

Parameter → Device settings

Observation → Variables that are intended for monitoring the device. The variables in this area are read in cyclically using the "postObservation" MQTT mechanism.

Diagnosis → Variables intended for the diagnosis of the device

3.6.2 Parameter standardisation

Keys Index, DataType, Access and Label are required.

The Subindex, Size, ParameterDescriptor, Range, Gradient, Resolution and Offset, Unit, Remark, DefaultValue and Value buttons are optional.

JSON

    "Variable": {
      "Index": required
      "Subindex": optional
	"BitOffset": required if Subindex != 0
      "DataType": required
      "Access": required
      "Label": required
      "Size": required/optional (required for DataType = "UIntegerT", "IntegerT")
      "ParameterDescriptor": optional 
      "Range": optional 
      "Gradient": optional 
      "Resolution": optional 
      "Offset": optional 
      "Unit": optional
      "Remark": optional
      "Value": optional
      "DefaultValue": optional
    }

MainKey variable → Label (name) of the variable in UpperCamelCase format. E.G: Label = "Energy consumption" → MainKey = "EnergyConsumption". Allowed characters are: [a-z], [A-z], [0-9]

Key Index → A unique number that identifies the variable. The same index must not appear more than once.

Key Subindex → A unique number that identifies the variable within the subindex. The same subindex may not appear more than once within an index.

Key BitOffset → When using subindices, the offset of the least significant bit of the date within a complex parameter. Counted from the right (see representation of RecordT in the IODD)

Key DataType → Data type of the variable (as a string). The following values are permitted:

§ IntegerT

§ UIntegerT

§ BooleanT

§ StringT

§ Float32T

§ TimeT

§ TimespanT

§ HexStringT

§ OctetStringT

Key Access → Authorisations for the variable (as a string). The following values are permitted:c

§ „r“ → Read only allowed

§ „rw“ → Reading and writing allowed

§ „w“ → only writing allowed

Key Label → Variable name

Key Size → describes the bit length (as an integer). Required for the following DataTypes: "UIntegerT" and "IntegerT"

Key Unit → Variable unit

Key Remark → Function/description of the variable

Key ParameterDescriptor → Describes the meanings of all possible values. As with the SystemCommand parameter, each value has a specific meaning. This value should be formatted as follows:

„[Value 1]=[Meaning 1],[Value 2]=[Meaning 2],...,[Value N]=[Meaning N]“

The key should be present if Key Range has values with a specific meaning.c

Example:

NONE

"0=Reset erasable counters,1=Calibrate sensor"

Key Range → All possible values of the variable. Similar to ParameterDescriptor, all permitted values should be defined in the following format:

„[Value 1], [Value 2],..., [Value N]“

Or for value ranges:

„[Value min]-[Value max]“

Or a mixture of both:

„[Value 1], [Value 2],..., [Value N], [Value min]-[Value max]“

Examples:

CODE

"2,3,128,129"
"0-999"
"0,3,5,7,100-999"

Key Gradient → Multiplication factor for the correct display of the variable (as a string)

Key Resolution → Display format. May have the following values:

Hex: Hexadecimal notation with postfix "h"
Dec: Decimal number notation without postfix
Dec.x: Decimal number notation with existing precision (x is the number of digits after the decimal point)
Bin: Binary notation with postfix "b"

Example:

CODE

"Bin"
"Hex"
"Dec"
"Dec.1"

Key Offset → Value shift (as string)

Beispiel:

CODE

"12.3"
"-5.1"

The Gradient, Resolution and Offset keys, if present, should always be present as a group. In this case, the value of the variable is changed as follows:

a. The value of the variable is multiplied by Gradient and shifted by the value of the key offset (addition)

Beispiel {“SensorValue”: “2222” & “Gradient”: “0.01” & “Offset”: “-0.2”}

New value of the variable after gradient & offset have been applied:

“SensorValue”: “22.20”

b. The value of the variable is converted into the corresponding format for the display (defined by Key Resolution)

Example {“ SensorValue”: “22.20” & “Resolution”: “Dec.1”}

New value of the variable after resolution has been applied:

“SensorValue”: “22.2”

Key DefaultValue → Standard value of the variable (without using gradient, offset and resolution)

Key Value → Static value of the variable. The NodeID can be entered here for an SDD for OPC UA adapters.

Examples:

CODE

“§§.Observation.Monitoring.ProcessDataIn.RatioComponentGrippedDropped” “ns=4;s=.SPZi.Observation.Monitoring.ProcessDataIn.RatioComponent”
“ns=4;s=|var|CODESYS.Application.IoConfig_Globals_Mapping.Input_1”

Complete example for a parameter/variable:

DataType StringT for OPC UA (SICON PLUG Control and Generic)

JSON

      "Geolocation": {
        "Index": 10,
        "DataType": "StringT",
        "Access": "rw"
        "Label": "Geolocation",
        "Value": "§§.Identification.Localization.Geolocation",
      }

DataType UIntegerT

JSON

      "EnergyConsumptionPerCycle": {
        "Index": 157,
        "DataType":"UIntegerT",
        "Access":"r",
        "Size": 16,
        "Label": "Energy consumption per cycle",
        "Unit": "Ws"
        "Remark": "Add some description to this variable. ToDo!",
        "ParameterDescriptor": "",
        "Range": "0-999",
        "Gradient": "1",
        "Resolution": "Dec",
        "Offset": "0"
      }

3.6.3 Pre-defined indices

The following variables have predefined indices:

IOL-Standard-Parameter (IDs always the same)	Hex value	Dec value
V_SystemCommand	0x0002	2
V_DeviceAccessLocks	0x000C	12
V_VendorName	0x0010	16
V_VendorText	0x0011	17
V_ProductName	0x0012	18
V_ProductID	0x0013	19
V_ProductText	0x0014	20
V_SerialNumber	0x0015	21
V_HardwareRevision	0x0016	22
V_FirmwareRevision	0x0017	23
V_ApplicationSpecificTag	0x0018	24
V_ErrorCount	0x0020	32
V_DeviceStatus	0x0024	36
V_DetailedDeviceStatus	0x0025	37

Schmalz-Standard-Parameter - Identification (IDs not standardised)
Unique ID	0x00F0	240
Feature List	0x00F1	241
Equipment Identification	0x00F2	242
Anlagenkennzeichnung	0x00F5	243
Ortskennzeichen	0x00F6	244
Geolocation	0x00F6	246
Weblink to IODD	0x00F7	247
Weblink to NFC App	0x00F8	248
Storage Location	0x00F9	249
Article Number	0x00FA	250
Article Index	0x00FB	251
Production Date	0x00FC	252
Installation Date	0x00FD	253
Detailed Product Text	0x00FE	254

3.6.4 Pre-defined groupings

The following groupings are predefined for the Diagnosis parent key: "Device status", "Energy monitoring", "Predictive maintenance" and "Condition monitoring"

JSON

  "Diagnosis": {
    "Device status": { },
    "Energy monitoring": { },
    "Predictive maintenance": { },
    "Condition monitoring": { }
  }

The variable(s) for the description of the device status should be defined in the "Device status" grouping.

The variable(s) for describing the energy consumption of the device should be defined in the "Energy monitoring" grouping.

In the "Predictive maintenance" grouping, the variable(s) for predictive maintenance should be defined.

The variable(s) for monitoring the status of the device should be defined in the "Condition monitoring" grouping.

3.6.5 Pre-defined variables in the SICON PLUG Control - MAIN interface

The following variables should be available for the MAIN SDD in the SICON PLUG Control interface:

JSON

"Identification": {
    "Information": {
      "VendorName": {
        "Index": 16,
        "DataType": "StringT",
        "Access": "r",
        "Label": "Vendor name",
        "Remark": "This is the vendor name of the Facility/PLC",
        "Value": "§§.VendorName"
      },
      "VendorText": {
        "Index": 17,
        "DataType": "StringT",
        "Access": "r",
        "Label": "Vendor text",
        "Remark": "This is the vendor text of the Facility/PLC",
        "Value": "§§.VendorText"
      },
      "ProductName": {
        "Index": 18,
        "DataType": "StringT",
        "Access": "r",
        "Label": "Product name",
        "Remark": "This is the product name of the Facility/PLC",
        "Value": "§§.ProductName"
      },
      "ProductText": {
        "Index":20,
        "DataType": "StringT",
        "Access": "r",
        "Label": "Product text",
        "Remark": "This is the product text of the Facility/PLC",
        "Value": "§§.ProductText"
      },
      "SerialNumber": {
        "Index": 21,
        "DataType": "StringT",
        "Access": "r",
        "Label": "Serial number",
        "Remark": "This is the serial number of the Facility/PLC",
        "Value": "§§.SerialNumber"
      },
      "HardwareVersion": {
        "Index": 22,
        "DataType": "StringT",
        "Access": "r",
        "Label": "Hardware version",
        "Remark": "This is the hardware version of the Facility/PLC",
        "Value": "§§.HardwareVersion"
      },
      "FirmwareVersion": {
        "Index": 23,
        "DataType": "StringT",
        "Access": "r",
        "Label": "Firmware version",
        "Remark": "This is the firmware version of the Facility/PLC",
        "Value": "§§.SoftwareVersion"
      },
      "ArticleNumber": {
        "Index": 250,
        "DataType": "StringT",
        "Access": "r",
        "Label": "Article number",
        "Remark": "This is the article number of the Facility/PLC",
        "Value": "§§.ArticleNumber"
      },
      "InstallationDate": {
        "Index": 253,
        "DataType": "StringT",
        "Access": "r",
        "Label": "Installation date",
        "Remark": "This is the installation date of the Facility/PLC",
        "Value": "§§.InstallationDate"
      },
      "ProductionCode": {
        "Index": 255,
        "DataType": "StringT",
        "Access": "r",
        "Label": "Production code",
        "Remark": "This is the production code of the Facility/PLC",
        "Value": "§§.ProductionCode"
      },
	"DeviceType": {
        "Index": 260,
        "DataType": "StringT",
        "Access": "r",
        "Label": "Device type",
        "Remark": "This is the Device type of the SIO device",
        "Value": "§§.DeviceType"
      }
    },
    "Localization": {
      "Geolocation": {
        "Index": 246,
        "DataType": "StringT",
        "Access": "rw",
        "Label": "Geolocation",
        "Remark": "This is the geolocation of the Facility/PLC",
        "Value": "§§.Geolocation"
      },
      "WebLink": {
        "Index": 248,
        "DataType": "StringT",
        "Access": "rw",
        "Label": "Web link",
        "Remark": "This is the web link of the Facility/PLC",
        "Value": "§§.WebLink"
      },
      "StorageLocation": {
        "Index": 249,
        "DataType": "StringT",
        "Access": "rw",
        "Label": "Storage location",
        "Remark": "This is the storage location of the Facility/PLC",
        "Value": "§§.StorageLocation"
      },
      "LinkToIoT": {
        "Index": 256,
        "DataType": "StringT",
        "Access": "rw",
        "Label": "Link to IoT",
        "Remark": "This is the link to IoT of the Facility/PLC",
        "Value": "§§.LinkToIoT"
      },
      "OwnerName": {
        "Index": 257,
        "DataType": "StringT",
        "Access": "rw",
        "Label": "Owner name",
        "Remark": "This is the owner name of the Facility/PLC",
        "Value": "§§.OwnerName"
      }
    }
  },
  "Observation": {
    "Counters": {
      "GlobalCycles": {
        "Index": 140,
        "DataType": "StringT",
        "Access": "r",
        "Label": "Global cycles",
        "Gradient": "1",
        "Resolution": "Dec",
        "Unit": "",
        "Remark": "This are the global cycles of the Facility/PLC",
        "Value": "§§.GlobalCycles"
      }
    }
  },
  "Diagnosis": {
    "Device status": {
      "DeviceStatus": {
        "Index": 36,
        "DataType": "IntegerT",
        "Access": "r",
        "Size": 32,
        "Label": "Device status",
        "Remark": "This is the device status of the Facility/PLC",
        "Value": "§§.DeviceStatus"
      }
    }
  }

3.6.6 Pre-defined variables in SICON PLUG Control interface - SIO device

The following variables should be present in the SICON PLUG Control interface for the SIO device SDD:

JSON

"Identification": {
    "Information": {
      "SerialNumber": {
        "Index": 21,
        "DataType": "StringT",
        "Access": "r",
        "Label": "Serial number",
        "Remark": "This is the serial number of the SIO device",
        "Value": "§§.SerialNumber"
      },
	"DeviceType": {
        "Index": 260,
        "DataType": "StringT",
        "Access": "r",
        "Label": "Device type",
        "Remark": "This is the Device type of the SIO device",
        "Value": "§§.DeviceType"
      }
    }
  },
  "Diagnosis": {
    "Device status": {
      "DeviceStatus": {
        "Index": 36,
        "DataType": "IntegerT",
        "Access": "r",
        "Size": 32,
        "Label": "Device status",
        "Remark": "This is the device status of the SIO device",
        "Value": "§§.DeviceStatus"
      }
    }
  }

3.7 Events

Parent-Key Events contains all information relating to events and has the following structure:

JSON

  "Events": {
    "EventCode": {
      "Type": required
      "LanguageCode": {
        "Name": required
        "Remark": required
        "Description": optional
        "Cause": optional
        "Impact": optional
        "Solution": optional
      },
      "LanguageCode": {
        "Name": required
        "Remark": required
        "Description": optional
        "Cause": optional
        "Impact": optional
        "Solution": optional
      }
    }
  }

Main key EventCode → Code for recognising the event

Key Type → Event type. May have the following value:

„Error“
„Warning“
„Notification“

Sub-levels for multilingualism: LanguageCode → Language code for the subordinate texts. 2-letter codes according to ISO 639-1 such as "en", "de", etc. are used. There must always be at least "en".

There are the following sub-keys for each language:

Key Name → Event text

Key Remark → additional information

Key Description → describes the event.

Key Cause → describes the cause of the event.

Key Impact → describes the effect of the event.

Key Solution → describes the remedy for the event.

Example:

JSON

"Events": {
    "20736": {
      "Type": "Error",
      "en": {
        "Name": "Undervoltage US",
        "Remark": "Check application",
        "Description": "Primary power supply US is too low",
        "Cause": "Use of insufficient power supply or voltage drop on cabli…",
        "Impact": "Proper operation of the device cannot be ensured…",
        "Solution": "Check specification of power supply unit…"
      },
      "de": {
        "Name": "Unterspannung US",
        "Remark": "Anwendung überprüfen",
        "Description": "Haupt-Versorgungsspannung US ist zu niedrig",
        "Cause": "Hoher Spannungsabfall in Zuleitung, Netzteil defekt",
        "Impact": "Ventilfunktion beeinträchtigt, Datenverlust",
        "Solution": "Zuleitung und Netzteil überprüfen"
      }
    }
  }

3.8 XConfig

The parent key must be defined if the Reporting parent key is defined. It opens up the option of defining X values for the display of events & reporting (Y values).

For example: time, cycles, ...

Key XIndices → Indices of the variables that are to be delivered as XValues for events and reporting (as an array, max. 4 indices permitted). The elements in the array are to be written as a string ("Index.Subindex"). There must be numerical data objects behind the specified Index.Subindex combinations; a composite index must not be accessed via subindex 0.

Key AutomaticReadForEvents → Defines whether the XIndices should be read automatically when processing an event (true/false)

Key AutomaticReadForReporting → Defines whether the XIndices should be read automatically when processing a report (true/false)

All keys are required. The structure and information is as follows:

JSON

  "XConfig": {
    "XIndices": ["140.0","143.0"],
    "AutomaticReadForEvents": true,
    "AutomaticReadForReporting": true
  }

The semantics of the first two XIndices are pre-defined as:

X1= GlobalCycles

X2= PartCycles

3.9 Replay

Replay is used to specify the indices and trigger conditions for the replay feature.

JSON

  "Replay": {
    "YIndices": ["64.1","65.1","66.2","148.0","149.0"],
    "Triggers": [
      {"Code":36002,"Mode":"SINGLESHOT"},
      {"Code":12345,"Mode":"DISAPPEARS"}
    ]
  }

Key indices: Indices of the variables that are to be included in the replay (as an array, max. 30 indices permitted). The elements in the array are strings, with the option of specifying a subindex. There must be numerical data objects behind the specified index-subindex combinations; a composite index may not be accessed via subindex 0.

Key Triggers lists an array of individual trigger conditions. These are OR-linked. Each trigger condition is an object consisting of the following keys:

Code: Event code to be used for triggering the replay.
Mode: Event mode to be used for triggering the replay. Possible values:

o „APPEARS“

o „DISAPPEARS“

o „SINGLESHOT“

Event 36002, SINGLESHOT, must always be present as a minimum ("user trigger").

3.10 Reporting

The Reporting parent key may only be defined if the Xconfig parent key is also defined. It contains the settings for the cyclical postReport messages and has the following structure:

JSON

"Reporting": {
    "Trigger": {
      "type": required
      "Code": required (only if type "event")
      "mode": required (only if type "event")
    },
    "YIndices": required
    "SummaryAccess": optional (only implemented for IO-Link devices so far)
    {
    	"Index": required
    	"Offsets": required
    }
    }

Key Trigger has the following subkeys:

Type: describes the trigger type of the reporting message. The key may have the following values:

o „time“

o „event“

o „self-triggered“

§ Code: Event code to be used for triggering the postReport message. The key must only be present if Key Type → "event".

§ Mode: Event mode to be used for triggering the postReport message. The key must only be present if Key Type → "event". Possible values:

o „APPEARS“

o „DISAPPEARS“

o „SINGLESHOT“

§ SamplingRate: Time interval between 2 reporting messages if Key Type -> "time". (Interval in ms)

Key YIndices: Indices of the variables that should be delivered in the reporting message (as an array, max. 20 indices permitted). The elements in the array are to be written as objects. It is also possible to write indices with subindices. There must be numerical data objects behind the specified index-subindex combinations; a composite index may not be accessed via subindex 0.

The indices are the keys of an object and the value is a string that may have the following values: "EM", "CM" and "PM". These values define the grouping for the reporting variables, with the following meaning:

EM → Energy Monitoring

PM → Predictive Maintenance

CM → Condition Monitoring

Example:

CODE

[{"41.0": "EM"},
{"42.0": "PM"},
{"43.0": "PM"},
{"44.0": "CM"},
{"45.0": "CM"},
{"46.0": "CM"},
{"47.0": "CM"},
{"48.0": "CM"},
{"49.0": "CM"}]

Key SummaryAccess → Object with display of a reporting summary index

Index→ Index on which all reporting data can be read in summarised form
Offsets → Array length 1...20, specification of the respective byte index (starting at 0, from left to right) where the reporting value can be found in the collective index (order of the offset array corresponds to the order in the indices array).

3.11 Updater

The parent key updater is optional and contains the settings for regular updating of static variables. It has the following structure:

JSON

"Updater": {
  "Interval": required
  "Indices": required
}

Key Interval: Time interval for updating the variables in ms.

Key Indices: Indices of the variables that should be updated (as an array).

Example:

3.12 OPCUA

This section is still being revised.

3.12.1 Subdevices

This parent key is optional and can be used for the registration of sub-elements or sub-devices of a Schmalz device. This key must not be used in an SDD of an OPCUA sub-device. The following structure exists:

JSON

  "Subdevices": {
    "p1": {
      "VendorID": required
      "DeviceID": required
      "SerialNumber": required
      "DeviceType": required
      "RootPath": required/optional (required if Schmalz OPC UA, otherwise optional)
      "Parent": required
      "ParentInfo": required
      "LocationTag": optional
      "LocationPos": optional
      "AssetID": required
    },
    "p2":
    .
    .
  }

Each object describes a sub-device and consists of the following keys:

Parent-Key p[x] → Must be numbered consecutively

Main key VendorID →

Main key DeviceID →

Main key SerialNumber → Serial number of the device

Main key DeviceType → Device type "sdd" or "iodd"

Main key RootPath → Initial path of the sub-device from the OPC UA server

Main key Parent → Parent-Key des Vorgängers vom Untergerät (als String)

Main key ParentInfo → Extra information from the predecessor of the sub-device (e.g.: connection port)

Main key LocationTag → Installation of the sub-device (as a string)

Main key LocationPos → Location of the sub-device (as a string)

Main key AssetID → Equipment labelling (as a string)

Example for a Schmalz OPC UA device:

JSON

"Subdevices": {
    "p1": {
      "RootPath": "ns=4;s=.p1",
      "Parent": "p0",
      "ParentInfo": "I/O Klemme 1.0",
      "VendorID": "§§.BasicInformation.VendorID",
      "DeviceID": "§§.BasicInformation.DeviceID",
      "SerialNumber": "§§.BasicInformation.SerialNumber",
      "DeviceType": "sdd",
      "AssetID": "-B1"
    },
    "p3": {
      "RootPath": "ns=4;s=.p3",
      "Parent": "p0",
      "ParentInfo": "I/O Klemme 1.1",
      "VendorID": "§§.BasicInformation.VendorID",
      "DeviceID": "§§.BasicInformation.DeviceID",
      "SerialNumber": "§§.BasicInformation.SerialNumber",
      "DeviceType": "sdd",
      "AssetID": "-A1"
    },
    "p7": {
      "RootPath": "ns=4;s=.p7",
      "Parent": "p0",
      "ParentInfo": "I/O Klemme 2.0 - 2.3",
      "VendorID": "§§.BasicInformation.VendorID",
      "DeviceID": "§§.BasicInformation.DeviceID",
      "SerialNumber": "§§.BasicInformation.SerialNumber",
      "DeviceType": "sdd",
      "AssetID": "-A2"
    },
    "p12": {
      "RootPath": "ns=4;s=.p12",
      "Parent": "p0",
      "ParentInfo": "I/O Klemme 2.0 - 2.3",
      "VendorID": "234",
      "DeviceID": "987654321",
      "SerialNumber": "§§.SerialNumber",
      "DeviceType": "sdd",
      "LocationPos": "+Flach",
      "AssetID": "-F1"
    }
  }

3.12.2 Events (OPCUA)

The parent key must be defined for SDDs for Schmalz OPC UA devices and must not be used for an SDD of an OPC UA sub-device.

Key DataPath → NodeID for the event string of the OPC UA server

Key HandshakePath → NodeID for the OPC UA server handshake

Key Format → Format of the event string in the OPCUA server

Key Modes → Description of all event modes (as an array of strings)

Key Types → Description of all event types (as an array of strings)

All keys are required. The structure and information is as follows:

JSON

"OPCUA": {
  "Events": {
    "DataPath": "§§.Events",
    "HandshakePath": "§§.EventsHandshake",
    "Format":"timestamp;GlobalCycles;PartNumber;PartText;PartCycles;mode;type;Subdevice;code",
    "Modes": ["UNKNOWN", "SINGLESHOT", "APPEARS", "DISAPPEARS"],
    "Types": ["UNKNOWN", "Notification", "Warning", "Error"]
  }
}

3.12.3 Replay (OPCUA)

To be defined..

3.12.4 Reporting (OPCUA)

Key DataPath → NodeID for the reporting data (as a string) of the OPC UA server

Key HandshakePath →NodeID for the reporting handshake of the OPC UA server

CODE

"DataPath": "§§.ReportingData",
"HandshakePath": "§§.ReportingHandshake",

Key Format must be defined for Schmalz OPC UA devices. This describes the format of the variables that are supplied by the OPC UA device in the reporting string before the actual reporting data.

Example:

CODE

"Format": "timestamp;GlobalCycles;PartNumber;PartText;PartCycles;Subdevice",

Example:

JSON

"OPCUA": {
  "Reporting": {
    "DataPath": "§§.Events",
    "HandshakePath": "§§.EventsHandshake",
    "Format":"timestamp;GlobalCycles;PartNumber;PartText;PartCycles;mode;type;Subdevice;code"
  }
}

3.13 CyclicData

The parent key "CyclicData" is optional and allows the definition of cyclic process data for the device. These are then retrieved using the MQTT mechanism getDynData or startCyclicData.

JSON

"CyclicData": { optional
  "ProcessDataIn": { optional
    "ProcessDataInParameter1": {
      "Index": required
      "DataType": required
      "Access": required
      "Size": conditional (required for DataType = "UIntegerT", "IntegerT")
      "Label": required
      "ParameterDescriptor": optional 
      "Range": optional 
      "Gradient": optional 
      "Resolution": optional 
      "Offset": optional 
      "Unit": optional
      "Remark": optional
      "Value": optional
      "DefaultValue": optional
    },
    "ProcessDataInParameter2": {
        ...
    }
  },
  "ProcessDataOut": { optional
    "ProcessDataOutParameter1": {
        ...
    }
  }
}

Keys ProcessDataIn, ProcessDataOut: if CyclicData is present, at least one of these keys must be present. "In" describes the data that the device supplies to a controller as process data, while "Out" describes the data that is sent from the controller to the device.

Keys ProcessDataInParameter1, ProcessDataInParameter2 etc.: provide reference names for the individual elements of the CyclicData. These are later used as object names when sending on MQTT ?

All other keys are equivalent to those in the variable definition (Identification, Parameter, Observation etc.). Does the ?

To clarify:

Index/subindex available, optional or always? What is done with it ?

At least with eMQTT-based devices, a specification of BitOffset and BitLength should always be included and thus possibly also a subindex ?

For comparison, example from old Spec v0.3:

JSON

     "RatioComponentGrippedDropped": { 
        "Index": 157, 
        "DataType":"UIntegerT", 
        "Access":"r", 
        "Size": 16, 
        "Label": "Ratio - component gripped/dropped", 
        "Range": "0-100", 
        "Gradient": "1", 
        "Resolution": "Dec.1", 
        "Offset": "0" 
        "Value": "§§.Observation.Monitoring.….RatioComponentGrippedDropped", 
      }

3.14 MappedIndices

The MappedIndices parent key is optional and contains the settings for indices that are synchronised with internal SICON.OS values both when reading and writing. Currently, only the value "Geolocation" exists. MappedIndices has the following structure:

JSON

"MappedIndices": {
	"Geolocation": {
	  "Format": required
	  "Index": required
	}
}

Key Format: Format string that represents the formatting of the index.

Key Index: Index of the variable to be synchronised (as a string).

Example:

JSON

"MappedIndices": {
	"Geolocation": {
	  "Format": "%LAT_10_DC_POINT;%LONG_10_DC_POINT",
	  "Index": "246.0"
	}
}

3.15 EventGroups

The EventGroups parent key is optional and contains event groups (array) with settings (object) for events that belong together (because they represent a status, for example) and values/aggregates that can be derived/calculated from them. EventGroups has the following structure:

JSON

"EventGroups": [
	{
		"GroupName": required
		"EventCodes": required
		"Computed": [
		 	{
				"Name": required
				"Equation": required
			}
		]
	}
]

Key GroupName: Name (unique) of the group that is displayed in the frontend

Key EventCode: Array of objects with code and label that are part of the group

Key Computed: Array of objects of values/aggregates to be derived/calculated, with the following subkeys:

Key Name: Name (unique) of the value to be displayed in the frontend

Key Equation: math. Formula for calculating this value, with possible variables:

timeSumEEVENTCODE: totalled time for which this EventCode was active

Example:

JSON

"EventGroups": [
	{
		"GroupName": "Vacuum Generator Status",
		"EventCodes": [
{
"Code": 1000,
"Label": "pump off"
},
{
"Code": 1001,
"Label": "pump on"
}
],
		"Computed": [
		 	{
				"Name": "Pump Off Time",
				"Equation": "timeSumE1000"
			},
		 	{
				"Name": "Pump On Time",
				"Equation": "timeSumE1001"
			},
		 	{
				"Name": "working Time",
				"Equation": "timeSumE1000 + timeSumE1001"
			},
		 	{
				"Name": "Score",
				"Equation": "timeSumE1001 / (timeSumE1000 + timeSumE1001) * 100"
			}
		]
	}
]

5. SDD for IO-Link devices

For IO-Link devices, it is possible to describe further information (which is not mapped in the IODD) using the SDD specified here.

The following areas can be extended by an SDD:

Information about documentation (Key DocumentationNames in BasicInformation)
Parent-Key „XConfig“
Parent-Key „Reporting“
Parent-Key „Updater“
Parent-Key „MappedIndices“
Parent-Key „EventGroups“
Parent-Key "Events"
- To expand an event from the IODD, only the text Cause, Impact, Solution and Remark should be specified.
- An event can also be newly defined that does not even exist in the IODD. Then at least the type and the name must also be defined here.

The following structure should be used for this:

JSON

{
  "Document": {
    "SDDRevision": erforderlich
  },
  "BasicInformation": {
    "VendorID": required
    "DeviceID": required
    "DocumentationNames": optional
  },
  "XConfig": { optional },
  "Reporting": { optional },
  "XConfig": { optional },
  "Updater": { optional },
  "Events": { optional }
}

Example: SDD for IO-Link device VSi

JSON

{
  "Document": {
    "SDDRevision": "1.1"
  },
  "BasicInformation": {
    "VendorID": 234,
    "DeviceID": 100213
    "DocumentationNames": "{\"UsersGuide_EN\":\"VSi-100610-BA-EN.pdf\"}"
  },
  "XConfig": {
    "XIndices": ["140.0","143.0"],
    "AutomaticReadForEvents": true,
    "AutomaticReadForReporting": true
  },
  "Reporting": {
    "Trigger": {
      "type": "event",
      "code": 35872,
      "mode": "APPEARS"
    },
    "YIndices": [{"160.0": "CM"}, {"66.2": "CM"}]
  },
  "Updater": {
    "Interval": 10000,
    "Indices": ["36.0"]
  },
  "Events": {
    "20736": {
      "en": {
        "Cause": "Use of insufficient power supply or voltage drop on cabli…",
        "Impact": "Proper operation of the device cannot be ensured…",
        "Solution": "Check specification of power supply unit…"
      },
      "de": {
        "Cause": "Hoher Spannungsabfall in Zuleitung, Netzteil defekt",
        "Impact": "Ventilfunktion beeinträchtigt, Datenverlust",
        "Solution": "Zuleitung und Netzteil überprüfen"
      }
    }
  }
}

These special SDDs for IO-Link devices are named according to the following scheme:

<VendorName>-<ProductName>-<Date>-IOLSDD<SDDrevision>.conf

4. Document revision

21.08.2019	Update to SDD0.3 (new naming scheme)
04.02.2020	v0.4.0 – Renaming, restructuring Observation and X/Y indices
05.05.2020	v0.4.1 – Attributes FirmwareUpdatePossible added under BasicInformation
11.05.2020	v0.5.0 – Adaptation / revision to implemented version
27.05.2020	v0.5.3 – Transparency/Corrections, Definition Replay.
10.06.2020	v1.0.0 – Corrections to the names of Replay, Reporting, Updater. Reorganisation of OPCUA. Release of the spec as v1.0.0
18.08.2020	v1.1.0 – Extension of the events to include multilingualism. Extension of IOLSDD with events
14.01.2021	v1.2.0 – New section "MappedIndices" added
20.01.2021	v1.2.1 – CyclicData has been reactivated, no longer deprecated
10.02.2021 10.03.2021	v1.3.0 – New section "EventGroups" added v1.3.1 – EventGroups: EventCodes are now objects with code and label