 |
 |
 |
 |
 |
 |
|
||||||
|
This document describes how to communicate with USB to LV series (LV-15 and LV-30) controllers and also to the TEC controller. These controllers are accessed using a USB standard protocol, the so-called “HID” (Human Interface Device). A programmer's library provides convenient C-language access under Microsoft Windows.
VueMetrix products that are not listed here use a virtual serial port emulation as the USB communication method. The information in this document does not apply to those controller types.
Readers of this document should own one or more of the following controllers:
The developer's kit consists of two files:
Links to download these files are at the bottom of this page.
This DLL has been compiled using the Borland Version 5.5 C++ compiler, and is expected to be fully compatible with other development environments. VueMetrix will make the source code of this library available on an as-needed basis; please contact the factory for details.
When an HID device sends a string of bytes to the host PC, Windows appends the incoming bytes to a buffer. Each device-to-host transmission is treated as a separate packet; the number of packets that can be held in the buffer is system-dependent. The function vm_hid_read will fetch the oldest data packet from this buffer. VueMetrix controllers send data only in response to a command, and every command results in a reply. In order to keep multiple replies from accumulating in the buffer, follow each call to vm_hid_write with a matching call to vm_hid_read.
The VueMetrix HID protocol prefixes each command by a one-byte message identifier. The controller prefixes the same message identifier to its reply. By matching the identifiers, client programs can insure that commands and replies are always associated correctly.
For example, to set an LV controller to 10 amps, you might send:
“xi 10.0>”
The leading 'x' is an arbitrary byte and will be ignored by the controller. The controller will send the reply:
“xOK<CR><LF>”
The leading 'x' is just the echo of the 'x' you sent. To ask for the current you might send:
“1i?>”
The controller will reply:
“110.0<CR><LF>”
The first '1' is not part of the reply, it is just the echo of the '1' you sent.
Many of the functions in the hidfuncs library return an integer error code. Zero always indicates success. An enum in hidfuncs.h list the other values, which are described in more detail here.
| Symbol | Value (int) | Meaning |
| VM_HID_NO_ERROR | 0 | Function succeeded |
| VM_HID_SYSTEM_ERROR | 1 | Windows reported an error. The details can be retrieved by standard API calls (e.g., GetLastError) |
| VM_HID_MEMORY_ALLOCATION_ERROR | 2 | The DLL failed to allocate needed memory |
| VM_HID_INVALID_HANDLE | 3 | An attempt was made to use an invalid handle |
| VM_HID_WRITE_FAILED | 4 | Data could not be sent to the controller within 1 second |
| VM_HID_READ_FAILED | 5 | Not used |
| VM_HID_ARGUMENT_RANGE_ERROR | 6 | A function argument was out of range |
| VM_HID_READ_TIMEOUT | 7 | No data was received from the controller in 1 second |
In the USB standard, all strings returned as part of the generic protocol are required to be Unicode. In the device information structure the two strings are Unicode, and are declared wchar_t in hidfuncs.h. Command strings to the controller and the responses, the syntax of which is defined by VueMetrix and not the USB standard, are simple ASCII strings and are declared char in hidfuncs.h.
In the following section the functions appear in the order they would normally be called in an application. For reference, here is a list of the function names in alphabetical order:
int WINAPI vm_hid_scan(void)
This must be called before any other function in the library. It performs a scan of all the HID devices on the computer. It builds a table containing information about devices that are manufactured by VueMetrix. For each VueMetrix device on the system, this method builds a device_info structure containing its handle, a string describing its product type, and a string containing its serial number.
Returns:
int WINAPI vm_hid_count(void)
Returns the number of VueMetrix devices found during the last call to vm_hid_scan.
int WINAPI vm_hid_get_info(int n,PDEV_INFO *pdi)
Gets information about a single device.
Arguments:
device_info *p; // Alternative form: PDEV_INFO p; vm_hid_get_info(0,&p);
In the event that only one controller is present on the system it is not necessary to use this mechanism. The function vm_hid_get_handle returns a handle to a device without requiring inspection of the contents of the device_info structure.
Returns:
HANDLE WINAPI vm_hid_get_device_handle(int n)
Gets a handle to device n, where n is less than the value returned by vm_hid_count.
Returns:
int WINAPI vm_hid_write(HANDLE h, const char *message, int msglen)
Sends a message string to a controller whose handle was previously obtained.
Arguments:
Returns:
int WINAPI vm_hid_read(HANDLE h,char *pbuffer, int *plen)
Retrieves a reply from the controller.
Arguments:
Returns:
int WINAPI vm_hid_close(HANDLE h)
h is a valid Windows handle previously obtained. After this method is called no communications can be performed with this handle.
Returns:
int WINAPI vm_hid_close_all(void)
Closes all the open handles at once. No communications can be performed with any previously obtained handle. Note that Windows will automatically close any handles owned by the application when it is closed, so this function does not need to be called on exit.
Returns:
int WINAPI vm_hid_flush(HANDLE h,int input,int output)
Flushes any buffers associated with this handle. Calling this function should not normally be necessary. If input is nonzero the input buffer is flushed; if output is nonzero the output buffer is flushed. This method wraps a call to the Windows API function PurgeComm, the effect of which on HID devices is not clear from Microsoft's documentation.
Returns: