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

AttributeDescriptionExpected valuesMandatory
namethis identifies the protocol stack
hnzserver
Yes
versionversion number of the configuration file2 digits x.y => x = major change, y = minor changeYes
transport_layer.
port_path_A

port number to listen for the path A

default = 6001Yes
transport_layer.
port_path_B

port number to listen for the path B

default = 6002Yes

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.

AttributeDescriptionExpected valuesMandatory
do_typemessage typeTS, TM, TC, TVCYES
do_stationstation address
YES
do_addrmessage address
YES
do_valuevalue

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_validvalidityvalid = 0 or invalid = 1YES
do_anTM type (analogic / numeric)"TMA", "TM8", "TM16"TM only
do_cgTS sourceCG = 1 or CE = 0TS only
do_outdatedOutdated message (after connection loss)up to date =0, outdated = 1TM and TS only
do_tstimestampepoch timestamp in millisecondsTS CE only
do_ts_ivtimestamp invalidvalid = 0 or invalid = 1 (from bit HNV)TS CE only
do_ts_closs of chronologylost = 1 else = 0 (from bit CV)TS CE only
do_ts_sts not synchronizedsynchronized = 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.

0co_typemessage typeTC, TVCYES
1co_addrmessage address

[0..255][0..7] (ADO + ADB) for a TC, [0..31] for a TVC

YES
2co_valuevalue[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.