Mistake in TriggerDetection function help text

[ebalci]

Hi,

I was planning to use the TriggerDetection function of Advanced Analysis Library.

The parameter names looked self explainin except Initialize. So I looked at its help.

This is the help for Initialize:

Specifies whether a trigger is detected on a rising edge or a falling edge.

Constant	Value	Description
SLOPE_FALLING_EDGE	0	Detects a trigger on the falling edge, or negative slope.
SLOPE_RISING_EDGE	1	Detects a trigger on the rising edge, or positive slope.

This did not make sense. So I checked others. The following is the help for Slope parameter:

Value above or below threshold through which the input signal must pass before a trigger level crossing is detected.

When initialize = 0 (SLOPE_FALLING_EDGE), the signal must pass above threshold + initialize before a trigger level crossing is detected.

When initialize = 1 (SLOPE_RISING_EDGE), the signal must pass below threshold – initialize before a trigger level crossing is detected.

and the Hysteresis parameter help:

History data for each channel that record whether the signal has passed below threshold + initialize or above threshold – initialize.

status[i] = 0, the signal of channel i has not passed below threshold + initialize or above threshold – initialize.

status[i] = 1, the signal of channel i has passed below threshold + initialize or above threshold – initialize.

Set this parameter to 0 for the first call in continuous mode.

It looks like something is mixed up here !? 

[StarSarina]

Ebalci,

The initialize function is an integer that will be either a 0 or a 1. You will set the initialize to a 0 or 1 based on when you want the triggering to be detected. For example if you had a square wave when it went from 0(low) to 1(high) and you would like the trigger to be detected then the initialize would be set to 1, which would be on the rising edge. However, if you would like the trigger to be detected when the square wave goes from 1 (high) to 0 (low) then you would set the initialize to 0, meaning that it would detect the trigger on the falling edge.

Please let me know if this makes sense.

[ebalci]

StarSarina,

I understand the "content" of the parameter help.

But I think the information is not at the right place.

Even if the Initialize parameter (despite its unintuitive name) determines the edge type (rising or falling) then why do we also have a Slope parameter?

It feels like the explanation given for Initialize belongs to Slope. Moreover, when I read the help for the Slope parameter, I feel like that explanation actually belongs to Hysteresis parameter.

I quote the help text below once again:

"... the signal must pass above threshold + initialize before a trigger level crossing is detected ..."

Summing threshold with initialize parameter is non-sense. Threshold is a physical value (like voltage, current, force, etc...) but initialize is a boolean. Why are we summing them?? I am almost sure that "initialize" must be replaced with "hysteresis"in the above sentence (also this holds for all similar sentences).

And I think the help text for hysteresis parameter actually belongs to Initialize.

The sentence below from the hysteresis help text is also confusing:

"... Set this parameter to 0 for the first call in continuous mode ..."

What is continuous mode?? This is the first occurence of a mode concept in the function help and it does not say anything else.

I hope I could make myself clear...

[StarSarina]

Ebalci,

I think that I understand your question and where the confusion exists, it is not that you don’t understand the content of the help but rather the naming is confusing. I wanted to try to make it clear by comparing it to a LabVIEW trigger detection VI.

CVI: http://zone.ni.com/reference/en-XX/help/370051V-01/cvi/libref/cvitriggerdetection/

LabVIEW: http://zone.ni.com/reference/en-XX/help/371361G-01/lvwave/basic_level_trigger_detect/

In LabVIEW the level is equivalent to the threshold value (CVI) and the trigger slope is equivalent to the Slope (CVI) and the hysteresis is the same. The initialize is the issue that seems not to compare in a 1 to 1 comparison.

I went ahead and made a simple code to determine the initialize to see if it was able to make a difference and it didn’t change the value of the index if the initialize was yes versus no. The following code is below:

#include <ansi_c.h>

#include <analysis.h>

double sine[256];

void main()

{

                double phase;

                ssize_t index;

                int trigger;

                SineWave (128, 1.0, 10.1, &phase, sine);

                TriggerDetection (sine, 128, 0.5, 0.1, SLOPE_FALLING_EDGE, ANALYSIS_TRUE, &index, &trigger);

                printf("Index: %d\nTrigger: %d", index, trigger);

                getchar();

}

Does the initialize make a difference in the code that you are using?

The initialize does seem to make a difference if you want to initialize the trigger detection again or you want to resume trigger detection as part of the previous input. The CVI initialize would correspond to the LabVIEW reset.

[ebalci]

I do not think you get me right.

This is not about a "naming confusion". The explanations in the function documentation are "wrong" and needs to be corrected.

My posts explain what is wrong and why. I advise you to discuss it with your developers.

I cannot tell you if I need Initialize or not because I still do not know what it does exactly!

I only have a "feeling" about it. Because its explanation actually belongs to Slope.

I could also get my code working, but everybody will have to live with the mistake until it is corrected.

[StarSarina]

Ebalci,

Ah okay, I did misunderstand your question. I will make sure that I pass this documentation issue on to the correct people so we are able to better document the functions in the future.

Thank you so much for this information.

[aghacker]

Even 6 months later I see the online help for TriggerDetection is not yet fixed. In case anyone else is confused, read the help for the function TriggerDetection2D since this one appears to be correct.

[riyas43]

Its been an year, still the help file remains confusing.

[StarSarina]

Hey All,

I wanted to let you know that it has been documented and it is pending a fix. We are aware of the issue and are working to resolve the documentation issue. At the moment, please look at the explanation above for any confusion. If you have any further questions, I would be happy to answer them.

Have a great day!

[ElectroLund]

It would appear that the documentation is now fixed.  I compared the 1D against the 2D and they appear identical now.

Also, the link above to the LabVIEW documentation on this topic is dead.  Here is the update.