4.7 - AIBurst [U12 Datasheet]
Reads a specified number of scans (up to 4096) at a specified scan rate (up to 8192 Hz) from 1,2, or 4 analog inputs. First, data is acquired and stored in the LabJack’s 4096 sample RAM buffer. Then, the data is transferred to the PC.
If the LED is enabled (ledOn>0), it will blink at about 4 Hz while waiting for a trigger, turn off during acquisition, blink rapidly while transferring data to the PC, and turn on when done.
The execution time of this function, in milliseconds, depends on transferMode and can be estimated with the below formulas. The actual number of samples collected and transferred by the LabJack is the smallest power of 2 from 64 to 4096 which is at least as big as numScans*numChannels. This is represented below as numSamplesActual.
Normal => 30+(1000*numSamplesActual/sampleRate)+(2.5*numSamplesActual)
Turbo => 30+(1000*numSamplesActual/sampleRate)+(0.4*numSamplesActual)
Declaration:
long AIBurst ( long *idnum, long demo, long stateIOin, long updateIO, long ledOn, long numChannels, long *channels, long *gains, float *scanRate, long disableCal, long triggerIO, long triggerState, long numScans, long timeout, float (*voltages)[4], long *stateIOout, long *overVoltage, long transferMode )
Parameter Description:
Returns: LabJack errorcodes or 0 for no error.
Inputs:
*idnum – Local ID, serial number, or -1 for first found.
demo – Send 0 for normal operation, >0 for demo mode. Demo mode allows this function to be called without a LabJack.
stateIOin – Output states for IO0-IO3. Has no effect if IO are configured as inputs, so a different function must be used to configure as output.
updateIO – If >0, state values will be written. Otherwise, just a read is performed.
ledOn – If >0, the LabJack LED is turned on.
numChannels – Number of analog input channels to read (1,2, or 4).
*channels – Pointer to an array of channel commands with at least numChannels elements. Each channel command is 0-7 for single-ended, or 8-11 for differential.
*gains – Pointer to an array of gain commands with at least numChannels elements. Gain commands are 0=1, 1=2, …, 7=20. This amplification is only available for differential channels.
*scanRate – Scans acquired per second. A scan is a reading from every channel (1,2, or 4). The sample rate (scanRate * numChannels) must be between 400 and 8192.
disableCal – If >0, voltages returned will be raw readings that are not corrected using calibration constants.
triggerIO – The IO port to trigger on (0=none, 1=IO0, or 2=IO1).
triggerState – If >0, the acquisition will be triggered when the selected IO port reads high.
numScans – Number of scans which will be returned. Minimum is 1. Maximum numSamples is 4096, where numSamples is numScans * numChannels.
timeout – This function will return immediately with a timeout error if it does not receive a scan within this number of seconds. Timeouts of 3 seconds or less are generally recommended to keep the U12 in turbo transfer mode.
*voltages – Pointer to a 4096 by 4 array where voltage readings are returned. Send filled with zeros.
*stateIOout – Pointer to a 4096 element array where IO states are returned. Send filled with zeros.
transferMode – 0=auto,1=normal, 2=turbo. If auto, turbo mode is used unless timeout is >= 4, or numScans/scanRate >=4.
Outputs:
*idnum – Returns the local ID or –1 if no LabJack is found.
*scanRate – Returns the actual scan rate, which due to clock resolution is not always exactly the same as the desired scan rate.
*voltages – Pointer to a 4096 by 4 array where voltage readings are returned. Unused locations are filled with 9999.
*stateIOout – Pointer to a 4096 element array where IO states are returned. Unused locations are filled with 9999.
*overVoltage – If >0, an overvoltage has been detected on at least one sample of one of the selected analog inputs.
ActiveX Function Differences:
The “channels” and “gains” arrays are replaced with “channelsPacked” and “gainsPacked”. The OCX has a function “FourPack” (4.39) which will convert 4 elements to a packed value. The packed value is determined as: element[0] + (element[1] * 2^8) + (element[2] * 2^16) + (element[3] * 2^24).
The parameters “demo”, “ledOn”, “disableCal”, “transferMode”, “updateIO”, and “stateIOin”, are replaced by an “optionBits” parameter. Call the OCX function “BuildOptionBits” (4.38) to determine this parameter.
The “voltages” and “stateIOout” arrays are represented as strings. Floating point data is returned as 13 characters per number (XXXX.XXXXXXXX) and integers are returned as 10 characters per number (XXXXXXXXXX). Zeros are used for padding where necessary. The total number of bytes in the “voltages” string is 13*numSamples. The total number of bytes in the “stateIOout” string is 10*numScans. Note that to avoid a memory leak, these strings should be emptied (set to “”) after each call to AIBurstX.
Declaration (ActiveX):
long AIBurstX ( long FAR* idnum, long numChannels, long channelsPacked, long gainsPacked, float FAR* scanRate, long triggerIO, long triggerState, long numScans, long timeout, BSTR FAR* voltages, BSTR FAR* stateIOout, long FAR* overVoltage, long optionBits)