Add Turing Machine mode to Pam's as another wave shape (#401)

* Add Turing Machine mode to Pam's as another wave shape

* Fixes a bug where a SettingMenuItem could have multiple copies of the autoselect items appended to it if its choice array is shared across objects.

Author: chrisib

software/contrib/pams-docs/wave_turing.png

@@ -132,13 +132,16 @@ The submenu for each CV output has the following options:
     triangle to ramp)
   - ![Sine Wave](./pams-docs/wave_sine.png) Sine: bog-standard sine wave
   - ![ADSR Envelope](./pams-docs/wave_adsr.png) ADSR: an Attack/Decay/Sustain/Release envelope
+  - ![Turing](./pams-docs/wave_turing.png) Turing: a shift-register like the Music Thing Modular Turing Machine. Can either
+    output pulses or stepped CV.
   - ![Random Wave](./pams-docs/wave_random.png) Random: outputs a random voltage at the start of every euclidean pulse,
     holding that voltage until the next pulse (if `EStep` is zero then every clock tick is assumed to be a euclidean
     pulse)
-  - ![AIN](./pams-docs/wave_ain.png) AIN: acts as a sample & hold of `ain`, with a sample taken at the start of every
+  - ![AIN](./pams-docs/wave_ain.png) AIN (S&H): acts as a sample & hold of `ain`, with a sample taken at the start of every
     euclidean pulse (if `EStep` is zero then every clock tick is assumed to be a euclidean pulse)
-  - ![KNOB](./pams-docs/wave_knob.png) KNOB: acts as a sample & hold of `k1`, with a sample taken at the start of every
+  - ![KNOB](./pams-docs/wave_knob.png) KNOB (S&H): acts as a sample & hold of `k1`, with a sample taken at the start of every
     euclidean pulse (if `EStep` is zero then every clock tick is assumed to be a euclidean pulse)
+
 - `Width` -- width of the resulting wave. See below for the effects of width adjustment on different wave shapes
 - `Phase` -- the phase offset of the wave. Starting a triangle at 50% would start it midway through
 - `Ampl.` -- the maximum amplitude of the output as a percentage of the 10V hardware maximum
@@ -147,6 +150,9 @@ The submenu for each CV output has the following options:
 - `Sustain` -- the percentage level of the sustain phase of an ADSR envelope
 - `Release` -- the percentage of of the cyle time minus the attack & decay phases dedicated to the release phase of
   an ADSR envelope
+- `TLen` -- The length of the Turning machine shift register
+- `TLock` -- The lock value of the Turing machine shift register
+- `TMode` -- The mode of the Turing machine: either `Gate` or `CV`
 - `Skip%` -- the probability that a square pulse or euclidean trigger will be skipped
 - `EStep` -- the number of steps in the euclidean rhythm. If zero, the euclidean generator is disabled
 - `ETrig` -- the number of pulses in the euclidean rhythm
@@ -299,15 +305,38 @@ CV1 Output
 _____|         |____|         |__________
 ```
 
+### Turing Waves
+
+`Turing` wave mode can operate in one of two sub-modes: `Gate` (default) or `CV`.
+
+In `Gate` mode, it outputs simple of/off square waves.
+
+Like the [original Turing Machine](https://github.com/TomWhitwell/TuringMachine) module, the `TLock` parameter
+controls the likelihood that bits are randomly flipped when the register shifts.  When `TLock` is _positive_, the
+output pattern is equal to the `TLength` parameter. When `TLock` is _negative_ the output pattern is the initial
+`TLength` bits, followed by their compliment.  The further from zero in either direction, the less likely it is that
+bits will be flipped during the shift.
+
+For example if `TLength` is 8 and the register contains `10101100`, and `TLock` is `+100` the gate output will be
+`[1, 0, 1, 0, 1, 1, 0, 0]`.  If `TLock` is `-100` instead the gate output will be
+`[1, 0, 1, 0, 1, 1, 0, 0, 0, 1, 0, 1, 0, 0, 1, 1]`.
+
+In `CV` mode it outputs a pseudo-random control voltage,similar to the `Random` wave. The value of the wave is
+determined by looking at the lowest 8 bits in the register (the register always contains 16 bits, regardless of
+`TLength`), treating them as a binary integer, and dividing that value by 256.  The resulting value in the range
+`[0, 1)` is multiplied by the output amplitude to generate the output voltage.
+
 ### Effects of Width on Different Wave Shapes
 
 - Square: Duty cycle control. 0% is always off, 100% is always on
 - Triangle: Symmetry control. 50% results in a symmetrical wave, 0% results in a saw wave,
   100% results in a ramp
 - Sine: ignored
 - Random: offset voltage as a percentage of the maximum output
-- AIN: ignored
-- KNOB: ignored
+- AIN (S&H): ignored
+- KNOB (S&H): ignored
+- Turing (Gate): Duty cycle control. 0% is always off, 100% will smear adjacent on-gates together
+- Turing (CV): ignored.
 
 ### Reset and Start Triggers
 
@@ -382,9 +411,10 @@ as an offset voltage.
 There is digital attenuation/gain via the `AIN > Gain` or `KNOB > Gain` settings.  This sets the
 percentage of the input signal that is passed to settings listenting to these inputs.
 
-For example, if your modulation source can only output up to 5V you should set the gain to
-`12.0 / 5.0 * 100.0 = 240%`.  This will allow the modulation source to fully sweep the
-range of options available.
+For example, if EuroPi is configured to use 10V as its maximum input voltage, but you patch
+an LFO that can only generate 0-5V, choosing `AIN` will only allow the LFO to sweep through the
+first half of the available options. To sweep the whole range, set `AIN > Gain` to
+`MAX_INPUT_VOLTAGE / (voltage source's max output) * 100 = 10.0 / 5.0 * 100 = 200`.
 
 The `AIN > Precision` and `KNOB > Precision` settings allow control over the number of samples
 taken when reading the input.  Higher precision can result in slower processing, which may introduce

software/contrib/pams.md

@@ -205,29 +205,53 @@
 #  etc...
 WAVE_KNOB = 6
 
+## Turing machine shift register
+#
+#  Requires a sub-setting for either gate or CV mode
+WAVE_TURING = 7
+
 ## Available wave shapes
+#
+#  These must be placed in the desired order
 WAVE_SHAPES = [
     WAVE_SQUARE,
     WAVE_TRIANGLE,
     WAVE_SIN,
     WAVE_ADSR,
+    WAVE_TURING,
     WAVE_RANDOM,
     WAVE_AIN,
-    WAVE_KNOB
+    WAVE_KNOB,
 ]
 
-## Ordered list of labels for the wave shape chooser menu
+## Labels for the wave shape chooser menu
 WAVE_SHAPE_LABELS = {
     WAVE_SQUARE: "Square",
     WAVE_TRIANGLE: "Triangle",
     WAVE_SIN: "Sine",
     WAVE_ADSR: "ADSR",
+    WAVE_TURING: "Turing",
     WAVE_RANDOM: "Random",
     WAVE_AIN: "AIN (S&H)",
     WAVE_KNOB: "KNOB (S&H)",
 }
 
-## Images of teh wave shapes
+# Turing machine modes of operation
+#
+# We can either output the gate pulses OR we can
+# output the semi-random CV
+MODE_TURING_GATE = 0
+MODE_TURING_CV = 1
+TURING_MODES = [
+    MODE_TURING_GATE,
+    MODE_TURING_CV,
+]
+TURING_MODE_LABELS = {
+    MODE_TURING_GATE: "Gate",
+    MODE_TURING_CV: "CV",
+}
+
+## Images of the wave shapes
 #
 #  These are 12x12 bitmaps. See:
 #  - https://github.com/Allen-Synthesis/EuroPi/blob/main/software/oled_tips.md
@@ -237,6 +261,7 @@
     WAVE_TRIANGLE: bytearray(b'\x06\x00\x06\x00\t\x00\t\x00\x10\x80\x10\x80 @ @@ @ \x80\x10\x80\x10'),
     WAVE_SIN: bytearray(b'\x10\x00(\x00D\x00D\x00\x82\x00\x82\x00\x82\x10\x82\x10\x01\x10\x01\x10\x00\xa0\x00@'),
     WAVE_ADSR: bytearray(b' \x00 \x000\x000\x00H\x00H\x00G\xc0@@\x80 \x80 \x80\x10\x80\x10'),
+    WAVE_TURING: bytearray(b'\xff\xf0\x04\x00\xf8\x00\x00\x00\xff\xf0\x04\x00\xf8\x00\x00\x00\xff\xf0\x04\x00\xf8\x00\x00\x00'),
     WAVE_RANDOM: bytearray(b'\x00\x00\x08\x00\x08\x00\x14\x00\x16\x80\x16\xa0\x11\xa0Q\xf0Pp`P@\x10\x80\x00'),
     WAVE_AIN: bytearray(b'\x00\x00|\x00|\x00d\x00d\x00g\x80a\x80\xe1\xb0\xe1\xb0\x01\xf0\x00\x00\x00\x00'),
     WAVE_KNOB: bytearray(b'\x06\x00\x19\x80 @@ @ \x80\x10\x82\x10A @\xa0 @\x19\x80\x06\x00'),
@@ -540,6 +565,9 @@ def __init__(self, cv_out, clock, n):
         self.cv_out = cv_out
         self.clock = clock
 
+        # 16-bit integer, initially random
+        self.turing_register = random.randint(0, 65535)
+
         ## What quantization are we using?
         #
         #  See contrib.pams.QUANTIZERS
@@ -799,6 +827,42 @@ def __init__(self, cv_out, clock, n):
             autoselect_cv = True,
         )
 
+        # Turing machine settings
+        self.t_length = SettingMenuItem(
+            config_point = IntegerConfigPoint(
+                f"cv{n}_t_len",
+                2,
+                16,
+                8
+            ),
+            prefix = f"CV{n}",
+            title = "TLen",
+            autoselect_knob = True,
+            autoselect_cv = True,
+        )
+        self.t_lock = SettingMenuItem(
+            config_point = IntegerConfigPoint(
+                f"cv{n}_t_lock",
+                -100,
+                100,
+                0
+            ),
+            prefix = f"CV{n}",
+            title = "TLock",
+            autoselect_knob = True,
+            autoselect_cv = True,
+        )
+        self.t_mode = SettingMenuItem(
+            config_point = ChoiceConfigPoint(
+                f"cv{n}_t_mode",
+                TURING_MODES,
+                MODE_TURING_GATE,
+            ),
+            prefix = f"CV{n}",
+            title = "TMode",
+            labels = TURING_MODE_LABELS,
+        )
+
         ## All settings in an array so we can iterate through them in reset_settings(self)
         self.all_settings = [
             self.quantizer,
@@ -811,6 +875,9 @@ def __init__(self, cv_out, clock, n):
             self.e_step,
             self.e_trig,
             self.e_rot,
+            self.t_length,
+            self.t_lock,
+            self.t_mode,
             self.skip,
             self.swing,
             self.mute,
@@ -873,18 +940,17 @@ def update_menu_visibility(self, new_value=None, old_value=None, config_point=No
         show_width = wave_shape != WAVE_AIN and wave_shape != WAVE_KNOB and wave_shape != WAVE_SIN
         self.width.is_visible = show_width
 
+        # hide the turing machine settings if we're not in Turing mode
+        show_turing = wave_shape == WAVE_TURING
+        self.t_length.is_visible = show_turing
+        self.t_lock.is_visible = show_turing
+        self.t_mode.is_visible = show_turing
+
     def change_e_length(self, new_value=None, old_value=None, config_point=None, arg=None):
         self.e_trig.modify_choices(list(range(self.e_step.value+1)), self.e_step.value)
         self.e_rot.modify_choices(list(range(self.e_step.value+1)), self.e_step.value)
         self.recalculate_e_pattern()
 
-    def request_clock_mod(self, new_value=None, old_value=None, config_point=None, arg=None):
-        self.clock_mod_dirty = True
-
-    def change_clock_mod(self):
-        self.real_clock_mod = self.clock_mod.mapped_value
-        self.clock_mod_dirty = False
-
     def recalculate_e_pattern(self, new_value=None, old_value=None, config_point=None, arg=None):
         """Recalulate the euclidean pattern this channel outputs
         """
@@ -895,6 +961,13 @@ def recalculate_e_pattern(self, new_value=None, old_value=None, config_point=Non
 
         self.next_e_pattern = e_pattern
 
+    def request_clock_mod(self, new_value=None, old_value=None, config_point=None, arg=None):
+        self.clock_mod_dirty = True
+
+    def change_clock_mod(self):
+        self.real_clock_mod = self.clock_mod.mapped_value
+        self.clock_mod_dirty = False
+
     def square_wave(self, tick, n_ticks):
         """Calculate the [0, 1] value of a square wave with PWM
 
@@ -911,8 +984,10 @@ def square_wave(self, tick, n_ticks):
         start_tick = self.phase.value * n_ticks / 100.0
         end_tick = (start_tick + duty_cycle) % n_ticks
 
-        if (start_tick < end_tick and tick >= start_tick and tick < end_tick) or \
-           (start_tick > end_tick and (tick < end_tick or tick >= start_tick)):
+        if (
+            (start_tick < end_tick and tick >= start_tick and tick < end_tick) or
+            (start_tick > end_tick and (tick < end_tick or tick >= start_tick))
+        ):
             return 1.0
         else:
             return 0.0
@@ -978,6 +1053,9 @@ def adsr_wave(self, tick, n_ticks):
         /            \
         -A--D---S---R-
         ---n_ticks----
+
+        @param tick  The current tick, in the range [0, n_ticks)
+        @param n_ticks  The number of ticks in which the wave must complete
         """
 
         # apply the phase offset
@@ -1011,6 +1089,48 @@ def adsr_wave(self, tick, n_ticks):
             # outside of the ADSR
             return 0.0
 
+    def turing_shift(self):
+        """Shift the turing machine register by 1 bit
+        """
+        r = random.randint(0, 99)
+        if r >= abs(self.t_lock.value):
+            incoming_bit = random.randint(0, 1)
+        else:
+            incoming_bit = (self.turing_register >> (self.t_length.value - 1)) & 0x01
+        self.turing_register = ((self.turing_register << 1) & 0xffff) | incoming_bit
+
+    def turing_wave(self, tick, n_ticks):
+        """Calculate the [0, 1] output of a Turing Machine wave
+
+        @param tick  The current tick, in the range [0, n_ticks)
+        @param n_ticks  The number of ticks in which the wave must complete
+        """
+        # respect phase shifting when updating the shift register
+        start_tick = int(self.phase.value * n_ticks / 100.0)
+        if tick == start_tick:
+            self.turing_shift()
+
+        active_bit = self.turing_register & 0x0001
+        if self.t_lock.value < 0 and self.wave_counter % (2 * self.t_length.value) >= self.t_length.value:
+            # turing machine outputs the [register, ~register] when "locked-left",
+            # effectively doubling the length of the pattern
+            active_bit = active_bit ^ 0x01
+
+        if self.t_mode.value == MODE_TURING_GATE:
+            if active_bit:
+                return self.square_wave(tick, n_ticks)
+            else:
+                return 0
+        else:
+            value = self.turing_register & 0xff  # consider only the lowest 8 bits
+
+            if self.t_lock.value < 0 and self.wave_counter % (2 * self.t_length.value) >= self.t_length.value:
+                # if we're in the second half of a doubled pattern, invert the value
+                value = (~value) & 0xff
+
+            return value / 256
+        return 0
+
     def reset(self):
         """Reset the current output to the beginning
         """
@@ -1097,6 +1217,8 @@ def tick(self):
                 wave_sample = wave_sample * self.sine_wave(wave_position, ticks_per_note) * (self.amplitude.value / 100.0)
             elif self.wave_shape.value == WAVE_ADSR:
                 wave_sample = wave_sample * self.adsr_wave(wave_position, ticks_per_note) * (self.amplitude.value / 100.0)
+            elif self.wave_shape.value == WAVE_TURING:
+                wave_sample = self.turing_wave(wave_position, ticks_per_note) * (self.amplitude.value / 100.0)
             else:
                 wave_sample = 0.0
 
@@ -1211,6 +1333,9 @@ def __init__(self):
             ch.clock_mod.add_child(ch.e_step)
             ch.clock_mod.add_child(ch.e_trig)
             ch.clock_mod.add_child(ch.e_rot)
+            ch.clock_mod.add_child(ch.t_length)
+            ch.clock_mod.add_child(ch.t_lock)
+            ch.clock_mod.add_child(ch.t_mode)
             ch.clock_mod.add_child(ch.swing)
             ch.clock_mod.add_child(ch.quantizer)
             ch.clock_mod.add_child(ch.root)

software/contrib/pams.py

@@ -421,7 +421,7 @@ def get_option_list(self):
         elif t is BooleanConfigPoint:
             items = [False, True]
         elif t is ChoiceConfigPoint:
-            items = self.src_config.choices
+            items = list(self.src_config.choices)  # make a copy of the items so we can append the autoselect items!
         else:
             raise Exception(f"Unsupported ConfigPoint type: {type(self.src_config)}")