Request Packet: Sent by the client to the server, containing the necessary information for the server to execute the command.
Response Packet: Sent by the server to the client.
- Successful Response Packet: Indicates a successful operation and provides the response to the request.
- Error Response Packet: Indicates an error occurred during execution of the request and contains error information.
Event Packet: Sent by the server to signify that an event has occurred, including its appropriate values.

Request Packet

The structure of the Request packet is outlined as follows:

Name	Type	Description
Packet Type	Integer	An integer specifying the packet type. For request, it is 0
Message Id	Integer	An integer representing the chosen arbitrary message Id for the request
OpCode	Integer	An integer representing the opcode of the command for the request
Parameter	Object	An optional object containing parameters needed to execute the command

For most supported commands within the system, a parameter object is provided. This object contains essential information necessary for the execution of the command. It typically consists of key-value pairs, where each key represents a specific parameter required by the command, and its corresponding value provides the necessary data or configuration. If any of the packet type, message ID, or opcode is missing or of an invalid type, a response indicating a parse error (-32700) will be provided.

Below is an example illustrating a request packet for lookup command:

[
  0,                            # Request Packet
  65,                           # Message Id
  3,                            # Lookup OpCode
  {                             # Lookup Object
    0: "Group 1.Data Point 1"   # Primary Key of the Xentara Element
  }
]

Success Response Packet

The structure of the successful response packet is outlined as follows:

Name	Type	Description
Packet Type	Integer	An integer specifying the packet type. For successful response, it is 1
Message Id	Integer	An integer representing the message Id provided in the request
Response	Item	An optional item containing the response of the request

The type of item received in the response depends upon each specific command. Therefore, when interacting with the server, it's important to check the command-specific documentation to determine the structure and content of the response item.

Below is an example illustrating a success response packet of requested lookup command:

[
  1,                                       # Packet Type - Success Response
  65,                                      # Message Id
  37(h'E3EE10714D884BA18E5D0F1E4CE25EE8')  # Xentara Element UUID
]

Error Response Packet

The structure of the error response packet is outlined as follows:

Name	Type	Description
Packet Type	Integer	An integer specifying the packet type. For error response, it is 2
Message Id	Integer	An integer representing the message Id provided in the request, or null if there is an error in parsing message id
Error	Object	An error object containing the error code and error message of the occurred error

The error object follows a structure similar to the JSON-RPC 2.0 specification. This object comprises of a code and a message enclosed within the same structure. The error code of type integer is identified by the key 0, while the error message of type string is identified by the key 1.

Below is an example illustrating a Parse Error (-32700):

[
  2,                                # Packet Type - Error Response
  null,                             # Message Id
  {
    0: -32700,                      # Error Code
    1: "payload not well formed"    # Error Message
  }
]

The error message might change based on the specific error encountered, but the error code remains consistent. For example, if the attribute identifier in the read request is invalid, an error object will be returned with the Invalid Parameter (-32602), along with an error message such as "invalid attribute identifier".

[
  2,                                       # Packet Type - Error Response
  65,                                      # Message Id
  {                                        
    0: -32602,                             # Error Code
    1: "invalid attribute identifier"      # Error Message
  }
]

Event Packet

The structure of the event packet is outlined as follows:

Name	Type	Description
Packet Type	Integer	An integer specifying the packet type. For events, it is 8
Event Type	Integer	An integer specifying the event type.
Parameter	Object	An object that includes a timestamp, the Xentara element UUID, and the attribute values (see below).

Event Parameters

The parameters for data change event is outlined as follows:

ID	Name	Description
0	time_stamp	A timestamp of the event, formatted according to the format for time stamp.
1	element_uuid	A UUID specifying the UUID of the Xentara element according to the format for UUIDs.
2	attribute_values	An object containing key-value pairs of attribute identifiers or attribute UUIDs and their corresponding values. The successful values are enclosed with tag 121 (alternative 0), while error values are enclosed with tag 122 (alternative 1).

Below is an example illustrating a data change event:

[
  8,                                             # Packet Type - Event
  0,                                             # Event Type - Data Change
  {
    0: 1(4([-9, 179998887776665])),              # Time Stamp
    1: 37(h'E6343C8939AA40A49583606D2B00E389'),  # Xentara Element UUID
    2: {                                         # Data Change Object
         11: 121(25.98),                         # Attribute Id and it's value
         9: 121(0)                                    
       }
  }
]

Table of Contents

Request Packet

Success Response Packet

Error Response Packet

Event Packet

Event Parameters