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 JSON output. The following example shows how data is returned. An explanation of how data is sorted and how single and empty values are handled are all provided in this example.

{
  "message": {
    "points": [
      {
        "bool": [false], //only boolean value in data-source
        "int16": [225,175,3,2], //int16 sorted on tag ID
        "str": [""], //no string variable in this data-source
        "tags": [1,2,3,4,5,6,7,8,9,10,11,12,13], // all tag ID's in the return
        "time": 1607079466500, //UNIX timestamp in ms
        "uint16": [214,200,86,83,61,86], //uint16 sorted on tag ID
        "uint32": [1655898122] //uint32 sorted on tag ID
      }
    ],
    "sentTime": 1607079466590 //time at which data was sent
  },
  "agent": {
    "publicId": "{agent Id}"
  },
  "device": {
    "publicId": "{source Id}"
  }
}

Updated 9 days 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.