TASE.2/ICCP Library Developer Guide: libtase2 Protocol Library Version 2.4

There are a few places were the API changed and you have to change your code accordingly.

When you migrate from an older version (prior to version 2.2) it is important to know that the application layer addresses (like AP-title, AE-qualifiers) are checked more rigidly. That means a setup that formerly worked because libtase2 didn’t check all the addressing details might no longer work because libtase2 now checks both the calling and called addresses. This was required when allowing multiple servers on a passive endpoint as the called address is required to identify the correct server instance.

The following code example shows how to create a dual-role passive endpoint. First the Tase2_Endpoint instance will be created and a local application reference will be assigned with the function Tase2_Endpoint_setLocalApTitle.

Then a server is created with the Tase2_Server_createEx function that accepts an Tase2_Endpoint as argument. This function automatically associates the new server instance with the endpoint instance.

After that a client is created with the Tase2_Client_createEx function that also automatically assigns the new client to the endpoint. A remote application reference is assigned to the client with the Tase2_Client_setRemoteApTitle function. Here this means that whenever a remote TASE.2 endpoint connects to the local endpoint it will be connected to this client instance when the remote application reference (or depending on the configuration other addressing parameters) matches with the configured ones of the client.

When using multiple servers with the same passive endpoint every server has to have its own local application addresses. These can be set using the Tase2_Server_setLocalAddresses function. When this function is not used then the default local address of the server is the address set for the endpoint with Tase2_Endpoint_setLocalApTitle.

It is also possible to remove a client or server during runtime from an endpoint instance using the Tase2_Endpoint_removeServer or Tase2_Endpoint_removeClient functions.

After removing the client or server instances can be released with the Tase2_Server_destroy or Tase2_Client_destroy functions.

It is also possible to move a server instance from one passive endpoint to another passive endpoint:

Next to the TCP/IP layer addresses (IP address and TCP port) there are specific address parameters used by TASE.2/MMS for the upper protocol layer. Actually each protocol layer has its own address.

Usually the AP-title and AE-qualifier are important. They are used by default by the protocol stack to associate clients with servers. Also they are used to associate bilateral tables to connected clients which is important to implement the access control properly.

The AP-title is an ITU object identifier (OID). It consists of a sequence of numbers separated by dots. The AE-qualifier is a single integer value. You can set these parameters by the setLocalApTitle and setRemoteApTitle functions of Tase2_Endpoint, Tase2_Server, and Tase2_Client.

The lower layer parameters (P, S, T selectors) are usually preset by some common default values and are usually not checked by the library in order to avoid interoperability problems. Yet in some cases (depending on the implementation of the peer device) it might be required to ensure that specific parameters are used.

E.g. you can set the local lower layer parameters by the Tase2_Endpoint_setLocalAddresses function.

You can also change the parameters that are used for address matching (associating connection with client and server instances) by using the Tase2_Endpoint_setAddressMatchingRules function.

This step is optional and only required for secure (encrypted and/or authenticated) communication.

The TLS configuration represented by a TLSConfiguration object. A new TLS configuration can be created with the TLSConfiguration_create function:

Some validation parameters can be enabled or disabled. In the following example all certificates are accepted that can be validated by one of the installed CA certificates:

The following function calls are required to load the private key, server certificate, and at least one CA certificate for chain validation:

Starting from version 2.4.0 the TLSConfiguration can be updated for a running endpoint. The update requires to create a new TLSConfiguration instance.

The TLSConfiguration and ALSConfiguration instances now have a reference counter and exist as long as an owner exists (e.g. a running TLS connection). You can freely call TLSConfiguration_destroy in your application when you no longer need it.

Starting from version 2.4.0 Application Layer Security (ALS) is supported according to IEC 62351-3:2007 is supported by the library.

ALS provides application layer authentication during the MMS handshake. Is can only be used for authentication and doesn’t provide encryption. If encryption is required ALS should be combined with TLS.

Similar to TLS the application layer security uses X509 certificates to authenticate peers.

It is possible (and recommended) to combine ALS with TLS.

ALS can be configured at the Endpoint level.

The ALS configuration can be created and used with an Endpoint as in the below code:

Related types are ASecurityConfiguration, Crypto_X509Certificate, Cryptp_PrivateKey.

The Crypte_X509Certificate type can also be used to analyse received certificates in the ConnectionAcceptHandler.

The Tase2_Endpoint is started by calling the Tase2_Endpoint_connect function. In case of an active endpoint this will cause the protocol stack to open a TCP connection to a remote TCP server. In case of a passive endpoint this will cause the protocol stack to listen for incoming TCP connections on a local TCP port.

The Tase2_Endpoint_connect function is an asynchronous function. It will invoke the connection process and then will return. After calling the function you can check the current endpoint state by the Tase2_Endpoint_getState function. This will return the current state.

E.g. example in case of an passive endpoint the state will be TASE2_ENDPOINT_STATE_LISTENING when the endpoint is listening for incoming client connections. If there had been a problem the state will be TASE2_ENDPOINT_STATE_ERROR.

In case of an active endpoint the state after calling the Tase2_Endpoint_connect function can either be TASE2_ENDPOINT_STATE_CONNECTING, TASE2_ENDPOINT_STATE_CONNECTED, or TASE2_ENDPOINT_STATE_ERROR.

To simplify programming you can used the Tase2_Endpoint_waitForState. This function will block until a specified state is reached or a time out occured. It will return true if the expected state has been reached or false in case of a time out or error.

The endpoint connections can be closed (and listening to new connection be stopped) with the Tase2_Endpoint_disconnect function.

The server data model is represented by an instance of Tase2_DataModel. The data model consists of domains, indication points, protection equipment data points, devices (control points), data sets, and transfer sets. The data model object can be created by the Tase2_DataModel_create function:

In TASE.2 variables are named objects that are part of the address space of the server. Variables can be system variables (like "Bilateral_Table_ID", "Supported_Features", …​), indication points, protections equipment, and devices.

Variables can have two "scopes". The VCC scope or domain specific (ICC) scope. Variables of VCC scope are not part of any TASE.2 domain and are visible to all clients.

Variables of VCC scope are identified by the variable name only. Variables of domain scope are identified by the domain name and the variable name.

A TASE.2 domain is represented by a Tase2_Domain object. The domain object can hold all kind of data points, data sets, and transfer sets. To create a new domain with a specific domain name the Tase2_DataModel_addDomain function has to be used:

The new domain will be added to the data model. The return value is a reference to the newly created domain. It should be stored for further usage.

Despite of the fact that VCC specific variables are not part of a domain, for implementation purposes they are associated with a specific Tase2_Domain instance. This instance is part of the Tase2_DataModel object by default and can be accessed by the Tase2_DataModel_getVCC function.

This function returns a Tase2_Domain instance that represents the VCC.

Now data points can be added to the domains and the VCC "domain" with the Tase2_Domain_addIndicationPoint, Tase2_Domain_addControlPoint, and Tase2_Domain_addProtectionEquipment functions.

The concept of information messages consists of the information message (IM) transfer set and information message buffers.

The information message transfer set is an association specific mechanism that (when enabled by the client) sends information messages from the server to the client. The message transmission is triggered by the server. Information messages can be VCC or ICC specific.

Information messages can contain textual messages or arbitrary binary data. The length of information messages is limited by the available information buffers and the maximum MMS PDU size.

To use information messages in a server application first the information buffers have to be created (when creating the server data model).

The information messages will only be sent to a client when the bilateral table allows it. With the bilateral table the information messages are restricted by their parameters information refererence, local reference, and scope (ICC or VCC).

After starting the server information messages can be sent with the Tase2_Server_sendInformationMessage function.

The bilateral table (BLT) consists of the following elements:

The bilateral tables form an important part of the access control mechanism. If no BLTs are defined, the access control decisions are solely based on the access rights defined for the data point. These access rights are the same for all clients. If bilateral tables are defined the access control decisions are based on both, the access rights defined for the data point and those defined in the bilateral table for the requesting client. If a data point is not part of the bilateral table for the requesting client, the request will be denied and an "object-access-denied" response will be sent to the client. If a data point is specified in the BLT for a client, then the access will only be allowed if it is allowed in the access control specification of the data point and the access control specification in the BLT.

A server will be represented by a Tase2_Server instance. First the server instance has to be created with the Tase2_Server_create function. The first argument is the data model that has to be created before. The second argument is the TLSConfiguration instance or NULL for insecure connections.

In order to apply different access control restrictions for different clients the bilateral tables have to be registered at the server:

Also the callback handlers can be installed here when required. The following example shows how the handler for write accesses can be registered. All handler registration functions have a third argument that can be used to pass an arbitrary pointer to the callback function. If not required this argument can be set to NULL.

The server can be started with the Tase2_Server_start function:

Once running the server can call the application by using callback functions.

In case you have configured the Tase2_Endpoint manually you should use the Tase2_Endpoint_connect function. This automatically starts all associated client and server instances:

To update the values the data point manipulations functions should be used:

1.) The value has to be updated

2.) Then the server has to be informed that the value changed:

This section describes how the server handles events. Depending on the kind of callback handlers installed the server will involve the application to handle the request or will handle the request autonomously.

Read requests from clients are handled automatically by the protocol stack. If the server accepts read requests depends on the type of information requested and the access rights that are defined in the bilateral table (BLT).

Write requests will can be handled automatically. In any case the server accepts only write requests that are permitted by the bilateral table. Additionally the user can provide the Tase2_WriteDataHandler that is invoked after the BLT rules are checked and allow write access.

There are also special write requests for devices that are handled by specialized callback handlers (Tase2_SelectHandler, Tase2_OperateHandler, Tase2_SetTagHandler).

The following callback functions are supported:

Devices (control points) can have a tag attribute. This attribute is optional. Tags indicate that the device (or parts of the device functionality) cannot be used temporarily. One reason can be ongoing maintenance work on associated equipment.

A tag has a value which is one of:

Additionally to the value a tag can also have a text string that can indicate a human readable reason for the tag. E.g. "maintenance work".

Tags can be set locally by using the Tase2_ControlPoint_setTag function or remotly by writing a tag value to the ControlPoint_TAG variable by the MMS protocol. Depending on the access control specfications remote access to the tag can be denied.

In order to setup a client the following steps are required:

Depending on the configuration this step has to be done using the Tase2_Endpoint_connect function. When not using the Tase2_Endpoint you have to use the Tase2_Client_connect function to start a TCP client connection to the server.

The Tase2_Client_connect function waits until the connection is established or an error occured during connection establishment.

You can the the success by evaluating the err return value of the function.

When the client is used on a passive Tase2_Endpoint instance (TCP server) it can also be useful to call Tase2_Client_connect when a connection from the active server has been established. Otherwise the client instance will not request information about the TASE.2 version used by the server. In this case the Tase2_Client_connect function can be called with the hostname and apTitle parameters set to NULL or Tase2_Client_connectEx can be used.

TASE.2 uses the identity service to provide some basic information about the device. The identity consists of the vendor, model, and revision of the device.

The identity service is also often used to implement an application level heartbeat in the case no application data is sent.

The following code shows how to read the identity from the server:

To read a data set from the server you first have to use the Tase2_Client_getDataSet function. The function returns an object of type Tase2_ClientDataSet. This is a handle to access the data set data. Tase2_Client_getDataSet itself does not read the data set from the server. Instead it reads the data set directory from the server and creates and initializes the Tase2_ClientDataSet instance with the information received from the server.

The actual step to read the data set from the server is done by calling the Tase2_ClientDataSet_read function.

You can access the names and values of the data set elements with the Tase2_ClientDataSet_getPointName and Tase2_ClientDataSet_getPointValue functions. The function Tase2_ClientDataSet_getSize provides the number of data set elements.

The following code shows how to access the data set elements:

The type Tase2_PointName is a pointer to a structure that contains the domain and the variable name of the data point. It is also possible to get these two strings separate by using the Tase2_ClientDataSet_getPointVariableName and Tase2_ClientDataSet_getPointDomainName functions.

There are also a function Tase2_ClientDataSet_isDeletable that returns the information if the data set can be deleted by the client (when it is a dynamic data set).

Dynamic data sets can be used by the client to create data sets that contain all information required by the application and do not have to rely that this information is contained in preconfigured data sets.

A dynamic data set can be created by the Tase2_Client_createDataSet function.

To specify the data set a LinkedList object with the data set name strings as elements has to be created first and passed to the function:

The following code shows how to create a dynamic data set:

It is recommended not to create large data sets. This can have a negative impact on performance. Also when the data set it too big there is the risk that the data doesn’t fit into a single MMS PDU and then cannot be set. Instead use the multipe data sets/DS transfer sets to transport large amounts of data.

Finally you can delete a data set with the Tase2_Client_deleteDataSet function. E.g.:

Data set transfer sets (DSTS) are the most important and most efficient mechanism to transport data from the server to the client. They can be used to send data from the server to the client without the client sending requests.

To start using a DSTS you have to call the Tase2_Client_getNextDSTransferSet with the correct domain name that is assigned to your client by the BLT. This function returns an object of type Tase2_ClientDSTransferSet that is the representation of the allocated transfer set. The transfer set can then be configured by writing to the configuration properties of the transfer set.

First you have to configure the data set for the transfer set (e.g. with the Tase2_ClientDSTransferSet_writeDataSetName function). Then also other important parameters can be configured.

There are the three important basic reporting options:

These basic mechanisms can be combined with other options:

The following parameters can be used to configure the basic reporting options:

For the option IntervalTimeout there exist the following cases:

For ObjectChange the following cases exist:

The IntegrityTimeout can be used additionally to send the whole dataset periodically when RBE = true. Otherwise the IntervalTimeout can be used to send the whole dataset periodically.

DSTS reports are handled by two different callback types. The first callback (Tase2_DSTransferSetReportHandler) is called twice for each report that is received. First when the report was received and the second invocation happens after the last value from the report has been passed to the user. The second callback Tase2_DSTransferSetValueHandler is called for each single value that is part of the report.

Information message (IM) transfer sets are used to send text or binary messages to one or more client. A client can subscribe to the information messages from a server by using the Tase2_Client_IMTransferSetEnable function. The server will then send all information messages to the client that are specified in the corresponding bilateral table (BLT).

The information messages are handled by a callback function.