 |
Xentara WebSocket API Specification v2.0.3
User Manual
|
|
Xentara WebSocket API Specification v2.0.3
User Manual
|
| OpCode | Name | Description |
|---|---|---|
| 6 | subscribe | Establish a subscription for multiple attributes across different elements. |
The parameter object outlined in request packet for this command includes:
| ID | Name | Optional | Description |
|---|---|---|---|
| 0 | subscription_array | no | An array comprises objects containing the UUID of a Xentara Element and the attribute identifiers for which subscription is desired. |
| 1 | maximum_update_rate | yes | A maximum update rate for the notifications in milliseconds (see below). |
| 2 | minimum_update_rate | yes | A minimum update rate for the notifications in milliseconds (see below). |
| 3 | desired_subscription_id | yes | A UUID specifying the desired UUID of the Subscription (see below). |
Each object in the subscription_array should be structured as follows:
| ID | Name | Optional | Description |
|---|---|---|---|
| 0 | element_uuid | no | A UUID specifying the UUID of the Xentara element. |
| 1 | attribute_ids | no | An array comprising integers, UUIDs, or a combination thereof, containing values from the Xentara attributes or attribute UUIDs. |
The subscribe command provides parameters to define update rates, allowing clients to balance the need for timely data with the network capacity and the processing capabilities of the subscriber.
The maximum_update_rate parameter sets the fastest rate at which updates can be sent. For example, if the maximum_update_rate is set to 10 milliseconds, any update event occurring more frequently than every 10 milliseconds will not trigger an immediate event. Instead, the latest event within that 10 milliseconds window will be sent at the end of the period, ensuring no more than one update is sent every 10 milliseconds.
The minimum_update_rate parameter sets the slowest rate at which updates can be sent. For instance, if the minimum_update_rate is set to 1000 milliseconds (1 second), an event packet will be sent every second even if no new events have been triggered within that time frame, ensuring regular updates at the defined interval. The minimum_update_rate should be greater than maximum_update_rate.
If neither the maximum nor minimum update rates are set, event packets will be sent immediately whenever an event is triggered. This default behavior ensures that all events are promptly communicated.
The desired_subscription_id contains the UUID formatted as specified in format for UUID. If the desired_subscription_id is not supplied, the Xentara WebSocket interface will generate a new subscription id and return the new UUID in the response. If the provided desired_subscription_id already exists, the existing subscription will be replaced, meaning the old subscription with the same subscription id will be removed and a new subscription with updated information will be created. Also, the desired subscription UUID cannot be null.
The response to this command includes both a response packet and an initial update event message. The response item outlined in response packet for this command includes:
| Name | Type | Description |
|---|---|---|
| Subcription Id | UUID | A UUID specifying the UUID of the Subscription in format of UUIDs. |
The initial update event message contains values for all subscribed events, structured as described under event packet structure and is sent immediately after the response packet to initialize the subscribed data. In addition to the initial update event message, subsequent event messages will be sent based on the events generated. The update rates specified in the request can be used to control the frequency of these event updates.
If an error occurs, the response will include an error packet with detailed error information.
Below is the list of the potential errors that may be encountered with this command. Further details regarding errors in the Xentara WebSocket interface can be accessed here.
| Sr. No. | Error Code | Error Description |
|---|---|---|
| 1 | -32700 | Parse Error |
| 2 | -32603 | Internal Error |
| 3 | -32602 | Invalid Parameter |
| 4 | -32600 | Invalid Request |
| 5 | -32000 | Missing Client Hello Request |
| 6 | -32100 | Unknown Element |
Below is an example for the request to browse the Xentara model tree for the element with the UUID "e3ee1071-4d88-4ba1-8e5d-0f1e4ce25ee8". The request should retrieve information up to the second layer of depth and include categories "Element Group" and "Data Point". The message id 65 is an arbitrary number assigned for this particular request.
[
0, # Request Packet
65, # Message Id
6, # Subscribe OpCode
{ # Subscribe Object
0: [ # Subscription Array
{
0: 37('B24AFA7273B74D7EA7A39F60BCD19766'), # Xentara Element UUID
1: [1,11,37('88130CE8B9E74A2A8F26D32A931129AA')] # Array of Attribute Identifiers
}
], # Close Subscription Array
1: 500, # Maximum Update Rate in Milliseconds
2: 10000, # Minimum Update Rate in Milliseconds
3: 37('E3EE10714D884BA18E5D0F1E4CE25EE8') # Desired Subscription id
}
]
Below is an example of the successful response to the aforementioned request. It indicates a package type of 1, signifying a successful response. The provided Message ID is intended for matching with the corresponding request. The response includes the subscription id.
[
1, # Packet Type - Success Response
65, # Message Id
37('E3EE10714D884BA18E5D0F1E4CE25EE8') # Subscription Id
]
Also, below is an example of the initial update event to the aforementioned request.
[
8, # Packet Type - Event
0, # Event Type - Data Change
{
0: 1(4([-9, 179998887776665])), # Time Stamp
1: 37(h'B24AFA7273B74D7EA7A39F60BCD19766'), # Xentara Element UUID
2: { # Data Change Object
11: 121(25.98), # Attribute Ids and it's value
1: 121("Data Point 1"),
37('88130CE8B9E74A2A8F26D32A931129AA'): 121(true)
}
}
]