HNZ south plugin

HNZ 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

Configuration JSON structure

{
   "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
            }
         ]
      },
      "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,
         "bulle_time": 10
      },
      "south_monitoring":{
         "asset":"CONNECTION-1"
      }
   }
}

HNZ datapoint representation

This is the Datapoint representation of an HNZ message.

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

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.

Connection status audits

This plugin will send Fledge audits of type SRVFL containing different messages to notify about changes in the status of the connection.

The connection status will be tracked at two different levels:

• Path level: An HNZ connection has a maximum of two path defined (A and B), one of them is active, the other is passive.
• Global level: The same level as in south_events representing the global state of the connection.

Generated audit messages will have the following pattern based on their level:

• Path level: <service_name>-<path_letter>-<status>
• Global level : <service_name>-<status>

With:

• <service_name>: The name of the service running this plugin (eg: hnzsouth_s1)
• <path_letter>: The letter of the path (A or B).
• <status>: The connection status.

The connection status can take different values based on the level of connection, each value is sent with a given audit severity :

• Path level:

• Global level:

These audits are sent :

• Whenever the plugin is reconfigured (including at plugin startup)
• Whenever the connection state they represent changes

Some audits may be repeated in the same state (in case of reconfiguration or plugin restart for example) but the implementation is designed to minimize the number of audits sent while ensuring that no state change can be missed.