Ocean Optics Ventana - Manual (Page 11)

Ventana Data Sheet
891-00000-200-05-201305 11
Offset
(Bytes)
Field Size
(Bytes)
Valid Values Notes
payload is used, this field is ignored.
40 Bytes
Remaining 4 0x00000000
–
0xFFFFFFFF Includes the payload, if any, plus the checksum and
footer. This is included for RS-232, such that a
constant-sized header could be read (including this
field) followed by another read for the remainder of the
message. Payload length must be computed as this
field minus the checksum and footer length. Ventana
may reject any message too long for it to process
internally and return a NACK.
The header can be represented as a C struct as follows (assuming that the int type is 32 bits long):
struct ooi_binary_protocol_header {
unsigned char start_bytes[2]; /* = { 0xC1, 0xC0 } */
unsigned short protocol_version; /* = 0x1000 */
unsigned short flags;
unsigned short errno;
unsigned int message_type;
unsigned int regarding;
unsigned char reserved[6];
unsigned char checksum_type;
unsigned char immediate_data_length;
unsigned char immediate_data[16];
unsigned int bytes_remaining;
};
Payload
After the standard header, a payload may be provided. The payload contains data required by the given
message type. The format of the data within the payload depends on the message type. Note that a
payload is not required if operands will fit in the Immediate Data field of the header. The length of the
payload must be computed from the Bytes Remaining field in the header, given that the checksum and
footer are of a constant length:
Payload length = Bytes remaining – 20
The Ventana may populate the Immediate Data field or the Payload as appropriate for the length of the
data being returned, regardless of the message type. Host programs decoding this protocol should
always be capable of checking both areas in any response.
Checksum
A 16-byte block must appear after the payload (if any) to contain checksum data. This block is
required even if no checksum is used (according to the Checksum Type field) or if the checksum does
not require the full 16 bytes. The unused parts of the block are for padding to ensure the message
length is consistent. This protocol does not support checksums longer than 16 bytes, e.g. SHA, but the
intent of the checksum is to detect bit errors, not to prevent tampering or to provide cryptographic
assurance. The checksum may not be necessary for USB but may be useful for buses that do not
provide data integrity guarantees, such as RS-232.