HNZ north plugin

HNZ connection initialization

The HNZ north plugin binds its local ip address and two ports originating from the configuration so as to serve path_A and path_B

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	hnzserver	Yes
version	version number of the configuration file	2 digits x.y => x = major change, y = minor change	Yes
transport_layer. port_path_A	port number to listen for the path A	default = 6001	Yes
transport_layer. port_path_B	port number to listen for the path B	default = 6002	Yes

Configuration JSON structure

{
   "protocol_stack":{
      "name":"hnzserver",
      "version":"1.0",
      "transport_layer":{
          "port_path_A":6001
          "port_path_B":6002
      },
      "application_layer":{
         "remote_station_addr":12,
         "inacc_timeout":180,
         "max_sarm":30,
         "repeat_path_A":3,
         "repeat_path_B":3,
         "repeat_timeout":3000,
         "anticipation_ratio":3,
         "test_msg_send":"1304",
         "test_msg_receive":"1304",
         "gi_schedule":"99:99",
         "gi_repeat_count":3,
         "gi_time":255,
         "c_ack_time":10,
         "cmd_recv_timeout":100000
      }
   }
}

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_addr	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:

{
    "data_object":{
        "do_type":"TS",
        "do_station":12,
        "do_addr":325,
        "do_value":1,
        "do_valid":0,
        "do_cg":0,
        "do_outdated":0, 
        "do_ts":1685019425432,
        "do_ts_iv":0,
        "do_ts_c":0,
        "do_ts_s":0
    }
 }

Example for a TS from CG:

{
    "data_object":{
        "do_type":"TS",
        "do_station":12,
        "do_addr":325,
        "do_value":1,
        "do_valid":0,
        "do_cg":1,
        "do_outdated":0
    }
 }

Example for a TS quality update:

{
    "data_object":{
        "do_type":"TS",
        "do_station":12,
        "do_addr":325,
        "do_valid":0,
        "do_cg":0,
        "do_outdated":1, 
        "do_ts":1685019425432,
        "do_ts_iv":0,
        "do_ts_c":0,
        "do_ts_s":0
    }
 }

Example for a TMA:

{
    "data_object":{
        "do_type":"TM",
        "do_station":12,
        "do_addr":71,
        "do_value":-15,
        "do_valid":0,
        "do_an":"TMA",
        "do_outdated":0
    }
}

Example for a TMN 8 bits (TM8):

{
    "data_object":{
        "do_type":"TM",
        "do_station":12,
        "do_addr":71,
        "do_value":42,
        "do_valid":0,
        "do_an":"TM8",
        "do_outdated":0
    }
}

Example for a TMN 16 bits (TM16):

{
    "data_object":{
        "do_type":"TM",
        "do_station":12,
        "do_addr":71,
        "do_value":420,
        "do_valid":0,
        "do_an":"TM16",
        "do_outdated":0
    }
}

Example for a TM quality update:

{
    "data_object":{
        "do_type":"TM",
        "do_station":12,
        "do_addr":71,
        "do_valid":0,
        "do_an":"TMA",
        "do_outdated":1
    }
}

Example for a TC (after receiving ACK):

{
    "data_object":{
        "do_type":"TC",
        "do_station":12,
        "do_addr":71,
        "do_valid":0
     }
 }

Example for a TVC (after receiving ACK):

{
    "data_object":{
        "do_type":"TVC",
        "do_station":12,
        "do_addr":31,
        "do_valid":0
     }
 }

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.

The current implementation does not use a json structure, so the order of parameters is 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:

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

Example for a TVC:

{
    "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.