« Close

Datasheets and User Guides

App Notes

Software & Driver

 

1 - Overview

Overview

The UD library is the Windows driver/library for the U3, U6 and UE9. UD is also referred to as LabJackUD and LJUD. For other LabJack devices, go to the Software page.

The general operation of the UD functions is as follows:

  • Open a LabJack U3, U6 or UE9.
  • Build a list of requests to perform (Add).
  • Execute the list (Go).
  • Read the result of each request (Get).

At the core, the UD driver only has 4 basic functions: Open, AddRequest, Go, and GetResult. Then with these few functions, there are many constants used to specify the desired actions. When programming in any language, it is recommended to have the header file handy, so that constants can be copied and pasted into the code.

The first type of constant is an IOType, which is always passed in the IOType parameter of a function call. One example of an IOType is the constant LJ_ioPUT_DAC, which is used to update the value of an analog output (DAC).

The second type of constant is a Channel Constant, also called a Special Channel. These constants are always passed in the Channel parameter of a function call. For the most part, these are used when a request is not specific to a particular channel, and go with the configuration IOTypes ( LJ_ioPUT_CONFIG or LJ_ioGET_CONFIG ). One example of a Special Channel is the constant LJ_chLOCALID, which is used to write or read the local ID of the device.

The third major type of constant used by the UD driver is a Value Constant. These constants are always passed in the Value parameter of a function call. One example of a Value Constant is the constant LJ_tmPWM8, which specifies a timer mode. This constant has a numeric value of 1, which could be passed instead, but using the constant LJ_tmPWM8 makes for programming code that is easier to read.

Following is pseudocode that performs various actions. First, a call is done to open the device. The primary work done with this call is finding the desired device and creating a handle that points to the device for further function calls. In addition, opening the device performs various configuration and initialization actions, such as reading the calibration constants from the device:


//Use the following line to open the first found LabJack U6
//over USB and get a handle to the device.
//The general form of the open function is:
//OpenLabJack (DeviceType, ConnectionType, Address, FirstFound, *Handle)

//Open the first found LabJack U6 over USB.
lngErrorcode = OpenLabJack (LJ_dtU6, LJ_ctUSB, "1", TRUE, &lngHandle);

Second, a list of requests is built in the UD driver using AddRequest calls. This does not involve any low-level communication with the device, and thus the execution time is relatively instantaneous:


//Request that DAC0 be set to 2.5 volts.
//The general form of the AddRequest function is:
//AddRequest (Handle, IOType, Channel, Value, x1, UserData)
lngErrorcode = AddRequest (lngHandle, LJ_ioPUT_DAC, 0, 2.50, 0, 0);

//Request a single-ended read from AIN3.
lngErrorcode = AddRequest (lngHandle, LJ_ioGET_AIN, 3, 0, 0, 0);

Third, the list of requests is processed and executed using a Go call. In this step, the driver determines which low-level commands must be executed to process all the requests, calls those low-level functions, and stores the results. This example consists of two requests, one analog input read and one analog output write, which can both be handled in a single low-level Feedback call (Section 5.2.5):


//Execute the requests.
lngErrorcode = GoOne (lngHandle);

Finally, GetResult calls are used to retrieve the results (errorcodes and values) that were stored by the driver during the Go call. This does not involve any low-level communication with the device, and thus the execution time is relatively instantaneous:


//Get the result of the DAC0 request just to check for an errorcode.
//The general form of the GetResult function is:
//GetResult (Handle, IOType, Channel, *Value)
lngErrorcode = GetResult (lngHandle, LJ_ioPUT_DAC, 0, 0);

//Get the AIN3 voltage.  We pass the address to dblValue and the
//voltage will be returned in that variable.
lngErrorcode = GetResult (lngHandle, LJ_ioGET_AIN, 3, &dblValue);

The AddRequest/Go/GetResult method is often the most efficient. As shown above, multiple requests can be executed with a single Go() or GoOne() call, and the driver might be able to optimize the requests into fewer low-level calls. The other option is to use the eGet or ePut functions which combine the AddRequest/Go/GetResult into one call. The above code would then look like (assuming the U6 is already open):


//Set DAC0 to 2.5 volts.
//The general form of the ePut function is:
//ePut (Handle, IOType, Channel, Value, x1)
lngErrorcode = ePut (lngHandle, LJ_ioPUT_DAC, 0, 2.50, 0);

//Read AIN3.
//The general form of the eGet function is:
//eGet (Handle, IOType, Channel, *Value, x1)
lngErrorcode = eGet (lngHandle, LJ_ioGET_AIN, 3, &dblValue, 0);

In the case of the U6, the first example using add/go/get handles both the DAC command and AIN read in a single low-level call, while in the second example using ePut/eGet two low-level commands are used. Examples in the following documentation will use both the add/go/get method and the ePut/eGet method, and they are generally interchangeable. See Section 4.3 for more pseudocode examples.

All the request and result functions always have 4 common parameters, and some of the functions have 2 extra parameters:

  • Handle – This is an input to all request/result functions that tells the function what LabJack it is talking to. The handle is obtained from the OpenLabJack function.
  • IOType – This is an input to all request/result functions that specifies what type of action is being done.
  • Channel – This is an input to all request/result functions that generally specifies which channel of I/O is being written/read, although with the config IOTypes special constants are passed for channel to specify what is being configured.
  • Value – This is an input or output to all request/result functions that is used to write or read the value for the item being operated on.
  • ×1 – This parameter is only used in some of the request/result functions, and is used when extra information is needed for certain IOTypes.
  • UserData – This parameter is only used in some of the request/result functions, and is data that is simply passed along with the request, and returned unmodified by the result. Can be used to store any sort of information with the request, to allow a generic parser to determine what should be done when the results are received.