Ocean Optics Ventana - Manual (Page 8)

Ventana Data Sheet
8 891-00000-200-05-201305
Instruction Set
Protocol Design
The binary command protocol for the Ventana Spectrometer has the following design characteristics:
• Provides information so that the host does not need to know the state of the device to read the
message.
• Contains a distinct header and footer to fully bracket transfers.
• Provides an abstract interface to the device. All timing is represented in standard units rather
than clock divisors. A specific outcome is achieved via a single mechanism.
• Stores calibration information (wavelength, nonlinearity coefficients, etc.) in distinct
commands rather than EEPROM slots.
Ventana Command Protocol
There are two types of messages in this protocol:
• "commands" that do not return any information
• "queries" that cause the device to return information
When developing a device driver that will communicate with the Ventana, the fact that some messages
generate a response (including a status indication) and others do not can cause design problems. The
simplest approach to creating a driver for this protocol is to have all message types generate a reply.
This allows a single message read to be performed after every message write, and if the response
indicates an error, then the driver can recover immediately rather than finding the error later when it
expects a response to some new query.
The "flags" field in the message header (starting at byte offset 4) has an "acknowledgment (ACK)
requested" bit (bit 2). If this bit is set to 1 for every "command", and left at 0 for every "query", then
all communications with the Ventana will become predictable read/write transactions. The immediate
reply allows the host driver to avoid changing its state until it has received confirmation that the last
operation succeeded or failed. This makes driver design much easier than the alternative.
It is recommended that an Ventana protocol driver implement two functions:
• send_command_to_device() which takes a message type and an optional payload, and returns
a simple pass/fail result based on the ACK or NACK flag in the response. This should set the
"ACK requested" bit in every message it emits;
• query_device() which takes a message type and optional payload and returns a payload (e.g. a
byte array) which can be NULL if the response was a NACK. This must not set the "ACK
requested" bit because to do so would generate a spurious ACK in addition to the expected
response.
By using these two functions to encapsulate all transfers to the Ventana, the programming model is
kept very simple.
Message Layout
All multi-byte fields are little-endian (LSB first). Each message in the binary protocol is laid out as
follows:
1. A 44-byte header