NmxDLL Reference Guide > API (programming interface) > Sampling HighLevel (Application-specific Realtime Measurement) > NMX_Sampling_PrepareCustomTFT

Minimum DLL-Version: V1.1.0.11

This function is used to prepare a time-based sampling with optional triggering, arithmetic average filtering and "recording tail values after stop". Before starting the sampling, it must be prepared.

See also the HowTo-Guide.

Definition

NMX_STATUS NMX_Sampling_PrepareCustomTFT_1(

NMX_PHANDLE pHandle,

unsigned long ulSamplePeriod,

unsigned long ulFilteredPeriod,

unsigned long ulArrayLength,

unsigned long long udMaxSamples,

unsigned long ulNTailSamples,

unsigned long ulTriggerDigiInByteNo,

unsigned long ulTriggerDigiInBitNo,

unsigned long ulTriggerMode,

unsigned long ulTriggerPolarity);

Parameter

pHandle

Connection Handle.

ulSamplePeriod

Time period between two samples of the measurement hardware in µs, e.g. 1000 for 1ms.
This is the sampling period (-> measurement frequency) which will be used by the measurement system for acquiring the time-triggered measurement samples.
See the chapter "Sampling Speed with Irinos" for more information.

ulFilteredPeriod

Time period between two filtered samples provided to the application / measurement software in µs, e.g. 5000 for 5ms.
This value must be an integer multiple of ulSamplePeriod.
With this parameter, an average filter can be applied to the measurement samples. To disable the Filter, use the same values for ulSamplePeriod and ulFilteredPeriod.

Example: ulSamplePeriod is 1ms (=1000), then ulFilteredPeriod can be 1, 2, 3, 4, 5, ..., 10, ... 100ms.
If the SamplePeriod is 1ms and the FilteredPeriod is 5ms, then an average filter of the past 5 samples is used.

ulArrayLength

Data received from the device is internally buffered in the DLL. This parameter specifies the internal buffer length in samples.
Example: The filtered period is 1ms -> 1000Samples/s and the buffer shall contain a maximum of 10 seconds. Then ulDLLArrayLength = 10000;

udMaxSamples

Maximum number of samples, which shall be recorded.
Use 0 for endless sampling.
Example: The sampling speed is 1ms -> 1000Samples/s. Data shall be recorded for a maximum of 15 seconds. Then udMaxSamples = 15000;

ulNTailSamples

If this value is 0, then sampling will be stopped immediately, when the stop condition occurs.
If this value is >0, then ulNTailSamples will be sampled after the stop condition occurs.
The tail samples could for example be used for additional filtering.

ulTriggerDigiInByteNo

Number of the digital input byte, which contains the digital input information. Counting starts with 0.
This parameter is only relevant, if Triggering is used (ulTriggerMode > 0).

ulTriggerDigiInBitNo

Number of the bit in ulTriggerDigiInByteNo, which contains the digital input information. Counting starts with 0, maximum is 7.
This parameter is only relevant, if Triggering is used (ulTriggerMode > 0).

Example: A measurement system has 16 digital inputs, counted from 1 to 16. For input no 11, the parameters are:
ulTriggerDigiInByteNo = 1;
ulTriggerDigiInBitNo = 2;

ulTriggerMode

See general information about trigger mode.
The following modes are supported:
0 = Trigger disabled
1 = Edge
2 = Level
3 = Edge Start
4 = Level Once

ulTriggerPolarity

1 = falling edge / low active
2 = rising edge / high active
This parameter is only relevant, if Triggering is used (ulTriggerMode > 0).

Typical function call (C example)

Time-limited: NMX_Sampling_PrepareCustomTFT_1(pHandle, 1000, 5000, 10000, 10000, 4, 0, 0, 0, 0);

Endless: NMX_Sampling_PrepareCustomTFT_1(pHandle, 1000, 5000, 10000, 0, 0, 1, 4, 2);

Comments

•For short measurements of a few seconds, it is common practice using the same value for ulArrayLength and for udMaxSamples.

•The internal buffer is allocated in the heap memory of your application.

•The larger the DLL-internal buffer is, the larger the memory consumption.
For typical time-limited sampling, this is not a problem and the memory size will be between a few kBytes up to a few MBytes. This applies even to larger systems.
However, if you would use for example 256 measurement channels of 32 Bit size, and ulDLLArrayLength would be 100000, then 100 MBytes would be required. This may be too large for your heap memory.