Page History

HNZ

...

The HNZ protocol stack configuration specifies communication parameters and is a collection of entries containing information about OSI Transport and OSI Application layers objects.

Each entry is comprised of attributes that describe the object. All the configuration data are structured using JSON.

Each entry shall be mapped with the corresponding configuration function in the chosen implementation protocol library.

Attributes definition

connexion initialization

When the HNZ south plugin establishes a new connection with a HNZ device, it will automatically send the following messages to the device:

A set date and a set time: Those two messages will synchronize the date and time of the device with the one from the south plugin machine.
A CG request: This message will request all TS to be sent by the device in CG format (equivalent of GI request of iec104).

HNZ Protocol stack configuration

The HNZ protocol stack configuration specifies communication parameters and is a collection of entries containing information about OSI Transport and OSI Application layers objects.

Each entry is comprised of attributes that describe the object. All the configuration data are structured using JSON.

Each entry shall be mapped with the corresponding configuration function in the chosen implementation protocol library.

The present specification corresponds to the HNZ B1/TR mode working on a TCP/IP connection.

Attributes definition

Attribute	Description	Expected values	Mandatory
name	this identifies the protocol stack	iec104client, iec104server, tase2client, tase2server, 61850client, 61850server, etc...	Yes
version	version number of the configuration file	2 digits x.y => x = major change, y = minor change	Yes
connections	array of connections		Yes
connections.srv_ip	IP address to remote HNZ server	IP address	Yes
connections.port	port number to remote HNZ server	default = 6001	No
remote_station_addr	remote server station address	6 bits	Yes
Inacc_timeout	timeout before declaring the remote server unreachable (DF.GLOB.TS)	default = 180 (seconds)	No
max_sarm	max number of SARM messages before handing over to the passive path (A/B)	default = 30	No
repeat_path_A	max number of authorized repeats for path A	default = 3	No
repeat_path_B	max number of authorized repeats for path B	default = 3	No
repeat_timeout	time allowed for the receiver to acknowledge a frame, after this time, the sender repeats the frame.	default = 3000	No
anticipation_ratio	number of frames allowed to be received without acknowledgement	default = 3	No
test_msg_send	test message code in sending direction	default = 1304	No
test_msg_receive	test message code in receiving direction	default = 1304	No
gi_schedule	scheduled time for General Interrogation sending	default = 99:99 (disabled)	No
gi_repeat_count	repeat GI for this number of times in case it is incomplete	default = 3

AttributeDescriptionExpected valuesMandatorynamethis identifies the protocol stackiec104client, iec104server, tase2client, tase2server, 61850client, 61850server, etc...Yesversionversion number of the configuration file2 digits x.y => x = major change, y = minor changeYesredundancy_groupsarray of redundancy groupsYesredundancy_groups.connectionsarray of connections of a given redundancy groupYesredundancy_groups.connections.srv_ipIP address to remote IEC 104 serverIP addressYesredundancy_groups.connections.portport number to remote IEC 104 serverdefault = 2404Noredundancy_groups.connections.connestablish connection at startupTRUE, FALSE, default = TRUENoredundancy_groups.connections.startstart data transfer at startupTRUE, FALSE, default = TRUENoredundancy_groups.k_valueMaximum number of outstanding (unacknowledged) APDU's at a given timedefault = 12Noredundancy_groups.w_valueAcknowledge the reception latest after this number of APDU'sdefault = 8Noredundancy_groups.t0_timeouttime out of connection establishmentdefault = 10Noredundancy_groups.t1_timeouttime out for send or test APDU'sdefault = 15Noredundancy_groups.t2_timeouttime out for acknowledges in case of no data messages (t2 < t1)default = 10Noredundancy_groups.t3_timeouttime out for sending test framesdefault = 20Noredundancy_groups.rg_namethis identifies the redundancy groupYesredundancy_groups.tlsactivation of TLS (see tls configuration chapter for details)TRUE, FALSE, default = FALSENoorig_addrOriginator Addressdefault = 0Noca_asdu_sizesize of "Common Address of ASDU"default = 2 (byte)Noioaddr_sizesize of 'Information Object Address'default = 3 (byte)Nostartup_timetime to wait for startup completiondefault = 180 (seconds)Noasdu_size

maximum ASDU size in transmission direction, if set to "0" => maximum possible value is automatically used.

default = 0 (byte)

	No
gi_time	time to wait for General Interrogation (GI) completion	default =

0

255 (seconds)

No

gi

c_ack_

cycle

time	time to wait before receving a acknowledgement for a control command

send General Interrogation (GI) cyclically for the specified period of time

default =

0

10 (seconds)

, if 0 => DEACTIVATED

No

gi

cmd_

all

recv_

casend a separate GI request to every CA; otherwise a broadcast GI request is usedTRUE, FALSE, default = FALSENogi_repeat_countrepeat GI for this number of times in case it is incompletedefault = 2Nodisc_qualinformation object quality in case of interrupted connectionIV = Invalid, NT = Not Topical, default = NTNosend_iv_timetime delay before infos are sent as invalid (0 = deactivated)default = 0Notsivspecifies what to do with a time stamp marked as 'invalid'

remove, process, default = remove

remove: the time stamp will be removed from the information object

process: the time stamp will be processed on regular basis and additionally marked as 'not synchronized'

Noutc_timeUTC timezone (=TRUE) or local timezone (=FALSE) for time conversionTRUE, FALSE, default = FALSENocomm_wttaguse commands with time tag (=TRUE) or without time tag (=FALSE)TRUE, FALSE, default = FALSENocomm_parallelmaximum number of commands to be executed at in parallel (0 = unlimited)default = 0Noexec_cycl_testexecute cyclical test requests (C_TS_NA_1/C_TS_TA_1) in monitoring direction (=TRUE) or not (=FALSE)TRUE, FALSE, default = FALSENostartup_statestartup in active mode (=TRUE) or in passive mode (=FALSE)TRUE, FALSE, default = TRUENoreverseallow transmission of information objects in reverse direction (=TRUE) or only in standard direction (=FALSE)TRUE, FALSE, default = FALSENotime_syncperform time synchronization (=TRUE)default = 0 (seconds), if 0 => DEACTIVATEDNo

Configuration JSON structure

timeout	time to wait for bytes when receiving data from the HNZ device	default = 100000 (microseconds)	No
south_monitoring.asset	asset name used to send the connection and gi status information to the north	default = "CONNECTION-1"	No

Configuration JSON structure

Code Block

language	py

{
   "protocol_stack":{
      "name":"hnzclient",
      "version":"1.0",
      "transport_layer":{
         "connections":[
            {
               "srv_ip":"192.168.0.10",
               "port":6001
            },
            {
               "srv_ip":"192.168.0.11",
               "port":6002
            }
         ]
      }

Code Block

language	js

{
   "protocol_stack":{
      "name":"iec104client",
      "version":"1.0",
      "transportapplication_layer":{
         "redundancyremote_station_groupsaddr":[12,
         "inacc_timeout":180,
   {
      "max_sarm":30,
         "connectionsrepeat_path_A":[3,
         "repeat_path_B":3,
         {
"repeat_timeout":3000,
            "anticipation_ratio":3,
          "srvtest_msg_ipsend":"192.168.0.101304",
         "test_msg_receive":"1304",
            "port":2404"gi_schedule":"99:99",
            "gi_repeat_count":3,
         "conngi_time":true255,
            "c_ack_time":10,
         "startcmd_recv_timeout":true100000
      },
      "south_monitoring":{
      },
      "asset":"CONNECTION-1"
      }
      {
                     "srv_ip":"192.168.0.11",
                     "port":2404,
                     "conn":true,
                     "start":false
                  }
               ],
               "rg_name":"red-group-1",
               "tls":false,
               "k_value":12,
               "w_value":8,
               "t0_timeout":10,
               "t1_timeout":15,
               "t2_timeout":10,
               "t3_timeout":20
            }  }
}

HNZ datapoint representation

This is the Datapoint representation of an HNZ message.

Attribute	Description	Expected values	Mandatory
do_type	message type	TS, TM, TC, TVC	YES
do_station	station address		YES
do_address	message address		YES
do_value	value	TM (do_an = TMA): [-127..127] TM (do_an = TM8): [0..255] TM (do_an = TM16): [-32768..32767] TS: [0..1] TC: [1..2] (01b = on, 10b = off) TVC: [-255..255]	YES except in quality update readings
do_valid	validity	valid = 0 or invalid = 1	YES
do_an	TM type (analogic / numeric)	"TMA", "TM8", "TM16"	TM only
do_cg	TS source	CG = 1 or CE = 0	TS only
do_outdated	Outdated message (after connection loss)	up to date =0, outdated = 1	TM and TS only
do_ts	timestamp	epoch timestamp in milliseconds	TS CE only
do_ts_iv	timestamp invalid	valid = 0 or invalid = 1 (from bit HNV)	TS CE only
do_ts_c	loss of chronology	lost = 1 else = 0 (from bit CV)	TS CE only
do_ts_s	ts not synchronized	synchronized = 0 else = 1 (from bit S)	TS CE only

Example for a TS from CE:

Code Block

language	py

{
    "data_object":{
        "do_type":"TS",
            {
       "do_station":12,
        "connectionsdo_addr":[325,
          "do_value":1,
        {"do_valid":0,
        "do_cg":0,
        "do_outdated":0, 
        "srvdo_ipts":"192.168.0.12"1685019425432,
             "do_ts_iv":0,
        "portdo_ts_c":24040,
        "do_ts_s":0
    }
 }

Example for a TS from CG:

Code Block

language	py

{
         "conndata_object":false,
    {
        "do_type":"TS",
         "startdo_station":false12,
        "do_addr":325,
          }"do_value":1,
        "do_valid":0,
        "do_cg":1,
   {
     "do_outdated":0
    }
 }

Example for a TS quality update:

Code Block

language	py

{
    "data_object":{
         "srvdo_iptype":"192.168.0.13TS",

        "do_station":12,
        "do_addr":325,
        "portdo_valid":24040,
        "do_cg":0,
        "do_outdated":1, 
        "conndo_ts":false1685019425432,
            "do_ts_iv":0,
         "startdo_ts_c":false0,
        "do_ts_s":0
    }
 }

Example for a TMA:

Code Block

language	py

{
     }"data_object":{
        "do_type":"TM",
          ]"do_station":12,
          "do_addr":71,
        "rgdo_namevalue":"red-group-2",
       -15,
        "tlsdo_valid":false0,
           "do_an":"TMA",
         "kdo_valueoutdated":12,0
    }
}

Example for a TMN 8 bits (TM8):

Code Block

language	py

{
     "data_object":{
        "wdo_valuetype":8"TM",
        "do_station":12,
             "t0do_timeoutaddr":1071,
               "t1do_timeoutvalue":1542,
        "do_valid":0,
           "t2do_timeoutan":10"TM8",
        "do_outdated":0
     }
}

Example for a TMN 16 bits (TM16):

Code Block

language	py

{
     "t3data_timeoutobject":20{
        "do_type":"TM",
        }"do_station":12,
        "do_addr":71,
    ]
    "do_value":420,
  },
      "applicationdo_layervalid":{0,
            "orig_addr":0,
  "do_an":"TM16",
        "cado_asdu_sizeoutdated":2,0
    }
}

Example for a TM quality update:

Code Block

language	py

{
        "ioaddrdata_sizeobject":3,{
         "startupdo_timetype":180,
         "asdu_size":0"TM",
            "gido_timestation":6012,
            "gido_cycleaddr":false71,
         "gido_all_cavalid":false0,
            "gi_repeat_count":2 "do_an":"TMA",
         "discdo_outdated":1
    }
}

Example for a TC (after receiving ACK):

Code Block

language	py

{
qual":"NT",
         "senddata_iv_timeobject":0,{
         "tsivdo_type":"REMOVETC",
            "utc_time":false,
         "comm_wttag":falsedo_station":12,
            "commdo_paralleladdr":071,
         "execdo_cycl_testvalid":false,0
         "startup_state":true,
  }
 }

Example for a TVC (after receiving ACK):

Code Block

language	py

{
       "reversedata_object":false,{
         "timedo_sync":false
      }
   }
}

HNZ datapoint representation

This is the Datapoint representation of an HNZ message.

Code Block

language	js

{
    "data_object":{
       "do_type":"M_SP_TB_1"type":"TVC",
        "do_station":12,
        "do_addr":31,
        "do_cavalid":18325,0
         "do_oa":0,
       "do_cot":3,
       "do_test":false,
       "do_negative":false,
       "do_ioa":6468178,
       "do_value":1,
       "do_quality_iv":true,
       "do_quality_bl":false,
       "do_quality_ov":false,
       "do_quality_sb":false,
       "do_quality_nt":false,
       "do_ts":1653484330239,
       "do_ts_iv":true,
       "do_ts_su":false,
       "do_ts_sub":false
    }
 }

Path exploration

...

}
 }

NB: if an attribute is not required, then it is not put in the output data object, which means that the output object structure always fits the protocol model object type.

HNZ command representation

This is the command representation of an HNZ message.

Warning
The current implementation does not use a json structure, so the order of parameters is mandatory.

Order	Attribute	Description	Expected values	Mandatory
0	co_type	message type	TC, TVC	YES
1	co_addr	message address	[0..255][0..7] (ADO + ADB) for a TC, [0..31] for a TVC	YES
2	co_value	value	[1..2] (01b = on, 10b = off)	YES

The processing of FLEDGE commands should evolve. Below is an example of JSON format :

Example for a TC:

Code Block

language	py

{
    "co_type":"TC",
    "co_addr":325,
    "co_value":1
}

Example for a TVC:

Code Block

language	py

{
    "co_type":"TVC",
    "co_addr":31,
    "co_value":42
}

NB: if an attribute is not required, then it is not put in the output data object, which means that the output object structure always fits the protocol model object type.

HNZ south event representation

South events are special messages used to communicate information about the state of the connection and GI requests between south and north plugins.

Their behivior and structure is defined here.

Path exploration

...

In redundant network configuration or generally in cases where several communication paths exist between one client and one server, the path checking exploration mechanism allows the client to try all the paths one by one without making any difference between them. The client uses the first available path. On disconnection this procedure starts again from the beginning.

Page tree

Versions Compared

Old Version 1

New Version Current

Key

HNZ

Attributes definition

connexion initialization

HNZ Protocol stack configuration

Attributes definition

Configuration JSON structure

Configuration JSON structure

HNZ datapoint representation

HNZ datapoint representation

Path exploration

HNZ command representation

HNZ south event representation

Path exploration