Develop (#7)

- add **setDutyCycle()**, **getDutyCycle()**
- implement duty cycle for square(), triangle() and random_DC()
- add **seedRandom(a, b)**
- add some optimizations
- move code from .h to .cpp
- update readme.md
- update GitHub actions
- update license 2023
- minor edits

Author: RobTillaart

CHANGELOG.md

@@ -6,12 +6,23 @@ 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-03-25
+- add **setDutyCycle()**, **getDutyCycle()**
+- implement duty cycle for square(), triangle() and random()
+- add **seedRandom(a, b)**
+- add some optimizations
+- move code from .h to .cpp
+- update readme.md
+- update GitHub actions
+- update license 2023
+- minor edits
+
+
 ## [0.2.4] - 2022-11-07
 - add changelog.md
 - add rp2040 to build-CI
 - update readme.md
 
-
 ## [0.2.3] - 2021-12-18
 - update library.json, license, minor edits
 

README.md

@@ -13,7 +13,7 @@ Arduino library to generate (numeric) wave forms for a DAC.
 
 ## Description
 
-This library presents a class for a function generator in software. 
+This library presents a class for a function generator in **software**. 
 It is typical used to control one or more DAC's.
 To maximize signal quality one has to apply all (or most) processor power 
 to calculate new values over and over again to get enough resolution. 
@@ -25,119 +25,203 @@ Note: this class generates float values, performance wise this can be optimized,
 to achieve higher speeds at cost of accuracy / precision.
 
 
-## Performance
+#### Performance
 
 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.
 
 
-| Processor    | Clock    | Waveform | usec/calls | max freq |
-|:-------------|---------:|:---------|-----------:|---------:|
-| Arduino UNO  | 16 MHz   | sawtooth |  62        |    60 Hz |
-| Arduino UNO  | 16 MHz   | triangle |  74        |    50 Hz |
-| Arduino UNO  | 16 MHz   | square   |  53        |  1000 Hz |
-| Arduino UNO  | 16 MHz   | sinus    |  164       |    25 Hz |
-| Arduino UNO  | 16 MHz   | stair    |  81        |    50 Hz |
-| Arduino UNO  | 16 MHz   | random   |  37        |  1000 Hz |
-|              |          |          |            |          |
-| ESP32        | 240 MHz  | sawtooth |  3.8       |  1000 Hz |
-| ESP32        | 240 MHz  | triangle |  3.9       |  1000 Hz |
-| ESP32        | 240 MHz  | square   |  2.8       |  1000 Hz |
-| ESP32        | 240 MHz  | sinus    |  13.6      |   250 Hz |
-| ESP32        | 240 MHz  | stair    |  4.8       |   800 Hz |
-| ESP32        | 240 MHz  | random   |  1.3       |  1000 Hz |
-
-
-- assumption minimal 250 samples per period to get a smooth signal.
-  if a rougher signal is OK, higher frequencies are possible.
+|  Processor    |  Clock    |  Waveform  |  usec/call  |  max freq  | max values/period |
+|:--------------|----------:|:-----------|------------:|-----------:|--------:|
+|  Arduino UNO  |  16 MHz   |  sawtooth  |   62        |    60 Hz   |   268   |
+|  Arduino UNO  |  16 MHz   |  triangle  |   74        |    50 Hz   |   270   |
+|  Arduino UNO  |  16 MHz   |  square    |   53        |  1000 Hz   |    19   |
+|  Arduino UNO  |  16 MHz   |  sinus     |   164       |    25 Hz   |   152   |
+|  Arduino UNO  |  16 MHz   |  stair     |   81        |    50 Hz   |   246   |
+|  Arduino UNO  |  16 MHz   |  random    |   37        |  1000 Hz   |    27   |
+|  ESP32        |  240 MHz  |  sawtooth  |   3.8       |  1000 Hz   |   263   |
+|  ESP32        |  240 MHz  |  triangle  |   3.9       |  1000 Hz   |   256   |
+|  ESP32        |  240 MHz  |  square    |   2.8       |  1000 Hz   |   357   |
+|  ESP32        |  240 MHz  |  sinus     |   13.6      |   250 Hz   |   294   |
+|  ESP32        |  240 MHz  |  stair     |   4.8       |   800 Hz   |   260   |
+|  ESP32        |  240 MHz  |  random    |   1.3       |  1000 Hz   |   769   |
+
+
+- Assumption minimal around 250 samples per period to get a smooth signal.
+  If a rougher signal is OK, higher frequencies are possible.
+  For **square()** and **random()** less samples per period are often acceptable.
 - ESP32 can do more calculations however 1000 Hz seems to be a nice 
   upper limit for a software based function generator.
-- if one wants to control multiple DAC's one need to divide the numbers
-  and round down.
+- If one needs to control multiple DAC's one should divide the numbers
+  and round down to get an estimate.
 
 
 Note: hardware function generator https://github.com/RobTillaart/AD985X
 
 
+Note: 0.2.5 due to duty cycle the triangle and square 
+have become slightly slower.
+
+|  Processor    |  Clock    |  Waveform  |  usec/call  |  max freq  |
+|:--------------|----------:|:-----------|------------:|-----------:|
+|  Arduino UNO  |  16 MHz   |  triangle  |   84        |    50 Hz   |
+|  Arduino UNO  |  16 MHz   |  square    |   57        |  1000 Hz   |
+|  Arduino UNO  |  16 MHz   |  random_DC |   68        |   500 Hz   |
+
+
+#### 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.
+
+Needs further investigations.
+
+
 ## Interface
 
-### Constructor
+```cpp
+#include "functionGenerator.h"
+```
+
+#### Constructor
 
 - **funcgen(float period = 1.0, float amplitude = 1.0, float phase = 0.0, float yShift = 0.0)**
-All parameters can be set in the constructor but also later in configuration.
+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. 
 - **float getPeriod()** returns the set period.
 - **void  setFrequency(float frequency = 1.0)** set the frequency of the wave in Hertz (1/s).
 - **float getFrequency()** returns the set frequency in Hertz.
-- **void  setAmplitude(float amplitude = 1.0)** sets the amplitude of the wave. TODO point to point?
-Setting the amplitude to 0 gives ?what? 
+- **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. Will only be noticeable when 
-compared with other waves.
+- **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 in amplitude, allows to set some zero point.
+- **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.
+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
+(Marsaglia) random number generator. The first is mandatory, the second is optional.
 
 
-### Wave forms
+#### Wave forms
 
-t is time in seconds
+The variable t == time in seconds.
 
-- **float sawtooth(float t, uint8_t mode = 0)** mode == 0 (default) ==>  sawtooth /|. mode == 1 ==> sawtooth |\.
-- **float triangle(float t)** triangle form, duty cycle 50%.
-- **float square(float t)** square wave with duty cycle 50%.
+- **float sawtooth(float t, uint8_t mode = 0)** mode 0 is default.
+  - mode == 0 ==>  sawtooth /|. 
+  - 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 stair(float t, uint16_t steps = 8, uint8_t mode = 0)** mode = 0 ==> steps up, mode = 1 steps down.
-- **float random()** noise generation.
-- **float line()** constant voltage line. Depends on the set YShift and amplitude.
+- **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 line()** constant voltage line. 
+Height depends on the YShift and amplitude.
 - **float zero()** constant zero.
 
-Line() and zero() are functions that can be used to drive a constant voltage from a DAC 
-and can be used to calibrate the generator / DAC combination.
+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.
 
 
-## Operational
+#### Duty Cycle 
 
-See examples.
+Since 0.2.5 the library has **experimental** support for duty cycle.
+The meaning of duty cycle differs per wave form.
+Implementation may change in the future.
 
+In first iteration the following behaviour is implemented:
 
-## Future
+- **square()** implements duty cycle in a well known way. 
+At the start of the period the signal goes "HIGH".
+After duty cycle % of the period the signal goes LOW until the end of the period.
+- **triangle()** function uses the duty cycle to shift the peak from the
+begin (0%) to middle (50%) to end (100%) of the period. 
+- **random_DC()** A duty cycle of 0% is no noise 100% is full amplitude noise 
+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()**.
 
 
-#### waveforms
+The other functions need to be investigated what duty cycle means.
+Current ideas that are **NOT** implemented:
 
-- square duty-cycle  (will be slower!)
-- triangle duty-cycle (makes sawtooth a special triangle)
-- trapezium wave (would merge square and triangle and sawtooth)
-- Bezier curve?
+- **sawtooth()** - move from /|. to /|__  so 0% is a spike, 100% = normal.
+Think of it as the halve of the triangle wave.
+- **sinus()** move the two peaks like the triangle (adjusting steepness / freq)??
+- **stair()** like sawtooth??
+- **line()** has no period so does not make sense (yet).
+- **zero()** has no period so does not make sense (yet).
 
-#### investigate
+Feedback and ideas are welcome.
 
-- duty-cycle for sinus what does it mean. move peak.
-- white noise, pink noise etc.
-- investigate algorithms for performance gains (DAC specific values 10-12-16 bit)
-- Amplitude modulation ?
-- external clock to synchronize two or more sw function generators.
-- RC function curve.
-- heartbeat curve?
-- record a signal and play back
 
-#### misc
+## Future
+
 
-- stand-alone functions in separate .h?
-- mapping to voltage function.
-- check for synergy with https://github.com/RobTillaart/AD985X
+#### Must
 
-#### examples
+- documentation
+  - quality of signals - after substantial time t
+  - max freq per wave form etc.
+    Should this be in the library?
 
-- example ESP32 version as separate task...
-- example with DAC. 8 12 16 bit.
-- example with potentiometers for 4 parameters
 
+#### Should
 
+- smart reseed needed for random().
+- initialize random generator with compile time.
 
+
+#### Could
+
+- waves
+  - trapezium wave (could merge square and triangle and sawtooth)
+  - white noise, pink noise etc.
+- RC function curve.
+- 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.
+
+
+#### Examples
+
+  - Amplitude modulation ?
+  - heartbeat curve?
+  - example ESP32 version as separate task.
+  - example with DAC. 8 12 16 bit.
+  - example with potentiometers for 4 parameters
+
+#### Wont
+
+- investigate duty cycle for waveforms
+  - Derived class for the duty cycle variants? or functions!
+  - **float squareDC()** performance (loss)
+  - **float triangleDC()**
+  - **float sawtoothDC()**
+  - **float sinusDC()** duty-cycle for sinus what does it mean. 
+    - ==> move peaks, two half sinus with diff frequency
+  - **float stairDC()**
+- Bezier curve? (too complex)
+- record a signal and play back  ==> separate class

examples/functionGenerator/functionGenerator.ino

@@ -4,7 +4,6 @@
 // PURPOSE: demo function generators
 //    DATE: 2015-01-03
 //     URL: https://github.com/RobTillaart/FunctionGenerator
-//
 
 
 #include "functionGenerator.h"
@@ -33,11 +32,11 @@ void loop()
   {
     choice = Serial.read();
   }
-  // wave selection by potMeter
+  //  wave selection by potMeter
   // int choice = analogRead(A0) / 200;
 
   float value;
-  // wait for next millisecond;
+  //  wait for next millisecond;
   if (millis() - lastTime > 0)
   {
     lastTime = millis();
@@ -58,5 +57,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 

examples/functionGeneratorDuoPlot/functionGeneratorDuoPlot.ino

@@ -5,7 +5,7 @@
 //    DATE: 2020-06-10
 //     URL: https://github.com/RobTillaart/FunctionGenerator
 //
-// use a Serial plotter to show the data
+//  use a Serial plotter to show the data
 
 
 #include "functionGenerator.h"
@@ -17,7 +17,9 @@ funcgen gen2;
 void setup()
 {
   Serial.begin(115200);
-  // Serial.print("Start functionGeneratorPerformance - LIB VERSION: ");
+  // Serial.println();
+  // Serial.println(__FILE__);
+  // Serial.print("FUNCTIONGENERATOR_LIB_VERSION: ");
   // Serial.println(FUNCTIONGENERATOR_LIB_VERSION);
 
   gen1.setFrequency(13);
@@ -46,5 +48,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --