ezeio2:apiref:subscribe

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		 Previous revision
ezeio2:apiref:subscribe [2021-01-26 20:34] – created andrehezeio2:apiref:subscribe [2021-01-28 23:49] (current) – andreh
Line 1: Line 1:
 ==== subscribe ==== ==== subscribe ====
  
-Request a websocket data stream, and commands to manage the data stream+Request a websocket data stream, and commands to manage the data stream.
  
 === Description === === Description ===
Line 11: Line 11:
  
 Subsequent calls using the subscribe command are used to manage the data stream. Subsequent calls using the subscribe command are used to manage the data stream.
 +
 +<WRAP center round important 60%>
 +This functionality requires firmware 21012701 or later in the device.
 +</WRAP>
 +
  
 === Parameters === === Parameters ===
  
 The ''subscribe/ticket'' call has no parameters The ''subscribe/ticket'' call has no parameters
- 
  
 === Example usage === === Example usage ===
Line 21: Line 25:
 Using the subscribe API requires the following steps: Using the subscribe API requires the following steps:
  
-1) +**Step 1 : Request ticket and metadata** 
-Request a websocket ticket and relevant meta data:+ 
 +Call the following API endpoint using valid API credentials:
 <code>https://api.eze.io/v1/subscribe/ticket</code> <code>https://api.eze.io/v1/subscribe/ticket</code>
  
-This will return a JSON object with metadata listing the systems that will be accessible through the websocket.+This call will return a JSON object (see example below) with metadata listing the systems that will be accessible through the websocket.
  
-The ''ws'' property is the complete websocket URI. This URI is valid only for 10 seconds following the call to subscribe/ticket. +//(whitespaces added for readability)//
- +
-2) +
-Use the ''ws'' URI to open a websocket connection. +
-The websocket will automatically receive all updates to any system (ezeio) covered by the API call credentials given in the original call to subscribe/ticket. +
- +
-The following update types will be sent over the websocket connection: +
-LOGDATA - log interval data +
-STATUS - 10 minute interval data. Always sent from all systems. +
- +
-3)  +
-Call ''subscribe'' with  +
- +
-=== Return value === +
- +
-JSON formatted data from the ''subscribe/ticket'' call: +
- +
-//(below example has added whitespaces for readability)//+
  
 <code javascript> <code javascript>
Line 111: Line 99:
 </code> </code>
  
 +The ''ws'' property is the complete websocket URI. This URI is valid only for 10 seconds following the call to subscribe/ticket.
  
 +The ''api'' property should be saved until the websocket is disconnected, as it is required for subsequent calls to update the data flow. 
 +
 +**Step 2 : Open websocket and start receiving data**
 +
 +Use the ''ws'' URI from step 1 to open a websocket connection.
 +The websocket will automatically receive all updates to any system (ezeio) covered by the initial API call, as the data becomes available to the cloud servers.
 +
 +The data received will have a ''type'', describing what kind of data this is:
 +| ''LOGDATA'' | The field data is from the 'fast log'. The interval is determined by the log interval setting on each field. |
 +| ''STATUS'' | The field data is from the 'status log'. The interval is fixed to 10 minutes. |
 +
 +Note that the ezeio normally buffers data before the data is uploaded to the cloud servers, so the data may be delayed with up to 20 minutes 
 +
 +The STATUS updates will be sent every 10 minutes even if a faster subscription is active.
 +
 +This is an example of what a ''STATUS'' update looks like (whitespace added for readability):
 +<code javascript>
 +{
 +  "channel": "export:123",
 +  "data": {
 +    "type": "STATUS",
 +    "serial": "ABC-123",
 +    "time": "2021-01-31T14:20:00Z",
 +    "fields": [
 +      {
 +        "1": 73.4
 +      },
 +      {
 +        "2": 8.112
 +      }
 +    ]
 +  }
 +}
 +</code>
 +Note that the fields array will include all configured fields for this unit - regardless of their log setting. All fields are always logged every 10 minutes.
 +
 +A ''LOGDATA'' update has the following format (whitespace added for readability):
 +<code javascript>
 +{
 +  "channel": "export:123",
 +  "data": {
 +    "type": "LOGDATA",
 +    "serial": "ABC-123",
 +    "time": "2021-01-31T14:21:15Z",
 +    "timeout": 0,
 +    "fields": [
 +      {
 +        "2": 9.021
 +      }
 +    ]
 +  }
 +}
 +</code>
 +Note that this message only includes the fields that are configured for fast logging (interval less than 10 minutes). Please see below for the meaning of the ''timeout'' property.
 +
 +**Step 3 : Request subscription changes**
 +
 +With an open websocket and while receiving data from the ezeio system, you can call the subscribe API to request immediate updates or to cancel updates from a certain ezeio.
 +
 +To request unbuffered log updates, the call is:
 +<code>https://api.eze.io/v1/subscribe/wstktXXXXXXXXXXXXXXXXXXXXXXX/ABC123</code>
 +The log updates will revert to normal (buffered) mode after 30 minutes.
 +
 +To cancel updates, the call is:
 +<code>https://api.eze.io/v1/subscribe/wstktXXXXXXXXXXXXXXXXXXXXXXX/-ABC123</code>
 +
 +Multiple requests can be sent in the same command:
 +<code>https://api.eze.io/v1/subscribe/wstktXXXXXXXXXXXXXXXXXXXXXXX/-ABC123,ABC124,ABC321,-ABC322</code>
 +Up to 50 devices can be included in the same command
 +
 +=== Example code to set up the websocket channel and receive data (PHP) ===
 +<code php>
 +<?php
 +    define("APIURI", "https://api.eze.io/v1/subscribe/ticket");
 +    
 +    // API keyID and key needs to be set up in eze.io under Groups->API.
 +    define("APIKeyID", "12345");
 +    define("APIKey", "XXXXXYYYYYXXXXXYYYYYXXXXXYYYYY");
 +
 +    // Using the textalk/websocket client
 +    // https://github.com/Textalk/websocket-php
 +    require('vendor/autoload.php');
 +    use WebSocket\Client;
 +
 +    // Request a websocket key and metadata using cURL
 +    $ch = curl_init();
 +    curl_setopt($ch, CURLOPT_URL, APIURI);
 +    
 +    // All API calls use Digest AUTH
 +    curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);        
 +    curl_setopt($ch, CURLOPT_USERPWD, APIKeyID.":".APIKey);
 +    
 +    // Set a 5s timeout, and return any received data
 +    curl_setopt($ch, CURLOPT_TIMEOUT, 5);
 +    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); 
 +    
 +    // Execute the cURL request
 +    $response = curl_exec($ch);
 +    curl_close($ch);
 +
 +    // Decode the json reply into an associative array
 +    $json = json_decode( $response, TRUE );                     
 +    
 +    // Status should be 'OK'
 +    if($json["status"] != "OK")                                 
 +        die("ERROR:\n" . print_r($json, TRUE));
 +
 +    // Open the websocket
 +    $wsclient = new WebSocket\Client( $json["ws"] );
 +    
 +    // Loop forever (until websocket disconnects)
 +    while ( true ) {                                            
 +        try {
 +            $message = $wsclient->receive();                      
 +
 +            // Process the data - here we just print it for testing
 +            print_r( json_decode( $message, TRUE ) );
 +        } 
 +        catch (\WebSocket\ConnectionException $e) {            
 +            // If the websocket was disconnected, exit the loop
 +            if( !$wsclient->isConnected() )
 +                break;
 +        }
 +    }
 +    $wsclient->close();
 +</code>
  • ezeio2/apiref/subscribe.1611693269.txt.gz
  • Last modified: 2021-01-26 20:34
  • by andreh