Add six new waves (#9)

- add **float sinusDiode(float t)**
- add **float sinusRectified(float t)**
- add **float trapezium1(float t)** with duty cycle.
- add **float trapezium2(float t)** with duty cycle.
- add **float heartBeat(float t)**
- add **float freeWave(float t, int16_t arr, int size)** arbitrary wave generator.
- update **functionGeneratorPerformance.ino**
- add examples for **freeWave()**
- fix Arduino-lint.yml (long library name error)
- update readme.md
- minor edits

Author: RobTillaart

.github/workflows/arduino-lint.yml

@@ -10,4 +10,4 @@ jobs:
       - uses: arduino/arduino-lint-action@v1
         with:
           library-manager: update
-          compliance: strict
+          # compliance: strict

CHANGELOG.md

@@ -6,10 +6,24 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
-## [0.2.5] - 2023-11-02
+## [0.3.0] - 2024-07-05
+- add **float sinusDiode(float t)**
+- add **float sinusRectified(float t)**
+- add **float trapezium1(float t)** with duty cycle.
+- add **float trapezium2(float t)** with duty cycle.
+- add **float heartBeat(float t)**
+- add **float freeWave(float t, int16_t arr, int size)** arbitrary wave generator.
+- update **functionGeneratorPerformance.ino**
+- add examples for **freeWave()**
+- fix Arduino-lint.yml (long library name error)
 - update readme.md
-- update keywords.txt (align)
+- minor edits
+
+----
 
+## [0.2.6] - 2023-11-02
+- update readme.md
+- update keywords.txt (align)
 
 ## [0.2.5] - 2023-03-25
 - add **setDutyCycle()**, **getDutyCycle()**

README.md

@@ -27,10 +27,15 @@ In practice the generator is useful for low frequencies,
 Note: this class generates float values, performance wise this can be optimized,
 to achieve higher speeds at cost of accuracy / precision.
 
+As always, feedback and ideas are welcome.
 
-#### Performance
 
-Indication of what performance can be expected (based upon 0.2.1 version).  
+### Performance
+
+You always have to verify your own performance measurements to see if 
+your requirements are met by this library.
+
+**Indication** of what performance can be expected (based upon 0.2.1 version).  
 Note that the values need to be transported to a DAC or serial port too.  
 Numbers based on performance example, for one single signal.
 
@@ -72,55 +77,67 @@ have become slightly slower.
 |  Arduino UNO  |  16 MHz   |  square    |   57        |  1000 Hz   |
 |  Arduino UNO  |  16 MHz   |  random_DC |   68        |   500 Hz   |
 
+See **functionGeneratorPerformance.ino**
+
 
-#### Accuracy
+### Accuracy
 
 If the time parameter **t** grows large, the internal math may have rounding 
 problems after some time. This can and will affect the quality of the output.
+It is advised to reset **t** after a number (e.g. 100) full periods
 
 Needs further investigations.
 
+### Related
+
+- https://github.com/RobTillaart/AD9833 hardware waveform generator.
+- https://github.com/RobTillaart/AD985X hardware waveform generator.
+- https://github.com/RobTillaart/functionGenerator software waveform generator.
+- https://pages.mtu.edu/~suits/notefreqs.html frequency table for notes.
+
 
 ## Interface
 
 ```cpp
 #include "functionGenerator.h"
 ```
 
-#### Constructor
+### Constructor
 
 - **funcgen(float period = 1.0, float amplitude = 1.0, float phase = 0.0, float yShift = 0.0)**
 All parameters (except duty cycle) can be set in the constructor but also later in configuration.
 Default dutyCycle is 50%.
 
 
-#### Configuration
+### Configuration
 
-- **void  setPeriod(float period = 1.0)** set the period of the wave in seconds. 
+- **void setPeriod(float period = 1.0)** set the period of the wave in seconds.
+This is the inverse of the frequency.
 - **float getPeriod()** returns the set period.
-- **void  setFrequency(float frequency = 1.0)** set the frequency of the wave in Hertz (1/s).
+- **void setFrequency(float frequency = 1.0)** set the frequency of the wave in Hertz (1/s).
+This is the inverse of the period.
 - **float getFrequency()** returns the set frequency in Hertz.
-- **void  setAmplitude(float amplitude = 1.0)** sets the amplitude of the wave.
+- **void setAmplitude(float amplitude = 1.0)** sets the amplitude of the wave.
 The range is from **-amplitude** to **+amplitude**.
 Setting the amplitude to 0 gives effectively a zero signal.
 Setting the amplitude to a negative value effectively inverts the signal.
 - **float getAmplitude()** returns the set amplitude.
-- **void  setPhase(float phase = 0.0)** shifts the phase of the wave. 
+- **void setPhase(float phase = 0.0)** shifts the phase of the wave. 
 Will only be noticeable when compared with other waves.
 Phase is also known as the X- or horizontal shift.
 - **float getPhase()** returns the set phase.
-- **void  setYShift(float yShift = 0.0)** sets an Y-shift or vertical offset in amplitude.
+- **void setYShift(float yShift = 0.0)** sets an Y-shift or vertical offset in amplitude.
 This allows to set e.g. the zero level.
 - **float getYShift()** returns the set Y-shift.
-- **void  setDutyCycle(float percentage = 100)** sets the duty cycle of the signal.
+- **void setDutyCycle(float percentage = 100)** sets the duty cycle of the signal.
 Experimental, not all waveforms have a duty cycle or interpret it differently, see below.
 Duty cycle must be between 0 and 100% and will be clipped otherwise.
-- **float getDutyCycle()** returns the set duty cycle.
-- **void  setRandomSeed(uint32_t a, uint32_t b = 314159265)** sets the initial seeds for the
+- **float getDutyCycle()** returns the set (clipped) duty cycle.
+- **void setRandomSeed(uint32_t a, uint32_t b = 314159265)** sets the initial seeds for the
 (Marsaglia) random number generator. The first is mandatory, the second is optional.
 
 
-#### Wave forms
+### Wave forms
 
 The variable t == time in seconds.
 
@@ -129,11 +146,12 @@ The variable t == time in seconds.
   - mode == 1 ==> sawtooth |\\. Effectively equals inverting the amplitude.
 - **float triangle(float t)** triangle form, duty cycle default 50%. 
 - **float square(float t)** square wave with duty cycle default 50%.
-- **float sinus(float t)** sinus wave, has no duty cycle. 
+- **float sinus(float t)** sinus wave, has no duty cycle.
 - **float stair(float t, uint16_t steps = 8, uint8_t mode = 0)** defaults to 8 steps up.
   - mode = 0 ==> steps up
   - mode = 1 ==> steps down. Effectively equals inverting the amplitude.
-- **float random()** random noise generation.
+- **float random()** random noise generation between 0 and amplitude.
+Uses Marsaglia random generator.
 - **float line()** constant voltage line. 
 Height depends on the YShift and amplitude.
 - **float zero()** constant zero.
@@ -142,7 +160,29 @@ The functions **line()** and **zero()** can be used to drive a constant voltage
 from a DAC and can be used to calibrate the generator / DAC combination.
 
 
-#### Duty Cycle 
+Experimental 0.2.7
+
+- **float sinusDiode(float t)** sinus wave, only positive pulses.  
+(better name welcome).
+- **float sinusRectified(float t)** sinus wave, with "abs(negative pulses)".  
+(better name welcome).
+- **float trapezium1(float t)** trapezium wave.
+DutyCycle changes steepness of the falling and rising edge.
+The wave changes from a square wave, via trapezium to a triangle wave.
+- **float trapezium2(float t)** trapezium wave.
+DutyCycle changes duration HIGH vs LOW, wave stays trapezium like.
+Note at 50% DC the two trapezium functions are identical.
+- **float heartBeat(float t)** simplified heartbeat wave.
+To get a regular BPM heartbeat one should **setFrequency(BPM/60.0)** e.g 72/60 = 1.2.
+- **float freeWave(float t, int16_t arr, int16_t N)** define a free wave form.
+It uses an array of **N+1** values, dividing a full period in **N** equidistant steps.
+The last value should equal the first value to have a smooth transition.
+The values of the array normally vary between -10000 and +10000 to manage
+the set the relative amplitude in small steps. 
+These are scaled back to -1.0 to +1.0 times the amplitude.
+
+
+### Duty Cycle 
 
 Since 0.2.5 the library has **experimental** support for duty cycle.
 The meaning of duty cycle differs per wave form.
@@ -160,7 +200,16 @@ with respect to previous value.
 Implemented as a weighed average between new and previous value.
 Made a separate function as handling the duty cycle slows performance substantial.
 Initial starts at zero and can be adjusted with **YShift()**.
+- **float trapezium1(float t)** The duty cycle changes the steepness of the rising
+and falling edges. This changes the form from square wave to trapezium to triangle.
+The length of the HIGH LOW level go from 0 to half a period.
+- **float trapezium2(float t)** The duty cycle determines the length of the HIGH level,
+which is 0 for 0% DC and half a period for 100% DC. 
+The rising and falling edges stay same.
+- **float heartBeat(float t)** The duty cycle determines the part of the period
+that the signal ~zero.
 
+### No duty cycle
 
 The other functions need to be investigated what duty cycle means.
 Current ideas that are **NOT** implemented:
@@ -171,41 +220,52 @@ Think of it as the halve of the triangle wave.
 - **stair()** like sawtooth??
 - **line()** has no period so does not make sense (yet).
 - **zero()** has no period so does not make sense (yet).
-
-Feedback and ideas are welcome.
-
+- **float sinusDiode(float t)**
+- **float sinusRectified(float t)**
+- **float freeWave(float t, int16_t arr, int16_t N)**
 
 ## Future
 
-
 #### Must
 
-- documentation
-  - quality of signals - after substantial time t
-  - max freq per wave form etc.
-    Should this be in the library?
-
+- improve documentation
+  - reorganize
+  - section per function might be better.
 
 #### Should
 
 - smart reseed needed for random().
-- initialize random generator with compile time.
-
+  - initialize random generator with compile file + date + time.
+  - use function values for seed bits.
+- stand-alone functions in separate .h
+- clean up code
 
 #### Could
 
-- waves
-  - trapezium wave (could merge square and triangle and sawtooth)
-  - white noise, pink noise etc.
-- RC function curve.
+- ASDR wave 
+  - https://en.wikipedia.org/wiki/Envelope_(music)
+  - **float ADSR(float t, float A, float D, float S, float R)** 
+  - ADSR are percentages, A + D + R < 1.0
+  - S = % of amplitude.
 - external clock to synchronize two or more software function generators.
-- stand-alone functions in separate .h
 - check for synergy with https://github.com/RobTillaart/AD985X
 - investigate performance.
   - algorithms for DAC specific gains e.g. 10-12-16 bit.
   - improve performance sin() lookup table.
   - add float variable for ```_perDC = _period * _dutyCycle```
   - do we need **freq4** ? not since DC.
+- heartBeat
+  - small noise/variation parameter on amplitude and frequency.
+  - reduce footprint ==> wrapper around freeWave()
+- waves
+  - white noise, pink noise (better done with hardware)
+  - min() + max() => return +-amplitude + yshift?
+  - RC function curve.
+  - Gamma curve.
+- create a function table? with what?
+- create an example program to sample an arbitrary wave form
+  - output in the right format.
+  - slow sampling vs real time.
 
 
 #### Examples
@@ -228,6 +288,8 @@ Feedback and ideas are welcome.
   - **float stairDC()**
 - Bezier curve? (too complex)
 - record a signal and play back  ==> separate class
+- document max frequency per wave form etc.
+  Should this be in the library? differs per board.
 
 
 ## Support

examples/funcGenFreeWavePlotter/funcGenFreeWavePlotter.ino

@@ -0,0 +1,95 @@
+//
+//    FILE: funcGenFreeWavePlotter.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: demo function generators
+//     URL: https://github.com/RobTillaart/FunctionGenerator
+//
+//  use a Serial plotter to show the data
+
+
+#include "functionGenerator.h"
+
+funcgen gen;
+
+//  sin(t).
+int16_t arr_sin[101] =
+{
+  0,  627,  1253,  1873,  2486,  3090,
+  3681,  4257,  4817,  5358,  5877,
+  6374,  6845,  7289,  7705,  8090,
+  8443,  8763,  9048,  9297,  9510,
+  9685,  9822,  9921,  9980,  10000,
+  9980,  9921,  9822,  9685,  9510,
+  9297,  9048,  8763,  8443,  8090,
+  7705,  7289,  6845,  6374,  5877,
+  5358,  4817,  4257,  3681,  3090,
+  2486,  1873,  1253,  627,  0,
+  -627,  -1253,  -1873,  -2486,  -3090,
+  -3681,  -4257,  -4817,  -5358,  -5877,
+  -6374,  -6845,  -7289,  -7705,  -8090,
+  -8443,  -8763,  -9048,  -9297,  -9510,
+  -9685,  -9822,  -9921,  -9980,  -10000,
+  -9980,  -9921,  -9822,  -9685,  -9510,
+  -9297,  -9048,  -8763,  -8443,  -8090,
+  -7705,  -7289,  -6845,  -6374,  -5877,
+  -5358,  -4817,  -4257,  -3681,  -3090,
+  -2486,  -1873,  -1253,  -627,  0,
+};
+
+
+//  sin(t) + 0.25 * sin(5t)
+int16_t arr_two_sin[101] =
+{
+  0, 1120, 2178, 3117, 3891, 4472,
+  4847, 5024, 5029, 4904, 4702,
+  4481, 4300, 4213, 4261, 4472,
+  4852, 5392, 6063, 6820, 7608,
+  8366, 9033, 9554, 9886, 10000,
+  9886, 9554, 9033, 8366, 7608,
+  6820, 6063, 5392, 4852, 4472,
+  4261, 4213, 4300, 4481, 4702,
+  4904, 5029, 5024, 4847, 4472,
+  3891, 3117, 2178, 1120, 0,
+  -1120, -2178, -3117, -3891, -4472,
+  -4847, -5024, -5029, -4904, -4702,
+  -4481, -4300, -4213, -4261, -4472,
+  -4852, -5392, -6063, -6820, -7608,
+  -8366, -9033, -9554, -9886, -10000,
+  -9886, -9554, -9033, -8366, -7608,
+  -6820, -6063, -5392, -4852, -4472,
+  -4261, -4213, -4300, -4481, -4702,
+  -4904, -5029, -5024, -4847, -4472,
+  -3891, -3117, -2178, -1120, 0,
+};
+
+
+
+void setup()
+{
+  Serial.begin(115200);
+  //  Serial.println(__FILE__);
+  //  Serial.print("FUNCTIONGENERATOR_LIB_VERSION: ");
+  //  Serial.println(FUNCTIONGENERATOR_LIB_VERSION);
+  //  Serial.println();
+
+  gen.setAmplitude(80);
+  gen.setFrequency(0.5);
+  gen.setDutyCycle(50);
+}
+
+
+void loop()
+{
+  float t = millis() * 0.001;
+
+  Serial.print(80);
+  Serial.print("\t");
+  Serial.print(-80);
+  Serial.print("\t");
+  Serial.print(gen.freeWave(t, arr_two_sin, 100));
+  Serial.println();
+  delay(10);
+}
+
+
+//  -- END OF FILE --