I wish I had caught this earlier. But it is really strange to name a function in the library setAmplitude when it actually sets the range. The amplitude of a periodic function is of course half of the range.

It feels even stranger to use setAmplitude to set the range when combining it with setOffset.

For example, if you did

Tsunami.setAmplitude(1000);
Tsunami.setOffset(500);

I think you would not be crazy to expect you get a function that has an offset of 0.5V and an amplitude of 1V, instead of a function with an offset of 0.5V and an amplitude of 0.5V (which is what you really get).

Maybe it's too late to change, but I hope not. Because this will be confusing forever.

Maybe my instinct about this is wrong. I notice upon checking that commercial signal generators often have you set the peak to peak voltage, or the rms voltage. In that context I guess this could be right, but I feel like setVoltagePP might be better, along with setVoltageRMS or something like that.

I still think it will be confusing forever, but I guess it's already been confusing for a long time and maybe there's nothing to do but go along (like assuming that electricity flows from positive to negative).

This is a really excellent point. Perhaps we should institute a new function setVoltagePP, setPeakVoltage or setVoltageAmp and deprecate setAmplitude?

-Nick

I like setVoltagePP a bit better than setPeakVoltage. It's a little hard to decide, but I like that PP suggests very strongly 'peak to peak', whereas 'Peak' has the meaning of 'Peak Positive Voltage' in the measurePeakVoltage function.

Because of the ability to set an offset, the setPeakVoltage can't always mean the 'Peak Positive Voltage', or (even half that). I wouldn't choose setPeakVoltage unless I could make the functions match each other in meaning.

I imagine the setVoltageRMS to be just a helper function. It would call setVoltagePP with the argument scaled by 2*sqrt(2). Someone check my math on that, but I think that's right.

I think we don't ever set the amplitude of the square wave on the auxiliary port, so there's no danger in assuming a sine wave and using the scaling factor for that.

setVoltagePP would be a good name. setVoltageRMS would be useful but has two problems:

1. The peak voltage will be higher (except for square waves) and may exceed the voltage swing of the device
2. The relationship between peak voltage and RMS voltage depends on the crest factor of the waveform, which is unknown for arbitrary waveforms

setVoltagePP would be a good name. setVoltageRMS would be useful but has two problems:

1. The peak voltage will be higher (except for square waves) and may exceed the voltage swing of the device
2. The relationship between peak voltage and RMS voltage depends on the crest factor of the waveform, which is unknown for arbitrary waveforms

I guess I don't understand the importance of these two comments. It is true that the peak voltage will be higher than the RMS voltage. I haven't tested the library, but is it currently impossible to set the amplitude higher than the voltage swing of the device? If it fails now, then it would fail the same way.

And it seemed to me that the Tsunami only outputs sine waves (except on the auxilliary port). I looked to see if there was a function to switch to triangle or saw tooth and I didn't see one. Did I not look hard enough? If the only outputs are sines, then an RMS helper function wouldn't be ambiguous; it would just apply the scaling factor for a sine wave.

And it seemed to me that the Tsunami only outputs sine waves (except on the auxilliary port).

Ah, in that case a simple crest factor of 1.414 as you suggested would be fine, and the maximum RMS voltage would be 3.53V. I wasn't sure whether other waveforms were possible, and didn't want to exclude that possibility if so.

I think it would be 2.828, since peak to peak would be from -1.414*RMS to +1.414*RMS.

I think that illustrates the care we should take in naming stuff, since "peak" instinctively suggests peak positive.

And it seemed to me that the Tsunami only outputs sine waves (except on the auxilliary port).

According to the specifications on the Kickstarter campaign page:

Supports sine, triangle, and square wave signals.

Good call. This needs to be updated in the reference at: https://github.com/arachnidlabs/tsunami-arduino/wiki/Reference

We need the function modes documented:

Tsunami.setOutputMode(OUTPUT_MODE_TRIANGLE);

and

Tsunami.setOutputMode(OUTPUT_MODE_SINE);

In that case, I suppose I'd expect a helper function to use the scale appropriate to the current form.

What happens when you switch between output modes? I think my choice would be the peak-to-peak setting is retained (which means if you set the RMS value and then change output mode you can't expect the RMS value to stay constant).

Oops, not sure how I missed documenting those, sorry.

I'm out of the country (on holiday in Greece!) but I'll update them as soon as I get back home, next week.

-Nick

SetVoltagePP sounds good. I did try to look up what the "correct" definition of amplitude would be, but found only endless confusion - it really just depends on who do you ask... Somewhat amusingly, the confusion is illustrated right in the "FrequencyGenerator" example itself - measuring the Tsunami's own output you set an "amplitude" of 2.0 and measure an "amplitude" of 1.0 - which is made even worse by the fact that all you're actually measuring is the positive peak, making measurements on a signal with a DC offset quite meaningless - go on, change the offset in "FrequencyGenerator" and see your "amplitude" follow... I was actually wondering whether the Tsunami would be physically capable of measuring the negative peak as well, returning at least a peak-to-peak value - but judging by the schematics it's not going to happen (maybe in a future revision?). In this sense, the result of the measurement is rather misleading...

Unfortunately, no, it can't measure the negative peak with the current hardware - and there aren't really enough pins to add it. It can measure the mean voltage, though, which allows you to determine the true amplitude for signals with a DC offset.

That's interesting - sure, that would solve the problem; but I've seen no API function for mean measurement - how would one go about doing that?

The mean voltage can be measured on A3. I've added a bug to add an API function to measure and convert it.