7.1 Introduction to KIS.API

KIS.API is defined as a particular instance of REST API [1,2,3], which is designed for the purpose of unified and convenient communication with KIS.Devices and the associated environment operating within KIS.MANAGER.

The crucial components of KIS.API are the resources, which can be defined in a very broad sense. In fact, anything having a name can be perceived as a resource, e.g., a user, a workspace, an asset, etc. The crucial information associated with a resource pertains to the service being realized, i.e., the transfer of data as well as the associated actions. A general structure of the resource is given in Table 7.1 [1].

Let us start with the . As an example, one can consider a KIS.Device, which can characterized by, e.g.,

  • an ID,

  • a name,

  • a URN,

  • associated asset group (workspace) IDs,

while its possible representation can be given in an intuitive JSON [1] form:

figure a

Now let us proceed to the resource identifier, which provides a unique way to identify the resource at any time instance. In other words, it should provide a full and unique path to the resource. Since the REST structure is based on HTTP, a sample path can look as follows:

figure b

which uniquely identifies a given KIS.Device using its URN. Having a resource identifier, one can proceed to realize some actions with it. A general set of verbs, which defines specific actions, is given in Table 7.2. Finally, an important standard that is inherited by REST from HTTP pertains to the status code. The most common status codes are given in Table 7.3. Under the above preliminary information, one can proceed to the registration and authorization of a new KIS.API user using KIS.MANGER.

Table 7.1 A typical structure of a resource
Full size table
Table 7.2 KIS.API actions
Full size table
Table 7.3 KIS.API response
Full size table

7.1.1 User Registration and Authorization

The primary objective of this part is to define a new KIS.API user along with an appropriate credentials. The process starts with selecting the Main menu \(\rightarrow \) Portal admin and then pressing the KIS.API icon . Subsequently, a new KIS.API user can be created with . The process is fully automatic and the only information required is to provide a user description, i.e., a name. A sample KIS.API credentials generation process is presented in Fig. 7.1. As a sample, a KIS.API access control triplex is obtained, which can be summarized as follows:

  • the client ID,

  • the API key,

  • the baseUrl.

Note that baseUrl is simply the base resource identifier detailed in the preceding section, i.e.,

figure e

The objective of the subsequent sections is to provide a concise introduction to KIS.API. Thus, to simplify this process, the Postman (https://www.postman.com/) application is employed. It is a dedicated platform for building and using APIs. In other words, Postman can be perceived as an HTTP client for testing web services, which makes it easy to test APIs by providing a simple interface for issuing API requests and viewing responses. The Postman registration and configuration process is very intuitive, and hence it is omitted. The subsequent step is to proceed to the KIS.API documentation (https://docs.kisme.com) and then select Run are Postman button. As a result, KIS.API collection is loaded into the Postman workspace. The final step is to provide the above defined KIS.API credentials using . This process is illustrated in Fig. 7.2. As of that moment, all KIS.API commands can be accessed and tested using the intuitive Postman graphical user interface. This process boils down to selecting an appropriate option and then sending a desired request to KIS.API. Thus, the objective is to provide a concise review of all available KIS.API functionalities.

Fig. 7.1
figure 1

Defining KIS.API credentials

Full size image
Fig. 7.2
figure 2

Postman configuration with KIS.API credentials

Full size image

7.2 Essential Functionalities

The objective of this section is to provide essential KIS.API functionalities. This starts from access to assets being simply KIS.Devices, users and asset groups up to the related Datapoints. Finally, a set of recipes concerning an access to calculated Datapoints and KPIs is provided.

7.2.1 Obtaining Information About Asset Groups, Assets and Users

As introduced in Chap. 2, KIS.Devices constitute the core KIS.ME components. Thus, knowing all of them, along with their membership to particular asset groups (see Chap. 2), is of paramount importance. Table 7.4 presents the list of all available KIS.API requests concerning assets along with the designated actions. As can be observed, most requests require additional path variables:

  • assetUrn: directly printed on an asset (KIS.Device) and can be retrieved through request no. 1 from Table 7.4 or through KIS.MANAGER;

  • assetgroupId: can be retrieved through the request no. 1 in Table 7.5.

The response pertaining to the request detailed in Table 7.4 may contain the following parameters:

  • ID: the asset identifier,

  • URN: the asset URN,

  • name: the name of the asset,

  • isOnline: the asset isOnline Datapoint value,

  • hardware: information about the asset hardware,

  • software: information about the asset software,

  • certificate: information about the asset certificate,

  • network: information about the asset network,

  • firmwareUpdate: information about the asset firmware updates,

  • assetGroupIDs: an array containing numerical values of the asset groups associated with the asset.

Note that most of the above features can be directly accessed through KIS.MANAGER by selecting Main menu \(\rightarrow \) Assets and then choosing a desired asset. Subsequently, the information about the asset can be retrieved by pressing (see Fig. 2.16).

Table 7.4 List of possible requests associated with an asset
Full size table
Table 7.5 List of possible requests associated with an asset group
Full size table

Having all the above information, let us proceed to two simple examples of using the discussed requests.

Obtaining a list of assets

This example concerns a response to the request no. 1 listed in Table 7.4. As a result, the following JSON structure can be obtained:

figure h

As can be observed, the response contains information about two KIS.BOXes, which are assigned to two asset groups (9757 and 9758).

Removing an asset from the asset group

This example concerns a response to the request no. 5 listed in Table 7.4. Let us consider the first asset (KIS.BOX) given in the preceding example. Its URN is urn:rafi:sbox:9c65f93cbed6, and it is assigned to two asset groups 9757 and 9758. The objective is to remove it from the asset group 9757, and hence the assetgroupId parameter should be set to 9757. As a result, the following JSON structure can be obtained:

figure i

which simply means that it is impossible to remove an asset from the list of all available assets (see Table 2.5 for a comprehensive explanation). Thus, let us change the assetgroupId parameter to 9758 (the second available asset group). As a result, the following JSON structure is obtained:

figure j

As can be observed, the assignment of this asset to the asset group 9758 was removed.

Let us proceed to the asset groups for which the available request list is given in Table 7.5. As can be observed, most requests require an additional parameter assetgroupId, which can be retrieved through the request no. 1 in Table 7.5. The response pertaining to the request detailed in Table 7.5 may contain the following parameters:

  • ID: the asset group identifier,

  • assetIDs: an array containing numerical values of asset IDs associated with the asset group,

  • name: the name of the asset,

  • isOnline: the asset isOnline Datapoint value,

  • description: a detailed description of the asset group,

  • name: the name of the asset group.

Let us proceed to two simple examples explaining the application of the above requests.

Obtaining a list of asset groups

This example concerns a response to the request no. 1 listed in Table 7.5. As a result, the following JSON structure can be obtained:

figure k

As can be observed, the response contains information about two asset groups and the assets associated with them (IDs: 10102, 10153).

Updating the asset group description

This example concerns a response to the request no. 3 listed in Table 7.5. Let us provide a new description of Workspace 1 (ID 9758) in the JSON form:

figure l

In the case of the Postman application, to provide such a description one should go to the Body tab of the request and enter the above JSON structure. As a result, the following JSON structure can be obtained:

figure m
Table 7.6 List of possible requests associated with users
Full size table

Having access to assets and the associated asset groups, let us proceed to the user management functionalities, which are listed in Table 7.6. As can be observed in Table 7.6, requests no. 2 and 3 require an additional path parameter called accountNumber. Note that in KIS.MANAGER the user is identified by its name and email. Thus, at least one of these parameters should be known while realizing the request no. 1 in Table 7.6. Thus, the obtained response can be used to obtain the associated accountNumber.

Displaying all users and their accountNumber

This example pertains to realisation of the request no. 1 in Table 7.6. As a result, the following JSON structure can be obtained:

figure n

The structure contains information about two users and their associated accountNumber.

Deleting a user

The JSON structure obtained in the preceding example contains information about two users. The objective of the current example is to delete the user identified:

figure o

For that purpose, the above number has to be provided as a path parameter in the Postman application. Note that, after sending a request to KIS.API, no JSON structure is received (cf. code 204 in Table 7.3).

Table 7.7 List of possible requests associated with Datapoints
Full size table

7.2.2 Accessing Data Through Datapoints

The objective of this point is to provide a way of accessing the data associated with Datapoints. For a comprehensive description of Datapoints, the reader is referred to Sect. 2.7 and Appendix. B. The possible requests associated with Datapoints are provided in Table 7.7. It should be also noted that the above requests require the following path parameters:

  • assetUrn: directly printed on an asset (KIS.Device), can be retrieved through the request no. 1 from Table 7.4 or through KIS.MANAGER;

  • datapointDefinition: the Datapoint name, e.g., button1Pressed.

Additionally, request no. 2 in Table 7.7 can be executed with the following query parameters:

  • from: an ISO timestamp indicating a lower bound of the required time range;

  • to: an ISO timestamp indicating an upper bound of the required time range;

  • limit: a maximum number of required Datapoint values.

Note that it is not compulsory to use all of the above-listed query parameters simultaneously. For example, the limit parameter can be employed as a standalone one.

Obtaining a list of Datapoints

The example is concerned with the request no. 1 in Table 7.7. As a result of using it, a full list of Datapoints along with their types is returned. A sample form of such a couple is given as follows:

figure p

Obtaining five recent Datapoint values

For the purpose of this example, a set of two rules is implemented (see Sect. 2.9 for more details), i.e.,

  1. 1.

    If the KB Button1 operational LED color is black, then the KB Button 1 operational LED color is red.

  2. 2.

    If the KB Button 1 operational LED color is red, then the KB operational LED color is black.

Thus, the purpose of the above rules is to switch the KB Button1 operational LED color from red to black (no illumination) and vice versa. This means that the resulting effect should be the KB Button 1 operational LED blinking in red. However, to achieve such an effect, the KB Button 1 operational LED color should be initiated using its digital twin (see Sect. 2.6) by setting the above color to either black or red. Subsequently, the path parameters should be defined, i.e., assetUrn and datapointDefinition. The latter one is set to button1ColorKpi. Finally, the query parameter limit is set to five. As a result, a JSON structure is obtained containing the five recent values of the indicated Datapoint:

figure q

The recorded Datapoint values simply indicate that the KB Button 1 operational LED changes its color from red (5) to black (2) and vice versa. As can be observed, the switching process takes more or less one second. However, this time is data transfer-dependent, and hence its is not uniform.

Obtaining five recent Datapoint values from a given time frame

The objective of this example is to focus on the reader attention to ISO data-time format, which is given, e.g., by

figure r

Its construction is obvious: however, it contains characters which are not permitted in a URL construction, i.e. ‘.’, which should be simply replaced by its equivalent equal to ‘%3A’, yielding

figure s

Thus, by setting the from query parameter according to the above form one can obtain:

figure t
Table 7.8 List of possible requests associated with CDPs
Full size table
Table 7.9 List of possible requests associated with KPIs
Full size table

7.2.3 KPIs and Calculated Datapoints

This section constitutes a continuation of the preceding one. Indeed, CDPs and KPIs (see Sect. 4.1.2 and Appendices A and B) employ Datapoints as a basis for forming desired answers pertaining to the system state and performance. The CDP requests are similar to those for Datapoints (see Table 7.7), and they are presented in Table 7.8. It should be also noted that the above requests require the following path parameters:

  • assetUrn: directly printed on an asset (KIS.Device), can be retrieved through the request no. 1 from Table 7.4 or through KIS.MANAGER;

  • calaculatedDatapointDefinition: CDP name, e.g., kg2lb.

Additionally, the request no. 2 in Table 7.8 can be executed with the following query parameters:

  • from: an ISO timestamp indicating a lower bound of the required time range;

  • to: an ISO timestamp indicated an upper bound of the required time range;

  • limit: a maximum number of required CDP values.

Now, let us proceed to KPI requests available through KIS.API. They are given in Table 7.9, and it is not surprising that they are similar to those presented in Table 7.8. Additionally, they path parameters are given by

  • assetUrn: directly printed on an asset (KIS.Device), can be retrieved through request no. 1 from Table 7.4 or through KIS.MANAGER;

  • kpiDefinition: the CDP name, e.g., kg2lb.

Unlike Datapoints and CDP, the KPI request no. 2 (see Table 7.9) has to be executed with the following query parameters:

  • from: an ISO timestamp indicating a lower bound of the required time range;

  • to: an ISO timestamp indicate an upper bound of the required time range.

Accessing the list of KPIs

Let us continue with the example presented in Sect. 7.2.2 pertaining to a KIS.BOX associated with two rules. These two rules perform cyclically one after the other. The first one change the KIS.BOX Button 1 operational LED color from black to red while the second one realizes an opposite situation. It is assumed that no KPIs are defined for this KIS.BOX (see Sect. 4.1.2 for a detailed tutorial on KPIs). Thus, let us define the KPI counting the entire time period for which the above mentioned color is red. For that purpose, the following KPI is implemented:

figure u

where x stands for the button1ColorKpiDuration Datapoint while the number five signifies the red color (see Table 2.2). Finally, let us assume that this KPI is named KBButton1red while its processing period  is set to 15 min. Having the above KPI, let us proceed to performing the request no. 1 in Table 7.9. As a result, the following JSON structure is obtained:

figure v

Accessing KPI values

Let us continue with the above example. Now, the task is to obtain KBButton1red (path parameter kpiDefinition) values within the time period defined by the parameters {\lsquo}from{\rsquo} and {\lsquo}to{\rsquo} given by

figure w

which, as discussed in Sect. 7.2.2, are formatted according to

figure x

As a result, the following JSON structure is obtained:

figure y

It can be easily observed that there are 12 values corresponding to 15-minute processing periods. It is also straightforward to observe that 15 min are equivalent to 900 s. Thus, it is evident that all the above-presented values should oscillate around 450 s, which is actually the case.

Accessing data from CDPs

The last task of this point concerns obtaining an information about predefined CDPs as well as finding their values. For that purpose, it is assumed that no CDPs are defined. Moreover, the preceding example is continued. Thus, a new CDP is defined according to the approach presented in Sect. 4.1.1 with x equivalent to button1ColorKpiDuration Datapoints. The developed CDP aims at bounding the minimum numerical value of x to 3, which represents the green color (see Sect. 2.6). As a result, the following simple implementation is obtained:

figure z

while CDP itself is named KBmaxcolorCDP. Let us start with the request no. 1 in Table 7.8, which pertains to obtaining a list of all available CDPs. As a result of using it, the following JSON structure is arrived at:

figure aa

which contains the existing CDP names as well as their data types. Having the CDP name, let us proceed to obtaining its values. In fact this process is identical to the one presented in Sect. 7.2.2. According to the adjustment performed in the preceding examples, x can have the values representing either the red or the black color, i.e., \(x=5\) or \(x=2\) (cf. Table 2.2). The request No. 2 in Table 7.8 is executed with the query parameter limit only, which is equal to 10. As a result, the following JSON structure is obtained, which provides the desired results:

figure ab
Table 7.10 List of possible requests associated with rules
Full size table

7.2.4 Accessing Information About Rules

Rules (cf. Sect. 2.9) constitute the last component which can be accessed through KIS.API. The currently possible requests are provided in Table 7.10.

Additionally, the request no. 2 in Table 7.10 should be executed with the following path parameters:

  • ruleId: the rule identification number which can be retrieved through the request no. 1 from Table 7.10.

  • assetgroupId: asset group identification.

The parameters that can be accessed through the process of executing these requests are

  • name: the name of the rule provided in KIS.MANGER Rule engine;

  • enabledAPI: a logical property stating if it is possible to trigger the rule from an external application using KIS.API.

Obtaining information about rules

The objective of this example is to show how to access information about rules. Let us start with the request no. 1 in Table 7.10, which does not require any path or query parameters while its execution results in the following JSON structure:

figure ac

Contrarily, having assetGroupId and id signifying the rule, one can obtain the name of the rule and the logical property enabledAPI. Indeed, by using them as the path parameters and then executing the request no. 2 in Table 7.10, one can arrive at the following JSON structure:

figure ad

7.2.5 Triggering Rules from External Applications

The objective of this section is to introduce a very important feature of KIS.API, which makes it possible to trigger a rule from an external application. However, as mentioned in Sect. 7.2.4, such an operation is possible for the rules having the enabledAPI property set to the logical truth. For example, the rule considered at the end of Sect. 7.2.4 should have the following JSON structure:

figure ae

Note that the modification of the enabledAPI property is possible through KIS.MANGER only. For that purpose, one should use the Main menu \(\rightarrow \) Asset groups and then select an appropriate asset group. Subsequently, by going to Rule engine and selecting the desired rule, one can see the property editor called API integration, which is presented in Fig. 7.3. As can be observed, there is another property, which is called Websocket-Action. However, it will be discussed in Sect. 7.5. Finally, the rule triggering request is described in Table 7.11.

Fig. 7.3
figure 3

Setting enabledAPIproperty

Full size image
Table 7.11 a requests associated with a rule trigger
Full size table

7.3 KIS.API in Practice

The purpose of Sect. 7.2 was to introduce to the reader the essential functionalities concerning KIS.API. All of them were carefully described while their practical usage was explained with the Postman (https://www.postman.com/) application. The objective of this section is to provide practical guidelines concerning KIS.API application using some popular software. Indeed, the software selection being used in this section is not accidental. The first candidate is employed widely both in the industry for presenting various kinds of data in tabular order. The second one is commonly used for research, analysis, development and deployment of new practical concepts based on data gathered from a given system. Thus, these two popular software instances are

Both of them have several different and freely-available counterparts, which can provide similar functionalities. Thus, the objective of the subsequent point is to provide a short practical tutorial on feeding MS Excel and Matlab with KIS.ME data. Although the current section is restricted to MS Excel and Matlab, the reader possessing the knowledge about the KIS.ME essential functionalities can integrate it with more advanced and dedicated software. An enterprise resource planning system can be a good example of such software (see, e.g., SAP and its API functionalities at https://api.sap.com/).

7.3.1 Feeding MS Excel with KIS.ME Data

Starting with MS Excel 2013 it is possible access any REST API using the so-called power query. Thus, the entire recipe for accessing data from KIS.API boils down the following steps:

  1. 1.

    Select and push the from Web power query icon.

  2. 2.

    Provide the URL associated with the desired request.

  3. 3.

    Use advanced options to provide appropriate headers, i.e., X-CLIENT-ID and X-API-KEY (see Fig. 7.1).

  4. 4.

    Perform the desired data request.

Obtaining a list of all rules

The objective of this example is to obtain a list of all rules present in KIS.MANAGER Rule engine. According to Sect. 7.2.4, a URL should be defined as follows:

figure af

while the required headers may have the following structure:

figure ag

Finally, the desired data request is performed and the obtained result is given in Fig. 7.4. As can be observed, there are three records, which simply correspond to three different rules. To make the obtained result more transparent, the option Convert to Table can be used used, which after suitable expansion yields the view presented in Fig. 7.5.

Fig. 7.4
figure 4

Result of a KIS.API request in MS Excel

Full size image
Fig. 7.5
figure 5

Result of a KIS.API request presented as a table

Full size image
Fig. 7.6
figure 6

Result of a KIS.API request in Matlab

Full size image

7.3.2 Feeding Matlab with KIS.ME Data

The objective of this section is to show how to realise the KIS.API GET request with MATLAB. The entire process boils down to the following steps:

  1. 1.

    Provide the URL associated with the desired request.

  2. 2.

    Define the weboptions structure HeaderFields containing the returned content type, X-CLIENT-ID and X-API-KEY.

  3. 3.

    Define optional query parameters.

  4. 4.

    Execute webread to obtain data associated with the desired request:

    figure ah

Accessing Datapoint values

The primary objective of this example is to obtain twenty recent values of the

button1ColorKpi Datapoint of KIS.BOX defined by a given URN. For that purpose the example introduced in Sect. 7.2 is utilized. Let us start with defining an appropriate URL according to Sect. 7.2.2 (Table 7.7), which can be realized as follows:

figure ai

Subsequently, the weboptions structure with HeaderFields is defined:

figure aj

Finally, webread can be executed:

figure ak

However, the current example, apart from retrieving data, extracts the values and occurrence times of the KIS.API data. Moreover, such a request is repeated every second and the obtained results are suitably visualized. Such a time-driven loop is repeated until a user presses any key. The code realizing all the above mentioned operations is given as follows:

figure al

The obtained results are given in Fig. 7.6. As can be observed, the value of button1ColorKpi Datapoints is switched between black (2) and red (5) colors.

Remark 7.1

The example presented in this point corresponds to the so-called polling procedure in which KIS.API requests are repeated every single second. This process is, of course, inefficient as it is executed irrespective of the fact of having new KIS.API data. Indeed, even if there is no new data, the request is still executed. To settle this unappealing phenomenon, KIS.ME provides the so-called websockets, which are discussed in Sect. 7.5.

7.4 Triggering Rules from MATLAB

The objective of this section is to show how to realize a KIS.API POST request with Matlab. For that purpose, an example with triggering the rule is engaged. Generally, the entire process boils down to the following steps:

  1. 1.

    Provide the URL associated with the desired request.

  2. 2.

    Define the weboptions structure HeaderFields containing the returned content type, X-CLIENT-ID and X-API-KEY.

  3. 3.

    Define optional request parameters.

  4. 4.

    Execute webread to obtain the data associated with the desired request:

    figure am

Triggering a rule from MATLAB

The objective of this example is to show how to trigger KIS.ME rule from MATLAB. For that purpose, let us define a new rule. This rule has no triggers or conditions defined in KIS.MANGER. It aims at switching the KIS.BOX Button 2 operational LED color to yellow. Thus, there is only one action which performs the above task. Subsequently, API Integration (see Fig. 7.3) is used to set the enabledAPI property by activating the API-Trigger active option. The remaining information required to formulate the rule triggering request reduces to collecting

  • Rule ID: 13fcb514-9fe7-44a9-9802-3d972b0fee8a,

  • Asset group ID: 9758.

Having the above information, it is possible to formulate the triggering request according to Table 7.11. Finally, the resulting code is given as follows:

figure an

7.5 Websockets

In spite of an incontestable appeal of the communication strategies presented in the preceding part of this chapter, they frequently suffer from the lack of efficiency. This is particularly the case when there is a need for observing the changes in system behaviour expressed in the evolution of Datapoints associated with KIS.Devices. Indeed, such a problem was already discussed in Sect. 7.3.2. The example considered in the preceding section concerned the so-called polling procedure, in which KIS.API requests are repeated every single second. This process is, of course, inefficient as it is executed irrespective of the fact of having new KIS.API data. Indeed, even if there is no new data, the request is still executed. To settle this unappealing phenomenon, KIS.ME provides the so-called websockets, which are discussed in this section.

7.5.1 Brief Introduction to Websockets

Websocket [4] can be defined as a communication protocol, which permits bidirectional communication between the client and the web server. In a most common case, if a browser visits a web page, then an HTTP request is sent to the associated server. Subsequently, the web server replies by sending the response to the web browser. A similar strategy was realized in the preceding part of this chapter while using a different kind of applications, i.e., POSTMAN, MS Excel and Matlab. Thus, as was shown in Sect. 7.3.2, if the application wants to receive recently released data, then it must constantly, e.g., every second, send a request to the server. This corresponds to the situation in which the user constantly refreshes the page within the browser. This is also the reason why HTTP is a half duplex, which denotes the fact that the traffic flows in a single direction at a time:

  • the client releases a request to the server (one direction);

  • the server replies to the request (one direction).

Therefore, it is an obvious fact that it is not an elegant solution, widely called polling. It is defined as a regularly timed synchronous call in which the client releases a request to the server to check if there is any new data available. Such requests are realized using regular time intervals, and the client receives a response irrespective of the availability of the new data. Thus, if there is no new data, then the server replies with a negative response and the connection closes. Hence, polling can be efficient when an exact time interval concerning the release of the new data is known. Unfortunately, as has already been mentioned, KIS.ME is used to model a discrete event system in which the occurrence time of events is not equally distributed over a time horizon. Another communication strategy is called long polling. In this case, the client sends request to the server and opens a connection within some time period. If the server has no new data, then it holds the request and connection open until it has a new data for the client (or a predefined timeout is reached). An alternative communication strategy is called streaming. In this case, the client sends a request to the sever, which maintains an open response that is continually updated. The connection can be open permanently or until a predefined timeout is reached. Note that the server never indicates the completion of the HTTP response, and hence the connection is open continuously.

In order to eliminate the above issues, the concept of websocket was introduced. The websocket is by nature a bidirectional full duplex and single-socket connection. While using it, a single HTTP request is required to open a websocket connection. An appealing property of websocket is that it reuses the same connection in both ways, i.e., client–server and server–client. Owing to the fact that the server can send messages as they are available, the overall latency is reduced. Contrarily to polling, websocket communication is based on a single request, i.e., it is not necessary to wait for another request (along with headers, request parameters, etc.). A concise summary of using the websocket can be formulated as follows:

  • it makes real-time communication much more efficient;

  • it enables a simpler Web-based communication between the client and server;

  • it is a network protocol that enables developing other standard protocols on top of it;

  • it overcomes the drawbacks of HTTP with respect to real-time communication.

Similarly to HTTP and HTTPS, the websocket defines two URI schemes, namely, ws and wss, which correspond to standard and encrypted communication between the client and the server. The wss (Websocket Secure) URI scheme corresponds to the websocket connection over transport layer security (TLS). Note that TLS is also known as SSL (Secure Socket Layer). Thus, the same security mechanism is used as the one employed for HTTPS. This means that while constructing websockets one should use a URL of either the ws:// or wss:// form.

7.5.2 Obtaining a KIS.ME URI and Identifiers

The objective of this point is to show how to retrieve a URI and an identifier necessary to construct a websocket. The first step on the way towards the above objective is to select the data of interest, which can be the following:

  • Datapoints: one can obtain real-time data corresponding to Datapoints or calculated Datapoints (see Sects. 2.5 and 4.1.1) of an asset;

  • KPIs: one can obtain data corresponding to KPIs (see Sects. 2.5 and 4.1.1) of an asset, which are calculated every 15 min assuming that the new underlying Datapoint values are available;

  • Rules: one can obtain data associated with the triggered rules.

Thus, the required preliminary data is associated with the property subscribeTo, which may have the following values:

  • datapoint,

  • kpi,

  • rule.

Subsequently, Datapoints and KPIs require a single or a list of assetIds (see Sect. 7.2) while rules require assetGroupIds. Finally, all these properties form a JSON data structure, which may look as follows:

figure ao

Having the above data along with KIS.API credentials (see Sect.7.1.1), one can perform a POST request according to Table 7.12. As a result, the following JSON structure can be obtained:

figure ap

Analogously, the DEL request will unsubscribe from the websocket.

Table 7.12 Requests of subscribing/unsubscribing to a websocket 
Full size table

7.5.3 Brief Introduction to STOMP

Messaging [4] stands for an architecture associated with sending asynchronous messages between independent components. Such an appealing property makes it possible to develop relatively loosely coupled systems. The crucial components of messaging are the message broker and the client. In particular, the former can perform such actions:

  • accepting connections of the clients,

  • sending messages to the clients,

  • distributing messages among the clients.

Note that the broker can also handle such operations as authorization, message encryption, etc. Thus, if clients are connected to the broker, then they can send messages to the broker as well as receive message distributed by the broker. Such a strategy is called publish/subscribe. Therefore, if a message broker publishes a number of messages, then the client can subscribe to either all or a subset of these messages. STOMP (simple text-oriented messaging protocol) is a good representative example of such a publish/subscribe protocol. Its layering relation with the websocket as well as with other protocols is detailed in Fig. 7.7. STOMP was also employed for the communication purposes within KIS.ME. Indeed, the websocket fits very well to a standard messaging architecture, in which there could be a large volume of potential messages distributed at high rates from the broker to the client. A good example is a client subscribing to Datapoints of an asset (see Sect. 7.5.2). Due to the relatively large number of Datapoints as well as their possible high rate of change, receiving messages in real-time as well as with low latency is extremely important for the final performance of the entire application. STOMP is a very simple protocol, which resembles HTTP in its appearance. Each frame consists of a command, headers, etc. STOMP messages can represent any text or binary data. For further information about STOMP, the reader is referred to the STOMP protocol specification [5]. Additionally, STOMP [5] provides the so-called heart-beating mechanism, which can optionally be employed to verify the healthiness of the underlying TCP connection and to ensure that the remote end is still alive and kicking. Generally, it is defined by two integer values, separated by a comma. The first one represents outgoing heart-beats from the sender:

  • 0 signifies the fact that it cannot send heart-beats;

  • otherwise it is the smallest number of milliseconds between heart-beats that it can guarantee.

The second one represents incoming heart-beats, i.e., what sender would like to obtain:

  • 0—stands for the fact that it does not want to receive heart-beats;

  • otherwise it is the desired number of milliseconds between heart-beats that it can guarantee.

Note that enabling heart-beating is possible by adding a suitable heart-beating header during the beginning of the STOMP session, i.e., to CONNECT [5].

Fig. 7.7
figure 7

STOMP over a websocket

Full size image

7.5.4 Sample Websocket Implementations

The objective of this section is to provide guidelines for practical implementation of KIS.ME-based websockets. In particular, the NODE.js [1] environment, which employs a widely employed JavaScript (JS) programming language is used. This section is composed of two examples, which aim at

  1. 1.

    reading KIS.ME data using STOMP over websocket,

  2. 2.

    enhancing the above example with a local Web server employed for publishing KIS.ME data.

Moreover, it is assumed that the reader has essential knowledge regarding NODE.js.

Reading KIS.ME data using STOMP over a websocket

Let us start with providing suitable credentials and parameters, which will be located in the .env file:

figure aq

For the purpose of further implementations, the following modules are required:

  • dotenv: loads environment variables from the .env file into process.env structure;

  • websocket: implements the websocket protocol;

  • webstomp-client: provides a STOMP client for Web browsers and NODE.js through websockets;

  • axios: is a promise-based HTTP client for the Web browser and NODE.js.

Note that the application of the above modules is not compulsory and there are several counterparts which can be employed instead. Moreover, their documentation can be easily found at https://www.npmjs.com. After such a preliminary step, it is possible to define suitable request headers and options, which are given as follows:

figure ar

while the underlying POST request concerns subscription to a websocket (see Sect. 7.5.2). Thus, the objective is to obtain (cf. subscribeTo) the values of Datapoints and calculated Datapoints of KIS.Devices associated with assetIds and assetGroupIds. Note that the last property is not compulsory for obtaining Datapoint values. Subsequently, let us assume that both incoming and outgoing heart-beating is set to 1000 ms. Having all the above ingredients, the final code is developed, which is mostly included in the getSubscriptionId function:

figure as
figure at

The example considered is a continuation of the ones exploited in this chapter for which the KIS.BOX (assetIds=10102) Button 1 operational LED color switches between red and black. The above KIS.BOX has also associated calculated Datapoint and KPI. After running the above code, one can observe that message.body contains the JSON structure, which may look as follows:

figure au

The above JSON structure is self-explained and it can be easily observed that it contains the info property, which covers another JSON structure involving

  • key: the name of the (calculated) Datapoint,

  • value: the value of the (calculated) Datapoint,

  • timestamp: the timestamp associated with the value of the (calculated) Datapoint,

and hence, this structure is directly displayed in the console. Note that the above code can be easily adapted to the remaining possible settings of subscribeTo, i.e., kpi and rule. However, such an implementation is left out to be featured an exercise listed in the last section of this chapter.

> Getting information about the rules

Contrarily, to KPIs and Datapoints, rules are directly associated with asset groups. Indeed, there are designed within each asset group. This implies the necessity of a reduced subscription data:

figure av

while assetIds is excluded.

Publishing KIS.ME data with a local Web server

The objective of this example is to extend the proceeding one in such a way as to provide the following functionalities:

  • feeding the selected Datapoint data to another bi-directional third party API,

  • a frontend displaying the selected Datapoint data obtained from the above API.

Let us start with selecting an API. Since the purpose of the example is to collect the data in the form of a JSON structure containing three properties (key, value and timestamp) the list of possible candidates is rather long. Thus, due to relative usage simplicity, the Pusher API was selected (https://pusher.com/). As was the case with KIS.API, the first step is to register with Pusher and then collect the list of credentials (App keys). A sample list of Pusher credentials is given as follows:

figure aw

Thus, let us extend the .env file with the above data, which yields

figure ax

Having the above information, let us simply extend the code from the previous example with a list of commands creating a Pusher instance:

figure ay

Now let us assume that the Datapoint of interest is called button1ColorKpi Duration (see Appendix. B for its description). Thus, the transfer of Datapoint values to the Pusher API reduces to the following:

figure az

where b1ColorKpiDuration signifies both the so-called channel and event (see https://www.npmjs.com/package/pusher for a detailed explanation). The preparation of the backend concludes with including the code for the local Web server. For that purpose the express module is used, which can be simply characterized as a lightweight NODE.js Web server. The entire code reduces to adding the following lines:

figure ba

which are responsible for creating an express Web server that will run on port 3000 and will communicate with server static files located in the public directory. Finally, the entire backend code can be implemented as follows:

figure bb
figure bc

Let us proceed to the frontend development by creating the public directory and the index.html file inside it. The presentation of Datapoint values will be reduced to showing its consecutive values in the form of a plot. For that purpose the well known plotly is employed. Thus, the entire frontend reduces to the following code:

figure bd

The main part of the code starts with creating an empty plot located in the chart section of the HTML document (newPlot). Subsequently, a new Pusher instance is created with the above-defined credentials named key and cluster. This enables forming a new channel b1ColorKpiDuration. Finally, the channel.bind command is responsible for receiving cyclically arriving Datapoint values. It also invokes the extendTrace command, which updates the existing plot with the new data. Note that the plot is restricted to presenting 23 most up to date values, which requires appropriate scaling realized with the relayout command. The graphical result obtained after running the entire application, i.e. the one presented in the browser, is given in Fig. 7.8.

Fig. 7.8
figure 8

Plotting datapoint values with a local Web server

Full size image

7.6 Training Exercises

7.1

Obtaining a list of assets

  1. 1.

    Obtain a JSON structure containing all KIS.Devices which are at your disposal.

  2. 2.

    Find all assets which are on-line.

7.2

Obtaining a list of asset groups

  1. 1.

    Obtain a JSON structure containing all asset groups.

  2. 2.

    Modify the name and description of a selected asset group.

7.3

Obtaining a list of users

  1. 1.

    Obtain a JSON structure containing all users and determine their account Number.

  2. 2.

    Obtain a user and determine the above JSON structure once again.

  3. 3.

    Delete the added user.

7.4

Obtaining a list of Datapoints and CDPs

  1. 1.

    Select a KIS.Device and determine its URN.

  2. 2.

    Obtain a JSON structure containing a list of all Datapoints.

  3. 3.

    Determine a list of CDPs.

7.5

Obtaining values of Datapoints and CDPs

  1. 1.

    Choose a KIS.Device and write a set of rules transferring automatically and cyclically its selected operational LED within a state-space: red, yellow, green.

  2. 2.

    Obtain a JSON structure containing a list of 10 recent values of Datapoints corresponding to the numerical values of the operational LED’s colors.

  3. 3.

    Prepare CDP converting the numerical values of the operational LED’s colors in such a way so that red corresponds to 0, yellow is signified by 1, while green yields 2.

  4. 4.

    Obtain a JSON structure containing a list of 10 recent values of the above CDP.

7.6

Obtaining values of KPIs

  1. 1.

    Continue Exercise 7.5 by implementing KPIs calculating mean times of each state, i.e., red, yellow and green.

  2. 2.

    Obtain a JSON structure containing all KPIs.

  3. 3.

    Obtain a JSON structure containing a list of 10 recent values of the above KPIs.

7.7

Obtaining information about rules

  1. 1.

    Continue Exercise 7.5 and display the information about rules used for color state transitions.

  2. 2.

    Import the information about the rules to MS Excel or any compatible software.

7.8

Triggering rules from an external application

  1. 1.

    Select a KIS.LIGHT.

  2. 2.

    Prepare two rules with API-Trigger active (see Fig. 7.3):

    • GoRed: with an action setting the KIS.LIGHT operational LED color to red;

    • GoGreen: with an action setting the KIS.LIGHT operational LED color to red;

  3. 3.

    Develop a Matlab (you can also use OCTAVE or Pyton) program, which will trigger these rules every second one after the other.

7.9

Websocket implementation

  1. 1.

    Continue Exercise 7.5 and develop websocket-based application according to the scheme presented in Sect. 7.5.4.

  2. 2.

    Use the above-developed software to get information about the triggered rules and KPI calculation. Hint: use the subscribeTo property.

7.10

Websocket implementation

  1. 1.

    Continue Exercise 7.9 and extend it according to Sect. 7.5.4 in order to get a local web server employed for presenting selected Datapoint values.

  2. 2.

    On the frontend side (index.html) implement a functionality calculating the total accumulated time of the red color state, i.e., the overal time in which the operational LED color is red.

7.7 Concluding Remarks

The aim of this section was to provide an overview of KIS.API functionalities. It was demonstrated that the software provides an effective way for communicating with external applications. In particular, the chapter started with KIS.API user registration and goes through KIS.API essential functionalities. These functionalities are strictly linked with the content of the preceding chapter. Indeed, it is shown how to prepare request for accessing the information about assets, asset groups, users, Datapoints, CDPs, KPIs as well as the rules. The crucial functionality, which makes KIS.API a fully bidirectional framework is the ability of triggering the rules from external applications. In particular, it was shown how to trigger such rules from Matlab, which is one of the most popular development tools in modern engineering. The last part of the chapter was devoted to the development of efficient websocket-based communication framework, which utilizes STOMP messaging architecture. Indeed, the websocket is an excellent for providing an efficient asynchronous bidirectional communication. It was also demonstrated how to prepare a local Web server for publishing Datapoint values. This crucially example clearly shows that with KIS.API there is an infinite spectrum of possible external extensions of KIS.ME. Finally, the chapter is summarized with a set of training exercises, which verify KIS.API-oriented skills.