Let UltimaSerial unleash the power of your Windaq Starter kit!

UltimaWaterfall

FFT1024

XChart

Lessons on how to use UltimaSerial

Downloads

info@ultimaserial.com

If you are starting a new project, upgrade to the UltimaSerial (Version 3) now!  UltimaSerial (version 3) supports USB-based DI-148, DI-158, DI-710 & DI-715B

This page covers all the properties and methods of UltimaSerial.

Properties: AcquisitionMode, AvailableData, CommPort, ChannelCount,  Device, EventLevel, Key, MaskOutDigitalBits, PreTriggerLength, PostTriggerLength, SampleRate, SerialNumber,  SquareWaveOutput,  TriggerChannel, TriggerStatus, TriggerLevel, PChannel, PGain, MatchSerialNumber, RawData,

Methods:  AnalogInput, DigitalInput, GetData, GetDataEx, GetDataFrame, GetDataFrameEx, MapErrorMessage, ResetCounter, SetLimitLines, Start, Stop, TransitionalCounter, DigitalOutput, DACOutput, GetDescription, SetDescription, SetDIODir, ScanDevice, Data2Volt, GetDataPt

Events: DriverError, GapInDataStream, LimitLine, NewData, Trigger

In the VB sample programs installed along with UltimaSerial control, most of  these properties, methods and events are addressed.

Properties: 

CommPort: Specify the COMM port (serial port) you want to use or find out which one you are currently using. (Serial port 1 is the default.)

Syntax:     Ultimaserial1.CommPort=variable (Writes serial port)
                variable=Ultimaserial1.CommPort (Reads serial port)
Variable:    Integer

COM port supported by UltimaSerial:

0 = USB (Ultimaserial rev 3)
1 = COM 1:
2 = COM 2:
3 = COM 3:
4 = COM 4:

....... Valid COM port number goes up to 64

To use multiple serial devices on multiple COM port, you need to insert multiple UltimaSerial control in your VB form. 

If multiple USB-based device like DI-148/158/71x exist, consider paring SerialNumber and  MatchSerialNumber to select a device

Device: Specify the Dataq serial data acquisition device model number you are going to use or find out which one you are currently using. (DI-194 is the default.)

Syntax:     Ultimaserial1.Device=variable (Writes Device Model Number)
                variable=Ultimaserial1.Device (Reads Device Model Number)
Variable:     Integer

Devices Supported  by UltimaSerial:

194 = DI-194 (8 bit device) & DI-194RS (10 bit device)
190 = DI-190
195 = DI-195B
154 = DI-154RS
150 = DI-150RS
151 = DI-151RS

USB-based devices:
148 = DI-148U & DI-148UP (10 bit resolution)
158 = DI-158U (12 bit resolution)
710 = DI-710U (14 bit resolution)
715 = DI-715BU (14 bit resolution)
718 = DI-718B (14-bit resolution)

ChannelCount: Lets you write the number of channels you want to be enabled or read the number of channels that are currently enabled. The default is 1 channel. If you enter a number that is higher than the number of possible channels for the data acquisition instrument you are using, ChannelCount will be reset to 1. (For example, since a DI-194 has 4 possible channels, and you request 10 channels, only one channel will be enabled.)

Syntax:     Ultimaserial1.ChannelCount=variable (Writes the number of channels to be enabled)
                variable=Ultimaserial1.ChannelCount (Reads the number of currently enabled channels)

Variable: Integer

For DI-194/154 Users only:

Normally, when you specify the channel count in UltimaSerial, like:
UltimaSerial.ChannelCount = 2, you enable channel 1 & 2.
or, UltimaSerial.ChannelCount = 4, you enable channel 1 & 2 & 3 & 4.

If you need to enable channels with different combination, you can use
UltimaSerial.ChannelCount = 100 + H
where H is the binary channel selector, i.e

H=1 enable channel 1
H=2 enable channel 2
H=3 enable channel 1 & 2
H=4 enable channel 3
H=5 enable channel 1 & 3
H=6 enable channel 2 & 3
H=7 enable channel 1 & 2 & 3
H=8 enable channel 4
H=9 enable channel 1 & 4
H=10 enable channel 2 & 4
H=11 enable channel 1 & 2 & 4
H=12 enable channel 3 & 4
H=13 enable channel 1 & 3 & 4
H=14 enable channel 2 & 3 & 4
H=15 enable channel 1 & 2 & 3 & 4

For DI-148/158/710/715 Users:

Please use PChannel, PGain property to change the channel and gain allocation table

SampleRate: The sample rate determines how fast the sampled data is reported per channel. When you specify a sample rate, an attempt is made to report data at that sample rate. When this is not possible, the data will be reported at the closest achievable rate to the sample rate you requested. The actual sample rate can then be read after you run Start method.

Syntax:     Ultimaserial.SampleRate=variable (Writes Sample Rate)
                Ultimaserial.Start 
                variable=Ultimaserial.SampleRate (Reads actual Sample Rate)
Variable: Double

The minimum throughput rate for 1xx is: 9.5E-06 Hz

AvailableData: This function reports how many available new data points have filled the buffer since the last time data was retrieved using GetData. 

Syntax:     variable=Ultimaserial1.AvailableData
Variable: Integer

EventLevel: The event NewData fires whenever a set number, or more, of new data points have been gathered. The EventLevel property allows you to specify when you want the NewData event fired. The specified integer must be between 0 and 32,767.  For example, if you specify "100" as the integer for EventLevel, the NewData event fire whenever 100 or more new data points have been gathered. Default value is 20.

A value of 0 will not  fire the NewData event. In this case, you should use Timer to pace the acquisition

Syntax:     Ultimaserial1.EventLevel=variable
Variable: Integer

Key: If you are using first version of DI-194, you need to have a "key" (a hex number) from DATAQ instruments to enable more than one channel. To enable multiple channels on DI-194, you must provide the Key before you Start the device. Recently, DATAQ drops the requirement of purchasing the key to enable multiple channels when you write your own programs (WinDaq still requires it), you can enter "ALICE13" in the key property to enable multiple channels for older version of DI-194.

Syntax:     Ultimaserial1.key=variable
Variable: String

The new version of DI-194, called DI-194RS (ship since Aug, 2001) does not require a key to enable all the channels.

The Key to enable multiple channel on the DI-194 is NOT the same as the Key to register UltimaSerial.

Key property also serves as the entry point for the superkey of site license

UltimaSerial.Key = "T1c2f345"     'The super key to enable UltimaSerial, assuming T1c2f345 is your superkey

UltimaSerial.Key = "ALICE13"    'The key to enable all four channels of DI-194.

UltimaSerial.Start

SerialNumber: If you are using an older version of DI-194, this property returns the serial number of the device after you Start the device successfully.  If multiple USB-based device like DI-148/158/71x are in use, consider paring SerialNumber and  MatchSerialNumber to select a device

Note: For DI-1xx, you must run Start method successfully before you will have a valid SerialNumber.

Variable: String

PreTriggerLength (integer) specifies the number of scans before the trigger point, 0 to 8000 scans can be specified (default: 100). The sum of PreTriggerLength and PostTriggerLength should not be higher than 8000.

Valid PreTriggerLength: 0 to 8000

Note: In AcquisitionMode  =3 & 4: 

PreTriggerLength should be zero

PostTriggerLength  (integer) specifies the number of scans after the trigger point, 1 to 8000 scans can be specified. 0 is for free-run after the trigger condition is met. (default: 100). The sum of PreTriggerLength and PostTriggerLength should not be higher than 8000.

Valid PostTriggerLength: 0 to 8000, where 0 means infinity.

Note: In AcquisitionMode  =3 & 4: 

PostTriggerLength should be zero if all data points above the level should be captured, or one if only the first one should be captured

AcquisitionMode  (integer) specifies the mode of acquisition, which includes unconditional, trigger on rising edge of an analog or digital input, trigger on falling edge of an analog or digital input, acquire when signal above a threshold level of an analog input, acquire when signal below a threshold level of an analog input, acquire when transitional counter reaches a predefined value, etc. A trigger event will be fired when the trigger condition is met.

Valid Acquisition Mode:

0 = NoCondition (default)
1 = OnEdgeLow2High
2 = OnEdgeHigh2Low
3 = WhenAboveLevel
4 = WhenBelowLevel

Note: In Mode 3 & 4: 

PreTriggerLength should be zero
PostTriggerLength should be zero if all data points above the level should be captured, or one if only the first one should be captured

SquareWaveOutput  (Boolean) When set, a pre-programmed square wave will be output on a pre-defined Digital channel (D2 for DI-194), which can be fed back to an analog channel for demo purpose. Sorry, but the pattern of the square wave cannot be controlled.

Note: With Ultimaserial (rev 3), you use change this property after Start is invoked to turn on/off the square wave, but it may create a garbage data point in the waveform.

TriggerChannel  (integer) specifies the member in PChannel list or a member in DigitalInput where the trigger condition takes place, which includes all available analog channels, digital channels and transitional event counters. 

Valid Trigger Channel:

 0 = PChannel1
1 =  PChannel2
2 =  PChannel3
3 =  PChannel4
...
15 = PChannel16

100 =  Digital0
101 =  Digital1
102 =  Digital2
...
107 = Digital7

The following use DigitalPort as Counter

200 =  L2HCounter0
201 =  L2HCounter1
202 =  L2HCounter2
...
207 = L2HCounter7

300 =  H2LCounter0
301 =  H2LCounter1
302 =  H2LCounter2
...
307 = H2LCounter7

TriggerStatus  (integer) returns the states of trigger mode

Possible returns:

0 = Filling PreTrigger Buffer
1 = Waiting for initial state
2 = Waiting for level crossing
3 = Filling PostTrigger Buffer
4 = TriggerDone 

TriggerLevel  (integer) specifies the threshold for trigger mode (default: 0)

Valid numbers:

Analog channels: -32768 to 32768
Digital channels: 0 and 1
EventCounters: Any positive numbers

MaskOutDigitalBits (Boolean) when set, the digital bits will be masked out from the data stream (default: false)

 

Methods:

Start: Start to acquire data.
Syntax: Ultimaserial1.start

Stop acquiring data.
Syntax:     Ultimaserial1.stop

GetData ensures waveform data continuity by passing a continuous stream of data to your program. GetData returns waveform data as a variant of two dimension 16-bit integer array. 

If you are using VB.NET, please also check this one out

Syntax:     Dim A as variant
                A=Ultimaserial1.GetData

To access the data returned by GetData, you can take a look at the following example:

Dim Channel1

Private Sub Command1_Click()

UltimaSerial.Device = 151
UltimaSerial.CommPort = 1
UltimaSerial.ChannelCount = 2

UltimaSerial.SampleRate = 240
UltimaSerial.EventLevel = 2
UltimaSerial.Start

End Sub

Private Sub UltimaSerial_NewData(ByVal Count As Integer)

V = UltimaSerial.GetData() 'The data will be returned to V as a variant 

cn = UBound(V, 1)    'cn  = number of channel -1
pts = UBound(V, 2)    'pts = number of data -1

ReDim Channel1(0, 0 To pts ) As Integer   
'create an array to accept channel1

For i = 0 To pts 
    Channel1(0, i) = V(0, i)    'Extract channel 1 from V
Next

DQChart1.Chart (Channel1)    'Plot channel 1

End Sub

                

GetDataEx: As long as you don't ask for more than what UltimaSerial has in its buffer,  GetDataEx, ensures waveform data continuity by passing a continuous stream of data to your program. GetDataEx returns waveform data to an integer array as binary data. 

For most C programmers, a variant of integer array returned by GetData is not what they would like to handle. In this case, it will be much easier to use GetDataEx to place the data directly to a pre-defined integer array.

Syntax:     Dim A(1000) as integer
                Ultimaserial1.GetDataEx A(0), Count

where A(0) is a pointer to the 16-bit integer array, A. Count, an integer, is the number of data points, not scans, that you are requesting (32,767 maximum). 

The data will be aligned with the first channel. If you enable more than one channel, you will have to sort out the data for each channel yourself. The order of data points is: Ch1, Ch2, Ch1, Ch2, Ch1, Ch2, .... (assuming you enable two channels)

Note: 
1) Make sure you have enough data available before you copy it.
2) Make sure the array allocated is large enough to store all the data requested.

To convert the AD Readings to voltage (assuming you are using -10 to +10V input range, which is the default for most of the serial devices):

For 14-bit devices like DI-71x :

Voltage = (FullScale/Gain) * (ADReading >>2)/8192

where >>2 means to shift the data to the right for 2 bits. In VB, you can use INT (ADReading/4)

For DI-158 :

Voltage = (FullScale/Gain) * (ADReading >>4)/2048

where >>4 means to shift the data to the right for 4 bits. In VB, you can use INT (ADReading/16)

For 12-bit devices like DI-195B, DI-190, DI-150RS, DI-151, DI-154RS and DI-148:

Voltage = 10 * (ADReading >>4)/2048

where >>4 means to shift the data to the right for 4 bits. In VB, you can use INT (ADReading/16)

For 8-bit devices like DI-194:

Voltage = 10 * (ADReading >>8)/128

where >>8 means to shift the data to the right for 8 bits. In VB, you can use INT (ADReading/256)

For 10-bit devices like DI-194RS:

Voltage = 10 * (ADReading >>6)/512

where >>6 means to shift the data to the right for 6 bits. In VB, you can use INT (ADReading/64)

If you don't mind the little error caused by the integer calculation (up to 1 LSB of the ADC), you can always use:

Voltage = 10 * ADReading/32768

int DigitalInput (int channel) returns the states of digital channels. This method must be invoked after Start 

Valid channel: 0, 1 and 2.

DI-190 has two digital channels (0, 1) labeled as Dig 0 & Dig 1
DI-151RS has two digital channels (0, 1) labeled as Dig 0 & Dig 1
DI-154RS has two digital channels (0, 1) labeled as D0 &  D1 (D2 is always a square wave output)
DI-194 has three digital channels (0, 1, 2) labeled as D0,  D1 & D2
DI-195B has one digital channel (0) labeled as DIN

DI-148 has 4 digital channels (I/O)
DI-158 has 4 digital channels (I/O)
DI-710/715 has 8 digital channels (I/O)

If you try to access the digital channel(s) which is not available on the device, the result is meaningless

void TransitionCounter (int channel, int edge) returns the contents of transitional counters. 

Valid channel: 0, 1 and 2 for digital channel 0, 1 and 2
Valid edge: 0, 1, where 0 is low-to-high transition, 1 is high-to-low.

Using the digital channels of the device as a transitional counter, we have:

DI-190 has two  low-to-high transitional counters, and two high-to-low transitional counters
DI-151RS has two  low-to-high transitional counters, and two high-to-low transitional counters
DI-154RS has two  low-to-high transitional counters, and two high-to-low transitional counters
DI-194 has three low-to-high transitional counters, and three high-to-low transitional counters
DI-195B has one low-to-high transitional counters, and one high-to-low transitional counters
...

void ResetCounter (int channel, int edge) resets a specified transitional counter

Valid channel: 0, 1 and 2 for digital channel 0, 1 and 2
Valid edge: 0, 1, where 0 is low-to-high transition, 1 is high-to-low.

int AnalogInput  (int channel) returns the immediate reading from an enabled analog channel. You must use the ChannelCount property to enable the appropriate channel before you can invoke this method to get the readings from a specified channel. For example, to read from channel 0, 1, 2 and 3 of DI-194, you must have ChannelCount=4, also you must use the Key to enable multiple channel setting on the DI-194.

Valid channel: 0, 1, 2, 3 and more for UltimaSerial (version 2)

DI-190 has two analog channels (0, 1)
DI-150RS has two analog channels (0, 1)
DI-151RS has two analog channels (0, 1)
DI-154RS has four analog channels (0, 1, 2 and 3)
DI-194 has four analog channels (0, 1, 2 and 3)
DI-195B has two analog channel (0)

 

Max/Min Readings of the duration for UltimaSerial (version 2)

To catch the Maximum reading of a specified channel in the duration of the test (from the moment Start method is invoked to the moment of this method is invoked), add 1000 to the valid channel count mentioned above. i.e. 1000, 1001, 1002 and 1003

To catch the Minimum reading of a specified channel in the duration of the test (from the moment Start method is invoked to the moment of this method is invoked), add 2000 to the valid channel count mentioned above. i.e.  2000, 2001, 2002 and 2003 

To convert the AD Readings, check here.

variant GetDataFrame (int Count)  returns the most recent specified number of data frames as acquired by the control to a variant without affecting the continuity of the data stream. One frame is equivalent to one sample of each active channel. Click here to find out how to extract the data from the variant.

For example: UltimaSerial.GetDataFrame Count 

Variables: Count is an integer and defines the number of scans you are requesting. The maximum number of scans you can request is 8,000.

int GetDataFrameEx (short * Array, int Count) returns the most recent specified number of data frames as acquired by the control  to an integer array without affecting the continuity of the data stream. One frame is equivalent to one sample from every active channel. GetDataFrameEx returns binary data. If you enable more than one channel, you will have to sort out the data for each channel yourself. The order of data points is: Ch1, Ch2, Ch1, Ch2, Ch1, Ch2, .... (assuming you enable two channels)

For example:: UltimaSerial.GetDataFrameEx A(0),Count

A(0) is a pointer to the 16-bit integer array, A. Count, an integer, is the number of data points, not scans, that you are requesting (30,000 maximum). The data will be aligned with the first channel.

To convert the AD Readings, check here.

MapErrorMessage  (int errorcode) as string maps the error code returned by the control to a brief description of the problem. Here is the map if you want to do it yourself:

-1: Invalid device name
-2: Invalid COMM port
-3: Invalid channel count. Original channel count is unmodified
-4: Sample out of possible range
-5: Invalid channel count. Channel count is changed to 1
-10: Trigger Level too high, and will be changed to 32767
-11: Trigger Level too low, and will be changed to -32768
-12: This trigger mode does not use pre- nor post- trigger length
-13: Unsupported trigger mode
-14: Unsupported trigger channel
-15: This channel does not support alarm setting
-998: Failed to communicate to the device
-999: Failed to send key to DI-194
-1000: Invalid key to DI-194! Channel Count changes to 1
-3000: Failed to create monitoring process, please poll the data from VB Timer function
-800: COM port is not available

SetLimitLine (int type, int threshold) specifies the type of monitoring and threshold to be used in LimitLine operation. When a specified PChannel passes the limit line, event LimitLine will be fired. Each channel can have two limit lines, one for high limit and one for low limit. This method must be invoked before Start

Valid type:

0 = PChannel1Below
1 = PChannel1Above
2 = PChannel2Below
3 = PChannel2Above
4 = PChannel3Below
5 = PChannel3Above
6 = PChannel4Below
7 = PChannel4Above
...

GetDataPt Instead of using GetData and GetDataEx, you can use GetDataPt to retrieve one data point at a time. This function is provided for primitive programming language that doesn't support variant output or array transfer. 

PChannel(index) changes Programmable Channel allocation table, or scanlist if you are using Dataq's term. This method must be invoked before Start

When Ultimaserial is first loaded, the channel allocation table is 1, 2, 3,...16 (all single-ended), all with gain of 1.

If you need to alter it to 1 SE, 3DIFF, 2SE, 4DIFF, invoke the following codes

PChannel(0)=CH01_SE

PChannel(1)=DIFF_03

PChannel(2)=CH02_SE

PChannel(3)=DIFF_04

PGain(index) changes Programmable Gain table. This method must be invoked before Start

PGain goes in parallel with PChannel.

If we have the following codes:

PGain(0)=0

PGain(1)=1

PGain(2)=2

PGain(3)=3

along with the above codes for PChannel, we assign the lowest gain for 1SE, second lowest gain for 3DIFF, 3rd gain for 2SE, and 4th gain for 4DIFF

DigitalOutput (data) outputs via Digital output port if the direction of DIO port is set up to be output. This method must be invoked after Start

Port	Bit	0	1
D7	7	low	high
D6	6	low	high
D5	5	low	high
D4	4	low	high
D3	3	low	high
D2	2	low	high
D1	1	low	high
D0	0	low	high

dio = 0

If DO7isHigh Then diodir = diodir + 128
If DO6isHigh Then diodir = diodir + 64
If DO5isHigh Then diodir = diodir + 32
If DO4isHigh Then diodir = diodir + 16
If DO3isHigh Then diodir = diodir + 8
If DO2isHigh Then diodir = diodir + 4
If DO1isHigh Then diodir = diodir + 2
If DO0isHigh Then diodir = diodir + 1

UltimaSerial.DigitalOutput dio

 

DACOutput (data)   outputs via the DAC on DI-148/158. This method must be invoked after Start

0000 = 0.0 volt
7FF8 = 1.2 volt

The DACs are not calibrated.

SetDIODir(data) sets the direction of DIO port for DI-148/158/710/715. This method must be invoked after Start

Port	Bit	0	1
D7	7	output	input
D6	6	output	input
D5	5	output	input
D4	4	output	input
D3	3	output	input
D2	2	output	input
D1	1	output	input
D0	0	output	input

diodir = 0

If DIO7isInput Then diodir = diodir + 128
If DIO6isInput Then diodir = diodir + 64
If DIO5isInput Then diodir = diodir + 32
If DIO4isInput Then diodir = diodir + 16
If DIO3isInput Then diodir = diodir + 8
If DIO2isInput Then diodir = diodir + 4
If DIO1isInput Then diodir = diodir + 2
If DIO0isInput Then diodir = diodir + 1

UltimaSerial.SetDIODir diodir

GetDescription gets the Description of the USB-based device, to change the description, use SetDescription. This method must be invoked after Start

ScanDevice (index) finds the available DI-148/158/710/715 devices connected to your PC. This feature is useful when multiple 710/158/148s are connected to the same PC. 

To initiate the seach, set index =0. If a device is found, the return value is a positive number, which is the device's virtual COMM port +1, then you can use this number as the index number to search for the next device. If none is found, the return value is -1:

i = 0
UltimaSerial.Device=710
Do Until i = -1
    i = UltimaSerial.ScanDevice(i)
    If i <> -1 Then
        s = Format$(UltimaSerial.Device) + " " + UltimaSerial.SerialNumber
        List1.AddItem (s)
    End If
Loop

MatchSerialNumber if this is set. A pre-assigned Serialnumber must be matched before the device is open. This feature is useful when multiple 710/158/148s are connected to the same PC

RawData if set, internal digital calibration on DI-148/158/71x will not be applied.

Data2Volt converts binary data according  to the equation

 Events:

GapInDataStream indicates a gap is detected in the data stream

Trigger (Timer as string) returns the closest moment of  triggering the monitoring process can determine.

LimitLine (Time as string, Channel as integer) indicates a pre-specified LimitLine is passed.

DriverError: Fired when an error is detected by the control. 

NewData: Fired when the number of new data points are equal to or higher than what is specified in the property of EventLevel.

 

Last update: 01/30/08

Copyright: 2000-2005  www.UltimaSerial.com