Communication protocol - PR-21-S

PR-21 Series User Guide

Document code
IM-EN-PR21S
Revision
C
Language
English
Product
PR-21-S
Document type
User guide

The communication protocol is based on UDP/IP to port 50023. It is a client/server protocol, where the DTR is the server and therefore only sends information when the client (your computer) requests it. The server answers requests within 5 s (5000 ms), usually the response time is below 100 ms.

Request format

The client to server communication (the requests sent from your computer to the DTR), is in binary format. The request packets contain the following binary data (all integers are in the network order, MSB first):

  • 32-bit integer: packet number
  • 32-bit integer: request ID
  • (any): request data (depends on the request)
  • (any): fill-in data
The maximum size of the message is 1472 octets (bytes).

The packet number is echoed back by the DTR, but not processed in any way. The packet numbers do not have to be sequential, any 32-bit value is valid.

The request ID is a 32-bit value that identifies the requested function, for example sensor information. See Request-response pair specification for request IDs.

The request data consists of 0 to 1464 octets of additional data associated with the request.

The fill-in data can be used to increase the number of octets in a message. Any number of NULL characters (0x00) may be added to the end of the request as long as the total size of the message does not exceed the maximum of 1472 octets. This may be useful, for example, if the client implementation uses fixed-length packets.

Response format

The response data sent by the DTR is in ASCII format. With the exception of the packet number, the data is human-readable. The data structure consists of:

  • Packet number (32-bit integer)
  • Zero or more lines of ASCII (text) keys and values associated with these keys (for example temperature key and process temperature in Celsius)

The packet number is echoed back without change. The client (software on computer) can use the packet number to check the response against the packet number of the request.

The message text consists of lines of text, each line a single key (of one word) and its value or values. The values are separated from the key by an equal sign ( = ) and multiple values are separated by a comma. White space (space or tabulator) is allowed anywhere except within a single value or key name.

If the response consists of a character string, it is enclosed in double quotes ("). For example all these are valid message text lines:

ok temp=23.45
headhum = 13.32
LEDcnt = 8341
ChemCurve = 1.234, 3.21, 0.00, 4.37, 1.11, 0.00002, 2.1345
StatusMessage = "Normal Operation"
All the key identifiers are case-insensitive, see Request-response pair specification. However, it is recommended that they are written as in this specification.

The server (DTR) may send the response keys in any order. It will send the mandatory keys of the specific request, but it may omit any other keys. The server may also send keys that are not specified in this document, but the client (computer) may ignore them.

Mandatory keys are marked with an asterisk in Request-response pair specification.

Request and response errors

When the server (DTR) detects an error, it responds with an error message. For more information see Error message specification. Error messages can be caused by an unknown request, or inability to collect data for the mandatory keys of a response.