ezeio2:apiref:subscribe

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
ezeio2:apiref:subscribe [2021-01-26 22:48] – 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 96: Line 100:
  
 The ''ws'' property is the complete websocket URI. This URI is valid only for 10 seconds following the call to subscribe/ticket. 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** **Step 2 : Open websocket and start receiving data**
Line 103: Line 109:
  
 The data received will have a ''type'', describing what kind of data this is: 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. | +| ''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. |+| ''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  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** **Step 3 : Request subscription changes**
Line 112: Line 160:
 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. 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 fast updates, the call is: +To request unbuffered log updates, the call is: 
-<code>https://api.eze.io/v1/subscribe/!ABC123</code>+<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: To cancel updates, the call is:
-<code>https://api.eze.io/v1/subscribe/-ABC123</code>+<code>https://api.eze.io/v1/subscribe/wstktXXXXXXXXXXXXXXXXXXXXXXX/-ABC123</code>
  
 Multiple requests can be sent in the same command: Multiple requests can be sent in the same command:
-<code>https://api.eze.io/v1/subscribe/-ABC123/!ABC124/!ABC321/-ABC322</code>+<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.1611701294.txt.gz
  • Last modified: 2021-01-26 22:48
  • by andreh