|
<< Click to Display Table of Contents >> Navigation: NmxDLL Reference Guide > API (programming interface) > Sampling HighLevel (Application-specific Realtime Measurement) > NMX_Sampling_PreparePosition_1 |
Minimum DLL-Version: V1.2.0.13
This function is used to prepare a position-triggered sampling. With position-triggered sampling, one measurement channel is used as a trigger source. In defined position distances, it triggers the other channels. This results in sets of measurement values (samples), which are recorded at equidistant position distances. Technically, position-triggered sampling uses an under
Before starting the sampling, it must be prepared.
See also the HowTo-Guide.
Definition
NMX_STATUS NMX_Sampling_PreparePosition_1(
NMX_PHANDLE pHandle,
unsigned long ulSamplePeriod,
unsigned long ulArrayLength,
unsigned long long udMaxSamples,
unsigned long ulTriggerChannelNumber,
double fdScale,
double fdStart,
double fdDistance);
Parameter
pHandle
ulSamplePeriod
Sampling-period for the underlying time-based sampling.
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. If you are unsure which value to use, 1000 (= 1ms) is a good value for starting your development.
ulArrayLength
Triggered data is internally buffered in the DLL. This parameter specifies the internal buffer length in samples.
Since position-triggered sampling is usually not endless, this parameter has typically the same value as udMaxSamples.
udMaxSamples
Maximum number of samples, which shall be recorded.
(0 can be used for endless sampling, even though this typically makes no sense with position-triggered sampling.)
Example: 360° shall be sampled with a position distance of 0.1°. This udMaxSamples = 360° / 0.1° = 3600.
To stop position triggering before udMaxSamples has been reached, use NMX_Sampling_Stop_1.
ulTriggerChannelNumber
Number of the measurement channel, which shall be used as source for the position trigger.
The first channel has the number 0.
Having a device with 24 measurement channels, these are numbered 0..23.
This measurement channel can be part of the sampled channels (this means it has been added to sampling via NMX_Sampling_AddChannel_1 or NMX_Sampling_AddChannelsAll_1). If this is not the case, it will be added automatically.
fdScale
Format: 64 Bit floating point number according to IEEE 754 (-> double).
Using the scale value, the position value of the Trigger Channel can be converted to a physical unit, e.g. from increments to degrees. It thereby sets the unit of the parameters fdStart and fdDistance.
If 1.0 is used, then the raw value from the trigger channel is used.
Example: An encoder with 720000 increments is used. The preferred resolution is 1°. Then fdScale = 720000 / 360 = 2000.
If a trigger distance (-> see fdDistance) of 0.1° is required, then fdDistance will now be 0.1 instead of 200.
fdStart
Format: 64 Bit floating point number according to IEEE 754 (-> double).
Start position for triggering: Triggering will not start, before this position has been crossed.
In case fdDistance ≥ 0, the start position must be crossed from a value below fdStart to a value equal/above fdStart.
In case fdDistance ≤ 0, the start position must be crossed from a value above fdStart to a value equal/below fdStart.
The unit of this parameter depends on fdScale.
fdDistance
Format: 64 Bit floating point number according to IEEE 754 (-> double).
Position distance between two trigger positions.
The unit of this parameter depends on fdScale.
Typical function call (C example)
NMX_Sampling_PreparePosition_1(pHandle, 1000, 10000, 10000, 8, 2000.0f, 0.0f, 0.1f);
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.