IXON-API

IXON API documentation

Welcome to the IXON development website. Curious about our API endpoints? Take a look at our endpoint list, you can try-out the API in that section as well. Do you need some guidance on how to use our API? Take a look at the API Documentation. Take a look at our release notes if you're curious what has changed to the API.

Endpoint List    Release Notes

How to set up a real-time data stream?

If you have set up Cloud Logging in the IXON Cloud, your IXrouter or IXagent will send PLC data to the IXON Cloud. A real-time data connection where your machine data will be sent every 0.5 second to your PC can be established using a WebSocket. Data retrieved through this connection will not be stored in the IXON Cloud. Please follow the steps below to establish a real-time WebSocket connection using the APIv2:

Step 1: Retrieve the required identifiers

To get started, you first need to retrieve an application ID, bearer token, company ID and agent ID. These values are necessary for proper authorisation and for the APIv2 to find the correct IXrouter or IXagent. This article explains how to request these values.

Step 2: Create a JWT Token

You need a JWT authorization token to create a real-time data stream. You can request a JWT Token using the AuthTokenDataList endpoint. You have to include the values you requested in step 1 in the request. You also have to set the expiration time for the token. The expiration time has to be between 1 minute (60 seconds) and 1 hour (3600 seconds). The example below contains the format for the request for a JWT Token and its response:

curl --request POST \
--url 'https://api.ayayot.com/auth-tokens/data' \
--header 'Api-Version: 2' \
--header 'Api-Application: {application Id}' \
--header 'Api-Company: {company Id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {secret Id}' \
--data '{
    "expiresIn": 3600,
    "agents": [
        {
            "publicId": "{agent Id}"
        }
    ]
}'
{
    "status": "success",
    "type": "AuthTokenCreateResponse",
    "data": {
        "publicId": "{token Id}",
        "secretId": "{JWT-Token}",
        "expiresOn": "2021-02-02T01:00:00Z"
    }
}

Step 3: Create a WebSocket entry

The next step is to set-up a WebSocket connection to read the real-time data. You can find the correct URL under the AgentDataRealTimeWebSocket endpoint in the discovery request.

Step 4: Authenticate your connection

When setting up a datastream in your software solution, you have to add a message with the JWT-token you requested in step 2. You have to put an event listener on onopen to prevent that the WebSocket will be closed by the server. You can prevent this by sending the JWT-Token with the onopen event listener. An HTML example of how this live data stream should be handled is provided below.

<!DOCTYPE html>
 <meta charset="utf-8" />
 <title>WebSocket Test</title>
 <script language="javascript" type="text/javascript">

 var wsUri = "wss://wse.mdr.ams.dkn.ayayot.com/agents/{AgentId},/data-realtime";
 var output;

 function init()
 {
   output = document.getElementById("output");
   testWebSocket();
 }

 function testWebSocket()
 {
   websocket = new WebSocket(wsUri);
   websocket.onopen = function(evt) { onOpen(evt) };
   websocket.onclose = function(evt) { onClose(evt) };
   websocket.onmessage = function(evt) { onMessage(evt) };
   websocket.onerror = function(evt) { onError(evt) };
 }

 function onOpen(evt)
 {
   writeToScreen("CONNECTED");
   doSend("Authorization: {JWT-Token});
 }

 function onClose(evt)
 {
   writeToScreen("DISCONNECTED");
 }

 function onMessage(evt)
 {
   writeToScreen('<span style="color: blue;">RESPONSE: ' + evt.data+'</span>');
 }

 function onError(evt)
 {
   writeToScreen('<span style="color: red;">ERROR:</span> ' + evt.data);
 }

 function doSend(message)
 {
   writeToScreen("SENT: " + message);
   websocket.send(message);
 }

 function writeToScreen(message)
 {
   var pre = document.createElement("p");
   pre.style.wordWrap = "break-word";
   pre.innerHTML = message;
   output.appendChild(pre);
 }


 window.addEventListener("load", init, false);

 </script>

 <h2>WebSocket Test</h2>

 <div id="output"></div>

 </script>

Step 5: Interpret your data-output

Real-time data is being returned in a JSON format. As the output is compressed to ensure the fastest connection possible, the data is a little difficult to interpret. In the output you will find a row that is called "tags". The values in this row are variable ID's, which are the key to interpret the data.

To understand the variable ID's, you send a GET request to the AgentDataVariableList endpoint with at least the fields "variableId", "name", "type", "signed" and "width". Your response should look like the example below.

{       
    "type": "AgentDataVariable",
    "data": [
        {...},
        {
            "publicId": "{publicId}",
            "variableId": 6,
            "name": "Weight",
            "type": "int",
                "signed": true,
            "width": "16"
        },
        {...}
    ],
    "moreAfter": null,
    "status": "success"
}

The variable ID corresponds with the value you can find in the "tags" row of the live data output. The name is the name of the variable to which that ID belongs, so we can see here that variable 6 is the weight. The other 3 fields can be used to determine the data type. In this case the data type is a 16 bit signed integer (int16).

With this information we can search for the weight in the live data output, which is shown in the example below. The first value for a data type is the one with the lowest variable ID, the second value for a data type is the one with the second lowest variable ID etcetera. So if you obtained the Variable IDs, data types and names, you can match the output with the names.

In the output below, variable numbers 6, 7, 11 and 12 are from the data type int16 (as we know from the full output of the example above). This means that variable 6 has value 225 and variable 11 has value 3 in the example below. From the previous request, we know that variable 6 has the name "weight" and thus the measured weight at the given time was 225.

In the whole output with all variable IDs we could also see that variables 8 and 9 are uint16 data types with the names "upperweight" and "underweight". Which are the highest and lowest reported weights at the given moment. Thus we can see that the highest weight was 250 and the lowest 200 in the given time.

{
  "message": {
    "points": [
      {
        "bool": [false],
        "int16": [225,175,3,2],
        "str": [""],
        "tags": [1,2,3,4,5,6,7,8,9,10,11,12,13],
        "time": 1607079466500,
        "uint16": [250,200,86,83,61,86],
        "uint32": [1655898122]
      }
    ],
    "sentTime": 1607079466590
  },
  "agent": {
    "publicId": "{agent Id}"
  },
  "device": {
    "publicId": "{source Id}"
  }
}

Updated 2 months ago


How to set up a real-time data stream?


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.