How it Works
Ocean Optics
Loading...
NeoFox Engineering Note
User Manual
30 pgs405.9 Kb2
Table of contents
Loading...

Ocean Optics NeoFox Engineering Note User Manual

Engineering Note
Topic: NeoFox Communic a t ion Interfaces Products Affected: NeoFox Date Issued: 04/18/2011 Updated: November 2012

Description

Topics addressed in this Engineering Note include the following:
Topic Page
Description 1 Architecture Overview 2 NeoFox Serial Interface 3 DLL Inter fa c e 5 NeoFox DLL Function Reference 7 Driver Interface and Har dware Interf ace 11 NeoFox Variable Reference Table 11 Additional Firmware Controls in FW Version 2.25 24
013-20000-010-04-201211 1
NeoFox Communication Interfaces
NeoFox Viewer
NeoFox DLL
USB Driver
UART-USB Bridge
Software
Hardware
Microprocessor
The NeoFox Viewer is a graphical user interface that
The NeoFox DLL accepts high level function calls from
The USB driver is provided by FTDI - the manufacturer of The UART-USB bridge chip accepts USB commands from
The microprocessor communicates via a serial
DLL Interface
Driver Interface
Hardware Interface
Serial Interface

Architecture Overview

Variables and Parameters

All communication with the NeoFox centers upon either reading or setting variables on the hardware device. For instance, a developer may want to set the number of scans to average parameter or read the current sensor temperature value. In either case, there is a specific variable in the system’s memory which should be set or read. This document includes reference information for all public variables and also describes the various methods with which to interact with these variables.

Communication Architecture

The diagram below illustrates the various layers involved in NeoFox’s communication stack. Developers may want to interact with the device at any level. This document will provide enough information to do so by documenting the DLL interface and the serial interface. The two other interfaces – the driver interface and the hardware interface can be inferred through knowledge of the serial interface and developer information from FTDI.
allows end users to interact with the NeoFox
applications and abstracts the lower level drivers from programmers.
the UART-USB Bridge chip. It accepts function calls from the DLL and sends USB commands to the hardware.
a host computer and communicates with the microprocessor through a UART.
communications interface through its UART. It does not natively handle USB communications.
2 013-20000-010-04-201211
NeoFox Communica t ion Interf a ce s

NeoFox Serial Interface

Overview

The NeoFox serial protocol can be used for a number of purposes. Most significantly, future versions of the NeoFox hardware may have an RS232 serial output that will directly expose this protocol. Additionally, knowledge of the serial protocol can be used in conjunction with knowledge of the FTDI USB protocol to create custom USB drivers for the NeoFox, which are necessary for embedded host applications or non-windows based PC host applications.
From the perspective of the embedded microcontroller, the serial protocol essentially has only two functions: to read and write parameters and variables.

Settings

Setting Value
Baud Rate: 750,000 baud (default) Stop Bits: 1 Parity: None Flow Control: None Byte Order: Little endian Integer Size: 4 bytes Float Size: 4 bytes
The following settings represent the default settings of the UART when used in through the USB interface. The default settings for the UART when it is communicating through the RS232 interface are listed in RS232 Default
Settings.

Writing Data to the NeoFox

All of the writable parameters on the NeoFox fall into two categories: floating point types and integer types (including char, short, etc). Regardless of type, all parameters accept the same command frame structure to set their values. This structure is documented below. There are two fields in this command that require detailed explanation.
First, bytes 8 through 11 hold the ParamType field. This field contains a code that indicates which parameter is to be set by the command. A list of parameters and codes is available at the end of this document.
The ParamValue field (bytes 12 through 15) contains the actual value that is to be set by the command. This field does not have an explicit type listed in the table below. The type is determined by the type of the parameter value (also listed in the table at the end of this document). If the parameter is an integer type (short, char, long, etc), then these four bytes are interpreted as a 4 byte signed integer (little endian) and then cast to the actual type. If the parameter is a floating point type, then the four bytes are explicitly interpreted as a little endian floating point value.
013-20000-010-04-201211 3
NeoFox Communication Interfaces
Addr Type Name Description
0 uchar Stx Start of transmission character. Set to 0x03. 1 uchar PacketType Set to 0xC8 2 ushort FrameSize Set to 20 (0x14). 4 ulong CmdNumber Reserved. Set to 0. 8 ulong ParamType Type code for the parameter that is to be set. 12 n/a ParamValue Value for the parameter to be set. Can be a float or integer type. 16 uchar Reserved1 Reserved. Set to 0. 17 uchar Reserved2 Reserved. Set to 0. 18 uchar Checksum Set to the aggregate sum of all previous bytes modulus 256. 19 uchar Eof End of transmission character. Set to 0x04.

Reading Data from the NeoFox

The NeoFox streams a “data dump” of all its publicly exposed parameters after each sample. This occurs approximately once every tenth of a second. The location of each particular value within this stream is given in the table at the end of this document. The data stream is structured as follows.
Addr Type Name Description
0 uchar Stx Start of transmission character. Set to 0x03. 1 uchar PacketType Set to 0xDC 2 ushort FrameSize Set to 5036 (0x13AC) 4 uchar FrameCount Number of frames uploaded since the device powered on. This
rolls over after 255. It can be used to determine whether any frames have been missed.
5 uchar ProtocolRev The value of the Data Copy Type parameter. The structure is a
"type 1" structure (the def ault communication structure for NeoFox). Therefore, this value will be 0x01. See Data Copy Type
for more information on alternative data structures. 6 uchar Reserved1 Reserved. Do not depend on this value. 7 uchar Reserved2 Reserved. Do not depend on this value. 8
… 927
928 … 2979
n/a Data Parameters are stored in this region of the structure. See the table
at the end of this document for variable-specific documentation
and addresses.
struct SensorBlue Blue sensor waveform raw data. This contains the data that can
be seen in the “sensor waveform window” in the NeoFox Viewer.
2980 struct SensorRed Red sensor waveform raw data. This contains the data that can
4 013-20000-010-04-201211
NeoFox Communica t ion Interf a ce s
Addr Type Name Description
… 5031
5032 uchar Reserved3 Reserved. Do not depend on this value. 5033 uchar Reserved4 Reserved. Do not depend on this value. 5034 uchar Checksum Set to the aggregate sum of all previous bytes modulus 256. 5035 uchar Eof End of transmission character. Set to 0x04
be seen in the “sensor waveform window” in the NeoFox Viewer.

DLL Interface

The NeoFox DLL can be used by developers without the need to understand the USB or serial interface layers. The DLL itself abstracts these layers and provides an interface of high-level function calls. This DLL interfac e can be easily used with almost any programming language: Labview, C, C++, Visual Basic, Java, or even VBA for excel.
The DLL enables the user to perform any of the following four common actions: It allows users to open a connection to a NeoFox device, read values from the device, set parameters on the device, and close the connection to the device. The functions which enable these actions are described below.

Opening a Connection

There are two steps to creating a connection to a NeoFox. First, the user must call the DevicePerformDiscovery function, which internally creates an index list of all unopened NeoFox units that are connected to the computer. In addition to creating an indexed list, this function will also inform the user of the number of unopened NeoFox units that are connected.
Once the list has been created, the user must call the DeviceOpenChannel for each NeoFox un it for which a connection is to be established. The DeviceOpenChannel function takes an index as its parameter and it opens the particular NeoFox unit that corresponds to that index in the list that was generated by the DevicePerformDiscovery function. However, since DevicePerformDiscovery does not provide any information about the units that it discovers, the indices are essentially arbitrary and in order to select any particular NeoFox unit, the user will basically need to open all available NeoFox units and they query them each individually to determine its name. It can then close connections to the units that it does not need.

Reading Data from the NeoFox

Reading variables from the device is accomplished through either of two functions: DeviceGetParameter or DeviceGetParameterFloat. The determination of which function to use is based on the type of the variable that is to be read. Use DeviceGetParameterFloat for floating point type parameters and DeviceGetParameter for any other type of parameter.
It is important to note that the NeoFox is a discrete sampling system. New samples are only refreshed from the hardware device approximately once every tenth of a second, and operating system latency may result in even lower throughput. Therefore, developers may find it useful to poll the Millisecond Count variable to evaluate whether or not information in the DLL has been refreshed since the last time that information was read.
013-20000-010-04-201211 5
NeoFox Communication Interfaces

Writing Data to the NeoFox

Writing variables to the device is similarly accomplished through either of two functions: DeviceSetParameter or DeviceSetParameterFloat. Again, the determination of which function to use will be based on the type of the data that is to be sent.

Closing a Connection

When interaction with the device is complete, the connection should be closed by calling the DeviceClose function.

Application Maintenance

Before calling any functions from the DLL, applications should make a call to the DLL’s ApplicationStartup function, which will begin a new thread in which it can run its background processes. Before exiting, applications should call ApplicationShutdown to terminate this thread.

Sample Code

A sample C++ program (MS Visual C++) that demonstrates how to use the device is available from the Ocean
Optics Sensors website.

Remarks

There is one additional issue that some early developers have faced which bears some discussion. The szText parameters, which are defined as type LPTSTR, are implemented as type char* in the DLL. There is a known issue with the Microsoft Visual C++ compiler in which sometimes the compiler has trouble casting between LPTSTR and char* types. One simple way to resolve this issue is to not include windows.h, which defines LPTSTR, and use a typedef instead (typedef char* LPTSTR). Another, more advisable, way to correct this issue is to set the project properties to use a multi-byte character set. This can be done by adjusting the “character set” project property at Properties  Configuration Properties General.
It is also important to note that the maximum number of NeoFox units that can be supported by the DLL at one time is 8.
6 013-20000-010-04-201211
NeoFox Communica t ion Interf a ce s

NeoFox DLL Function Reference

int DeviceSetParameter(int hDevice, int ParamType, int dValue)
Description
Sets an integer parameter on the NeoFox.
Parameters
int hDevice Handle to an open NeoFox device. int ParamType Unique code for the parameter which is to be set. int dValue Value to be written to the parameter.
Return Value
Number of bytes written to the hardware device in order to issue the set parameter command message. This includes the command packet overhead in addition to the ParamType code and the dValue payload. At the time of this writing, the size of this transaction is 20 bytes.
Remarks
Although the dValue parameter is a 4 byte integer, this function should also be used to set short and char type parameters as well.
int DeviceSetParameterFloat(int hDevice, int ParamType, float fValue)
Description
Sets a floating point parameter on the NeoFox.
Parameters
int hDevice Handle to an open NeoFox device. int ParamType Unique code for the parameter which is to be set. float fValue Value to be written to the parameter.
Return Value
Number of bytes written to the hardware device in order to issue the set parameter command message. This includes the command packet overhead in addition to the ParamType code and the dValue payload. At the time of this writing, the size of this transaction is 20 bytes.
int DeviceGetParameter(int hDevice, int ParamType, LPTSTR szText)
Description
Reads an integer type parameter from the NeoFox device.
013-20000-010-04-201211 7
NeoFox Communication Interfaces
Parameters
int hDevice Handle to an open NeoFox device int ParamType Unique code for the parameter which is to be read. LPTSTR szText A character buffer (char*). Be sure to pass this parameter a pointer
to an initialized buffer of at least 50 bytes.
Return Value
The function returns an int that represents the value that has been queried from the device. In some cases, it will also populate the szText buffer with a textual representation of the integer value.
Remarks
Although this function returns a 4 byte integer value, it should also be used to query the values of short and char type parameters. It is also important to note that although the function will sometimes populate the szText buffer, users are advised not to use this value unless the szText parameter is explicitly discussed in a particular variable’s information (from the variable table at the end of this document).
float DeviceGetParameterFloat(int hDevice, int ParamType, LPTSTR szText)
Description
Reads a floating point type parameter from the NeoFox device.
Parameters
int hDevice Handle to an open NeoFox device int ParamType Unique code for the parameter which is to be read. LPTSTR szText A character buffer (char*). Be sure to pass this parameter a pointer to an
initialized buffer of at least 50 bytes.
Return Value
The function returns a float that represents the value that has been queried from the device. In some cases, it will also populate the szText buffer with a textual representation of the integer value.
Remarks
Although this function returns a 4 byte integer value, it should also be used to query the values of short and char type parameters. It is also important to note that although the function will sometimes populate the szText buffer, users are advised not to depend on this information, which is not explicitly supported.
int ApplicationStartup(int hInstance)
Description
This function starts a thread for the DLL.
Parameters
int hInstance Pass NULL to this parameter.
8 013-20000-010-04-201211
NeoFox Communica t ion Interf a ce s
Return Value
This function always returns a value of 1.
Remarks
This function should be called at the beginning of any user program, before any other DLL functions are called.
int DevicePerformDiscovery(int vendorID, int productID, int ShowGUI)
Description
This function instructs the DLL to create an indexed list of all NeoFox devices that are connected to the system via USB but have not been opened already.
Parameters
int vendorID Vendor ID for the NeoFox product. The value is 0x2457. int productID Product ID for the NeoFox product. The value is 0x3000. int ShowGUI This parameter is reserved. Pass it a value of 0.
Return Value
This function returns the number of NeoFox devices that have been connected to the system via USB, but have not yet been opened with the DeviceOpenChannel function.
Remarks
This function must be called before a call to DeviceOpenChannel. It creates internally an indexed list of unopened NeoFox devices. The DeviceOpenChannel function will accept one of the indices from that list as a parameter to determine which device will be opened. It is important to note that once the DeviceOpenChannel function has been called to open a connection to any of the NeoFoxes in the list, the remaining indices rem ain valid until the next call to DevicePerformDiscovery. When DevicePerformDiscovery is called after DeviceOpenChannel has been called, it will re-index its list without including the newly opened NeoFox. Subsequent calls to DeviceO penCh anne l will need to use the new indice s as appr opri ate.
int DeviceOpenChannel(int Select, int SubChannel, int ShowGUI)
Description
Opens a NeoFox device and returns a handle to that device.
Parameters
int Select Index of the unopened NeoFox which is to be opened. See rem arks
for more information about this parameter. int SubChannel This parameter is reserved. Pass it a value of 0. int ShowGUI This parameter is reserved. Pass it a value of 0.
Return Value
Returns an integer handle to the NeoFox device that has been opened by the function. A value of 0 or -1 indicates that the function has failed to open the NeoFox device properly. Handle values begin at 10000 and increment upwards as new NeoFox devices are opened.
013-20000-010-04-201211 9
Loading...
+ 21 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use