Egressus melodium - Clockable and free-running LFO and random CV pattern generator (#337)

* initial egressum melodiam commit

* updated defaults to match doc

* move python docstrings to their correct place

* fix typos

* update debug modes

* removed StopException

* updated README.md

* replaced int(bool) with BOOL_DICT[bool]

* updated shread and wave icons to bytearrays

* use max_output_voltage from global config

* max cv voltage to 5V

* removed demo vid placeholder from MD file

* wrapped europi_config line in a try/catch to avoid errors with older firmware

* Update to require latest firmware version

* use max_output_voltage to comply with new config mgmt mechanism.

* removed debug output and try/except block

* minor cosmetic changes

* removed bpm functions - no longer used

* updated docstrings

* move din interrupt handling code to main()

* set CPU freq from global config value

* apply black formatting

* updated comment re CPU freq

* removed unused var: unClockedModeIndicator

* removed unused button handling placeholders

* added StopIteration handling back in :)

* removed overclocking - it is already done in the firmware

* Update egressus_melodiam.py

Collapse file-level docstring into a single string instead of multiple

* Update egressus_melodiam.py

Use Doxygen-style docstrings, consistently use `num` vs `sampleRate` for sample generation functions

* update output voltages in doc

* specify MAX_OUTPUT_VOLTAGE in doc

* updated documentation

* reverted CVecorder author change - requested by admin

* reduce frequency of saveState calls - this should fix OSError 28

* optimize calculateOptimalSampleRate() to work with 0-10V

* fixed typos, added link to demo vid

---------

Co-authored-by: Nik Ansell <[email protected]>
Co-authored-by: Chris I-B <[email protected]>

Author: 3 people

software/contrib/README.md

@@ -42,6 +42,12 @@ Recording of CV can be primed so that you can record a movement without missing
 <i>Author: [anselln](https://github.com/anselln)</i>
 <br><i>Labels: sequencer, CV, performance</i>
 
+### Egressus Melodium \[ [documentation](/software/contrib/egressus_melodiam.md) | [script](/software/contrib/egressus_melodiam.py) \]
+Clockable and free-running LFO and random CV pattern generator
+
+<i>Author: [gamecat69](https://github.com/gamecat69)</i>
+<br><i>Labels: clocked lfo, sequencer, CV, randomness</i>
+
 ### Envelope Generator \[ [documentation](/software/contrib/envelope_generator.md) | [script](/software/contrib/envelope_generator.py) \]
 An attack release envelope with optional sustain and looping functionality.
 Envelopes are triggered or gated by the digital input, and the envelope is output, along with a copy of the digital input and an inverted copy of the envelope.

software/contrib/egressus_melodiam-docs/.$egressus_melodiam.png.bkp

@@ -0,0 +1,91 @@
+# Egressus Melodiam (Stepped Melody)
+
+author: Nik Ansell (github.com/gamecat69)
+date: 19-Feb-24
+labels: clocked lfo, sequencer, CV, randomness
+Demo Video: https://youtu.be/_qlnV_ewb_c
+
+Clock-able and free-running LFO and random CV pattern generator.
+Eight different wave shapes either define the LFO shape or the slew shape between CV pattern steps.
+Use it to generate variable length melodies (using a quantizer), LFOs or weird and wonderful control voltages.   
+
+# Inputs, Outputs and Controls
+
+![Operating Diagram](./egressus_melodiam-docs/egressus_melodiam.png)
+
+Analogue outputs send a voltage from 0V to the maximum configured output voltage (MAX_OUTPUT_VOLTAGE) as defined by europi_config.
+The default maximum output voltage is +10V.
+
+# Getting started
+
+1. Patch a 50% duty cycle square wave or clock with pulses >= 16ms in duration into the digital input
+2. Connect one or more outputs to an input on another module (e.g. CV modulation inputs)
+3. Select a pattern length using Knob 1
+4. Start your clock. Each output will now send a looping CV pattern to your module!
+
+So, what happened in the above example?
+When the module first powered on it automatically generated 6 x 32 step random CV patterns - one for each of the 6 outputs.
+Each time a clock is received, the step advances by one step and then loops when it get to the end of the pattern.
+The length of the pattern loop is controlled using knob 1, which supports a value from 1 to 32.
+
+# Changing the slew/wave shape and clock division of an output
+
+Refer to the above diagram for a visual representation of the example below.
+
+1. Press and release button 2 until the output number you would like to edit is shown on the top-right.
+2. Press button 1 to cycle through the available wave shapes
+3. Adjust knob 2 to select the output division. An output division of 1 causes the CV pattern / LFO for that
+output to run at the clock rate. An output division greater than one reduces the CV pattern / LFO to run at the selected division (e.g. selecting a division of 2 would run at half the clock rate)
+
+In LFO mode (pattern length of 1) the wave shape determines the shape of the cycling LFO. However, when in CV pattern mode (Pattern length > 1) the wave shape determines the slew between pattern steps.
+
+## Available Slew/wave shapes
+
+Eight shapes are available. Some are symmetrical where the rising shape is the same as the falling shape, others are asymmetrical.
+
+- [<img src="./egressus_melodiam-docs/square.png" width="15"/>](square.png) **Square/Step**: Moves up/down immediately and holds until the next step
+- [<img src="./egressus_melodiam-docs/tri.png" width="15"/>](tri.png) **Triangle/Linear**: A straight line between steps
+- [<img src="./egressus_melodiam-docs/sine.png" width="15"/>](sine.png) **Sine/Smooth**: A smooth line between steps using a sine/cosine wave
+- [<img src="./egressus_melodiam-docs/exp-up-exp-down.png" width="15"/>](exp-up-exp-down.png) **Exponential up and down**: An exponential curve between steps. This rises/falls slowly at the start and fast at the end
+- [<img src="./egressus_melodiam-docs/sharktooth.png" width="15"/>](sharktooth.png) **Sharktooth**: Logarithmic rise, exponential fall. A logarithmic curve rises/falls quickly at the start and slowly at the end.
+- [<img src="./egressus_melodiam-docs/sharktooth-rev.png" width="15"/>](sharktooth-rev.png) **Reverse Sharktooth**: Exponential rise, Logarithmic fall.
+- [<img src="./egressus_melodiam-docs/log-up-step-down.png" width="15"/>](log-up-step-down.png) **Logarithmic up, step down**: Upward transitions are logarithmic, downward transitions are stepped.
+- [<img src="./egressus_melodiam-docs/square-up-exp-down.png" width="15"/>](square-up-exp-down.png) **Step up, exponential down**: Upward transitions are stepped, downward transitions are exponential.
+
+# Generating a new CV pattern for an output
+
+A new CV pattern is generated for the selected output by holding down button 1 for 2 seconds and releasing. An indicator is shown on the top left of the screen to show a new CV pattern has been generated. Note that if you are in LFO mode (pattern length of 1) this function will have no effect until the pattern length is increased. 
+
+# LFO Mode / CV Pattern mode
+
+Selecting a pattern length of 1 will output an LFO.
+Selecting a pattern length greater than one plays through the generated CV patterns.
+Slew is generated between CV pattern steps when a wave shape other then square is selected.
+
+# Clocked / Free-running mode
+
+Clocked mode is selected by default - indicated by showing the length of the CV pattern (in dots) in the middle of the screen.
+To enter free-running mode, hold button 2 for 2 seconds and release. The configured clock rate in milliseconds is shown
+in the middle of the screen to indicate you are in free-running mode.
+
+Note that when in free-running mode, the previously selected pattern length remains unchanged, it is therefore a good idea to select the required pattern length before changing to unclocked mode.
+
+# Saving and loading
+
+All settings and CV patterns are saved when changes are made and will not be lost when the module is powered off.
+
+# Changing the maximum CV voltage
+
+CV Patterns (including LFOs) output a range of 0-10V based on the default globally configured value.
+If you would like to change this value, two methods are available 1) Create a json file (see below), 2) Configure the global configuration value using the UI (coming soon in a later firmware release).
+
+## Reducing the maximum CV output using a json file
+
+1. Create a file on your pico named `config/config_EuroPiConfig.json`. Thonny is the easiest method for this.
+2. Add the following to the json file:
+
+```json
+{
+    "max_output_voltage": 5
+}
+```