Table of Contents |
---|
Introduction
...
Table of Contents |
---|
Introduction
Being able to configure the way a protocol plugin will manage the communication with the remote servers or clients using the protocol stack parameters, whether communication is secured or not, how the messages attributes are translated from the input protocol data model to the output protocol data model and what kind of rules (filters, math, routing, etc..) to apply to the messages that are exchanges with the remote systems are key features of any protocol translation gateway.
...
The pivot object model is based on 61850 semantic.
PIVOTTM PIVOT TM model, representation of a tele measurement
Attribute | Description | Expected values | Mandatory |
---|
PIVOT.GTIM.Beh.stVal | ? |
PIVOT.GTIM.Cause.stVal | Cause of transmission | COT Cause |
of Transmission - FledgePower - LF Energy | Yes |
PIVOT.GTIM.ChgValCnt |
.stVal | ? | ||
PIVOT.GTIM.ComingFrom |
Source protocol name | IEC103, IEC104, TASE.2, OPCUA, 61850, etc... | Yes | |
PIVOT.GTIM.Confirmation |
.stVal | Indicates positive or negative confirmation of activation | true, false, DEFAULT=false | |
PIVOT.GTIM.Identifier |
Unique identifier of the pivot object | Any non-empty string | Yes | |
PIVOT.GTIM.{CDC} |
Common Data Class representing the information object | MVTyp | Yes | |
PIVOT.GTIM.NormalSrc.stVal | ? |
PIVOT.GTIM.NormalVal.stVal | ? |
PIVOT.GTIM. |
Example of a pivot model instance representing a Tele Measurement:
...
language | js |
---|
...
TmOrg.stVal | Timestamp origin, genuine = source otherwise substituted | genuine, substituted, DEFAULT = genuine | Yes |
PIVOT.GTIM.TmValidity.stVal | Timestamp validity | valid, invalid, DEFAULT = valid | Yes |
Example of a pivot model instance representing a Tele Measurement:
Code Block | ||
---|---|---|
| ||
{
"@xmlns:xs": "http://www.w3.org/2001/XMLSchema",
"PIVOT": {
"GTIM": {
"Beh": {
"stVal": "on"
},
"Cause": {
"stVal": 1
},
"ChgValCnt": {
"stVal": 1
},
"ComingFrom": "String",
"Confirmation": {
"stVal": true
},
"Identifier": "String",
"MvTyp": {
"mag": {
"f": 0.1,
"i": 1
},
"q": {
"DetailQuality": {
"badReference": true,
"failure": true,
"inconsistent": true,
"innacurate": true,
"oldData": true,
"oscillatory": true,
"outOfRange": true,
"overflow": true
},
"Source": "process",
"Validity": "good",
"operatorBlocked": true,
"test": true
},
"t": {
"FractionOfSecond": 1,
"SecondSinceEpoch": 1,
"TimeQuality": {
"clockFailure": true,
"clockNotSynchronized": true,
"leapSecondKnown": true,
"timeAccuracy": 1
}
}
},
"NormalSrc": {
"stVal": "TELEMETERED"
},
"NormalVal": {
"stVal": "NORMAL"
},
"Origin": {
"q": {
"DetailQuality": {
"badReference": true,
"failure": true,
"inconsistent": true,
"innacurate": true,
"oldData": true,
"oscillatory": true,
"outOfRange": true,
"overflow": true
},
"Source": "process",
"Validity": "good",
"operatorBlocked": true,
"test": true
},
"stVal": "String",
"t": {
"FractionOfSecond": 1,
"SecondSinceEpoch": 1,
"TimeQuality": {
"clockFailure": true,
"clockNotSynchronized": true,
"leapSecondKnown": true,
"timeAccuracy": 1
}
}
},
"TmOrg": {
"stVal": "genuine"
},
"TmValidity": {
"stVal": "VALID"
}
}
}
} |
Example of a pivot model instance representing a Tele Signal:
...
language | js |
---|
...
PIVOT TS model, representation of a tele signal
Attribute | Description | Expected values | Mandatory |
---|---|---|---|
PIVOT.GTIS.Beh.stVal | ? | ||
PIVOT.GTIS.Cause.stVal | Cause of transmission | COT Cause of Transmission - FledgePower - LF Energy | Yes |
PIVOT.GTIS.ChgValCnt.stVal | ? | ||
PIVOT.GTIS.ComingFrom | Source protocol name | IEC103, IEC104, TASE.2, OPCUA, 61850, etc... | Yes |
PIVOT.GTIS.Confirmation.stVal | Indicates positive or negative confirmation of activation | true, false, DEFAULT=false | |
PIVOT.GTIS.Identifier | Unique identifier of the pivot object | Any non-empty string | Yes |
PIVOT.GTIS.{CDC} | Common Data Class representing the information object | SPSTyp, DPSTyp, BSCTyp | Yes |
PIVOT.GTIS.NormalSrc.stVal | ? | ||
PIVOT.GTIS.NormalVal.stVal | ? | ||
PIVOT.GTIS.TmOrg.stVal | Timestamp origin, genuine = source otherwise substituted | genuine, substituted, DEFAULT = genuine | Yes |
PIVOT.GTIS.TmValidity.stVal | Timestamp validity | valid, invalid, DEFAULT = valid | Yes |
Example of a pivot model instance representing a Tele Signal:
Code Block | ||
---|---|---|
| ||
{ "@xmlns:xs": "http://www.w3.org/2001/XMLSchema", "PIVOT": { "GTIS": { "Beh": { "stVal": "on" }, "Cause": { "stVal": 1 }, "ChgValCnt": { "stVal": 1 }, "stValComingFrom": "intermediate-stateString", "tConfirmation": { "FractionOfSecondstVal": 1,true }, "DpsTyp": { "SecondSinceEpochq": 1,{ "TimeQualityDetailQuality": { "clockFailurebadReference": true, "clockNotSynchronizedfailure": true, "leapSecondKnowninconsistent": true, "timeAccuracyinnacurate": 1true, } }"oldData": true, }, "Identifieroscillatory": "String"true, "NormalSrcoutOfRange": {true, "stValoverflow": "TELEMETERED"true }, "NormalValSource": {"process", "stValValidity": "NORMALgood", }, "OriginoperatorBlocked": {true, "qtest": {true }, "DetailQualitystVal": { "intermediate-state", "badReferencet": true,{ "failureFractionOfSecond": true1, "inconsistentSecondSinceEpoch": true1, "innacurateTimeQuality": true,{ "oldDataclockFailure": true, "oscillatoryclockNotSynchronized": true, "outOfRangeleapSecondKnown": true, "overflowtimeAccuracy": true1 }, } "Source": "process"}, "ValidityIdentifier": "goodString", "operatorBlockedNormalSrc": true,{ "teststVal": true"TELEMETERED" }, "stValNormalVal": "String",{ "tstVal": {"NORMAL" }, "FractionOfSecondOrigin": 1,{ "SecondSinceEpochq": 1,{ "TimeQualityDetailQuality": { "clockFailurebadReference": true, "clockNotSynchronizedfailure": true, "leapSecondKnowninconsistent": true, "timeAccuracyinnacurate": 1true, } } "oldData": true, }, "SpsTyposcillatory": {true, "qoutOfRange": {true, "DetailQualityoverflow": {true "badReference": true}, "failureSource": true"process", "inconsistentValidity": true"good", "innacurateoperatorBlocked": true, "oldDatatest": true, }, "oscillatorystVal": true"String", "outOfRanget": true,{ "overflowFractionOfSecond": true1, }"SecondSinceEpoch": 1, "SourceTimeQuality": "process",{ "ValidityclockFailure": "good"true, "operatorBlockedclockNotSynchronized": true, "testleapSecondKnown": true, }, "stValtimeAccuracy": true,1 "t": { } } }, "FractionOfSecondSpsTyp": 1,{ "SecondSinceEpochq": 1,{ "TimeQualityDetailQuality": { "clockFailurebadReference": true, "clockNotSynchronizedfailure": true, "leapSecondKnowninconsistent": true, "timeAccuracyinnacurate": 1true, } "oldData": true, } "oscillatory": true, }, "TmOrgoutOfRange": {true, "stValoverflow": "genuine"true }, "TmValiditySource": {"process", "stValValidity": "VALIDgood", } } } } |
Example of a pivot model instance representing a Tele Command:
Code Block | ||
---|---|---|
| ||
{ "@xmlns:xs": "http://www.w3.org/2001/XMLSchema", "PIVOTTC"operatorBlocked": true, "test": true }, "stVal": true, "t": { "GTIC": { "BehFractionOfSecond": {1, "stValSecondSinceEpoch": "on"1, }, "CauseTimeQuality": { "stValclockFailure": 1true, }, "ComingFromclockNotSynchronized": "String"true, "DevIdleapSecondKnown": {true, "nametimeAccuracy": "String"1 }, "DevSt": {} "q": { }, "DetailQualityTmOrg": { "badReferencestVal": true, "failure": true,"genuine" "inconsistent": true}, "innacurateTmValidity": true,{ "oldDatastVal": true, "oscillatory": true,"VALID" } "outOfRange": true, "overflow": true }, "Source": "process", "Validity": "good", "operatorBlocked": true, "test": true }, "stVal": true, "t": { "FractionOfSecond": 1, "SecondSinceEpoch": 1, "TimeQuality": { "clockFailure": true, "clockNotSynchronized": true, "leapSecondKnown": true, "timeAccuracy": 1 } } }, "DpcTyp": { "ctlVal": true, "q": { "DetailQuality": { "badReference": true, "failure": true, "inconsistent": true, "innacurate": true, "oldData": true, "oscillatory": true, "outOfRange": true, "overflow": true }, "Source": "process", "Validity": "good", "operatorBlocked": true, "test": true } } } |
PIVOT TC model, representation of a tele command
Attribute | Description | Expected values | Mandatory |
---|---|---|---|
PIVOT.GTIC.Beh.stVal | defines different behaviours of a control object: - Direct control with normal security: dct-ctl-wns | enum: dct-ctl-wns, dct-ctl-wes, sbo-ctl-wns, sbo-ctl-wes, DEFAULT = dct-ctl-wes | No |
PIVOT.GTIC.Cause.stVal | Cause of transmission | COT Cause of Transmission - FledgePower - LF Energy | No |
PIVOT.GTIC.ComingFrom | Source protocol name | IEC103, IEC104, TASE.2, OPCUA, 61850, etc... | Yes |
PIVOT.GTIC.DevId.name | ? | No | |
PIVOT.GTIC.{CDC} | Common Data Class representing the information object | SPCTyp, DPCTyp, INCTyp, APCTyp, BSCTyp | Yes |
PIVOT.GTIC.Identifier | Unique identifier of the pivot object | Any non-empty string | Yes |
PIVOT.GTIC.Qu.stVal | ? | No | |
PIVOT.GTIC.ServiceType.stVal | ? | No | |
PIVOT.GTIC.Tag.stVal | ? | No | |
PIVOT.GTIC.TagClass | ? | No | |
PIVOT.GTIC.TaggedReason | ? | No | |
PIVOT.GTIC.TmOrg | Timestamp origin, genuine = source otherwise substituted | genuine, substituted, DEFAULT = genuine | No |
PIVOT.GTIC.TmStamp | Timestamp | No |
Example of a pivot model instance representing a Tele Command:
Code Block | ||
---|---|---|
| ||
{ "@xmlns:xs": "http://www.w3.org/2001/XMLSchema", "PIVOT": { "GTIC": { "Beh": { "stVal": "dct-ctl-wes" }, "Cause": { "stVal": 1 }, "ComingFrom": "String", "DevId": { "name": "String" }, "stValDevSt": "intermediate-state",{ "tq": { "FractionOfSecondDetailQuality": 1,{ "SecondSinceEpochbadReference": 1true, "TimeQualityfailure": {true, "clockFailureinconsistent": true, "clockNotSynchronizedinnacurate": true, "leapSecondKnownoldData": true, "timeAccuracyoscillatory": 1true, } "outOfRange": true, } "overflow": true }, "IdentifierSource": "Stringprocess", "QuValidity": {"good", "stValoperatorBlocked": 1true, }, "ServiceTypetest": { true }, "stVal": "select" }, true, "SpcTypt": { "ctlValFractionOfSecond": true1, "qSecondSinceEpoch": {1, "DetailQualityTimeQuality": { "badReferenceclockFailure": true, "failureclockNotSynchronized": true, "inconsistentleapSecondKnown": true, "innacuratetimeAccuracy": true,1 "oldData": true, } } "oscillatory": true}, "outOfRangeDpcTyp": true,{ "overflowctlVal": true }, "Sourceq": "process",{ "ValidityDetailQuality": "good",{ "operatorBlockedbadReference": true, "testfailure": true, }, "stValinconsistent": true, "t": { "FractionOfSecondinnacurate": 1true, "SecondSinceEpocholdData": 1true, "TimeQualityoscillatory": {true, "clockFailureoutOfRange": true, "clockNotSynchronizedoverflow": true, "leapSecondKnown": true}, "timeAccuracySource": 1"process", } }"Validity": "good", }, "TagoperatorBlocked": {true, "stValtest": "NO-TAG"true }, "TagClassstVal": {"intermediate-state", "qt": { "DetailQualityFractionOfSecond": {1, "badReferenceSecondSinceEpoch": true1, "failureTimeQuality": true,{ "inconsistentclockFailure": true, "innacurateclockNotSynchronized": true, "oldDataleapSecondKnown": true, "oscillatorytimeAccuracy": true,1 "outOfRange": true,} "overflow": true } }, "SourceIdentifier": "processString", "Qu": { "ValiditystVal": "good",1 }, "operatorBlockedServiceType": true,{ "teststVal": true"select" }, "SpcTyp": { "stValctlVal": true, "tq": { "FractionOfSecondDetailQuality": 1,{ "SecondSinceEpochbadReference": 1true, "TimeQualityfailure": {true, "clockFailureinconsistent": true, "clockNotSynchronizedinnacurate": true, "leapSecondKnownoldData": true, "timeAccuracyoscillatory": 1true, } } "outOfRange": true, "overflow": true }, "TaggedReasonSource": "Stringprocess", "TmOrgValidity": {"good", "stValoperatorBlocked": "genuine"true, }, "TmStamptest": {true "q": { }, "DetailQualitystVal": {true, "badReferencet": true,{ "failureFractionOfSecond": true1, "inconsistentSecondSinceEpoch": true1, "innacurateTimeQuality": true,{ "oldDataclockFailure": true, "oscillatoryclockNotSynchronized": true, "outOfRangeleapSecondKnown": true, "overflowtimeAccuracy": true1 }, } }, "SourceTag": "process",{ "ValiditystVal": "goodNO-TAG", }, "operatorBlockedTagClass": true,{ "testq": true{ }, "stValDetailQuality": { "FractionOfSecondbadReference": 1true, "SecondSinceEpochfailure": 1true, "TimeQualityinconsistent": {true, "clockFailureinnacurate": true, "clockNotSynchronizedoldData": true, "leapSecondKnownoscillatory": true, "timeAccuracyoutOfRange": 1true, } "overflow": true }, "tSource": {"process", "FractionOfSecondValidity": 1"good", "operatorBlocked": true, "test": true }, "stVal": true, "t": { "FractionOfSecond": 1, "SecondSinceEpoch": 1, "TimeQuality": { "clockFailure": true, "clockNotSynchronized": true, "leapSecondKnown": true, "timeAccuracy": 1 } } }, } } } |
Protocol translation process
...
Protocol translation configuration
Code Block | ||
---|---|---|
| ||
{ "protocol_translation":{ "name":"SAMPLE", "version":"1.0", "mapping_rules":[ { "input_type":"M_SP_TB_1", "output_type":"SpsTyp", "mapping_rule":"104toP_1" }, { "input_type":"M_DP_TB_1", "output_type":"DpsTyp", "mapping_rule":"104toP_2" }, { "input_type":"M_ME_NA_1", "output_type":"MvTyp", "mapping_rule":"104toP_3" }, { "input_type":"M_ME_NC_1", "output_type":"MvTyp", "mapping_rule":"104toP_4" }, { "input_type":"SpsTyp", "output_type":"M_SP_TB_1", "mapping_rule":"Pto104_1" }, { "input_type":"DpsTyp", "output_type":"M_DP_TB_1", "mapping_rule":"Pto104_2" }, { "input_type":"MvTyp", "output_type":"M_ME_NA_1", "mapping_rule":"Pto104_3" },"TaggedReason": "String", "TmOrg": { "stVal": "genuine" }, "TmStamp": { "q": { "DetailQuality": { "badReference": true, "failure": true, "inconsistent": true, "innacurate": true, "oldData": true, "oscillatory": true, "outOfRange": true, "overflow": true }, "Source": "process", "Validity": "good", "operatorBlocked": true, "test": true }, "stVal": { "FractionOfSecond": 1, "SecondSinceEpoch": 1, "TimeQuality": { "clockFailure": true, "clockNotSynchronized": true, "leapSecondKnown": true, "timeAccuracy": 1 } }, "t": { "FractionOfSecond": 1, "SecondSinceEpoch": 1, "TimeQuality": { "clockFailure": true, "clockNotSynchronized": true, "leapSecondKnown": true, "timeAccuracy": 1 } } } } } } |
Protocol translation process
Drawio | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Exchanged data configuration
In this chapter we will describe the configuration of the exchanged data. This configuration allow to specify a list of supported data objects. The protocol plugin is expected to make some controls against each entry of the configuration to check:
- if protocol message address or reference is known otherwise throw an error message.
- if protocol type of message is known otherwise throw an error message.
- The label attribute shall be used to populate the Fledge's DataPoint Asset Name attribute.
Attributes definition
Attribute | Description | Expected values | Mandatory |
---|---|---|---|
name | this identifies the exchanged data configuration | Yes | |
version | this is the version number of the configuration | x.y where x represents a major version and y a minor change | Yes |
datapoints | array of datapoints that needs to be managed by the instance of the gateway | Yes | |
datapoints.label | label of the datapoint | any non empty string | Yes |
datapoints.pivot_id | unique identifier of the datapoint, this is used to create a pivot object | any non empty string | Yes |
datapoints.pivot_type | type of Common Data Class (CDC), this is used to create a pivot object | enum SpsTyp | DpsTyp | MvTyp | SpcTyp | DpcTyp | ... | Yes |
datapoints.pivot_subtypes | array of additional types of the pivot object | [transient, ...] | No |
datapoints.tfid | identifies the math function to transform the input value | enum "normal" | "square_root" | "quadratic" | "transparent" | No |
datapoints.params | array of parameters for the math function | array of float 32 [a, b, c, ...] | No |
datapoints.deadband | band of input values where the output is zero | array of 2 float 32 [min, max] | No |
datapoints.protocols | array of protocols that needs to be managed for a datapoint | Yes | |
datapoints.protocols.name | name of the protocol | enum "iec104" | "iec103" | "tase2" | "hnz" | "61850" | "opcua" | ... | Yes |
datapoints.protocols.address | address of the datapoint in the given protocol | any non empty string | Yes |
datapoints.protocols.typeid | type id of the datapoint in the given protocol | any non empty string representing a valid protocol type id | Yes |
datapoints.protocols.gi_groups | GI request status for north plugins, if "station" then datapoint is send for south plugins, it determines whether a datapoint is expected in the GI response | enum station | 1 | 2 | ... | No |
datapoints.protocols.alternate_mapping_rule | Alternate mapping rule to convert datapoint from protocol model to pivot or pivot to protocol model, if not specified then default conversion rule is applied | any non empty string representing a function name | No |
datapoints.operations | array of operations applied to produce a value for the current datapoint out of one or more input datapoints | No | |
datapoints.operations.operation | type of operation to perform | enum "or" | No |
datapoints.operations.input | array of Pivot ID of datapoints to use as inputs for the operation | array of Pivot ID strings | No |
Configuration JSON structure
Code Block | ||
---|---|---|
| ||
{ "exchanged_data":{ "name":"SAMPLE", "version":"1.0", "datapoints":[ { {"label":"TS1", "inputpivot_typeid":"MvTypID114562", "outputpivot_type":"M_ME_NC_1SpsTyp", "mappingpivot_rulesubtypes":"Pto104_4"[ }, "transient" { ], "operations":[ { "input_type":"SpsTyp", "output_typeoperation":"Data_StateQTimeTagExtendedor", "mapping_rule":"PtoT2_1" "input":[ "ID114562", "ID114563" ] } }, ], { "protocols":[ "input_type":"DpsTyp", { "output_type":"Data_DiscreteQTimeTagExtended", "mapping_rulename":"PtoT2_2iec104", }, { "address":"45-672", "input_type":"MvTyp", "output_typetypeid":"Data_RealQ",M_SP_TB_1", "mappinggi_rulegroups":"PtoT2_3station", } ] } } |
Exchanged data configuration
In this chapter we will describe the configuration of the exchanged data. This configuration allow to specify a list of supported data objects. The protocol plugin is expected to make some controls against each entry of the configuration to check:
- if CA of ASDU is known otherwise throw an error message.
- if IOA is known otherwise throw an error message.
- if type of ASDU is known otherwise an error message.
- The label attribute shall be used to populate the Fledge's DataPoint Asset Name attribute.
Attributes definition
...
Configuration JSON structure
Code Block | ||
---|---|---|
| ||
{ "exchanged_data":{ "name":"SAMPLE", "version":"1.0", "datapoints":[ "alternate_mapping_rule":"func_name_1" }, { "name":"tase2", "address":"S_114562", "typeid":"Data_StateQTimeTagExtended" }, { "name":"opcua", "address":"ID114562", "typeid":"opcua_sps" }, { "name":"iec61850", "address":"simpleIOGenericIO/GGIO1.Ind1", "typeid":"SPS" } ] }, { "label":"TS1TM1", "pivot_id":"ID114562ID99876", "pivot_type":"SpsTypMVTyp", "protocolstfid":["square_root", "params":[ { 2.0, "name":"iec104", 49.5 "address":"45-672", ], "typeid":"M_SP_TB_1",deadband":[ -0.02, "gi_groups":"station" 0.02 }, ], { "protocols":[ "name":"tase2",{ "addressname":"S_114562iec104", "typeidaddress":"Data_StateQTimeTagExtended45-984", "gi_groupstypeid":"stationM_ME_NA_1" }, ] { }, { "name":"tase2", "label":"TM1", "pivot_idaddress":"ID99876S_114562", "pivot_typetypeid":"DpsTyp",Data_RealQ" "protocols":[}, { "name":"iec104opcua", "address":"45-984ID99876", "typeid":"M_ME_NA_1opcua_mvf" }, { "name":"tase2iec61850", "address":"S_114562simpleIOGenericIO/GGIO1.AnIn1", "typeid":"Data_RealQMV" } ] } ] } } |
Warning |
---|
Do not use the name "IEC104Command" as a datapoint name in the exchanged data configuration. Doing so could potentially lead to conflicts when trying to read readings from both the South and Dispatcher components. |