# Turing Machine technical notes

This document contains development notes, implementation details, known issues,
and version-specific changes for the Workshop Computer Turing Machine Program
Card.

For operating instructions, patching, web-editor setup, and firmware
installation, see [README.md](README.md).

## Source and license

- Language: C++ using the Pico SDK
- Framework: Chris Johnson's ComputerCard library
- License: GPL-3.0-or-later
- Current documented version: 1.5.3

Source code:

- [Turing Machine v1.5
  source](https://github.com/TomWhitwell/Workshop_Computer/tree/main/releases/03_Turing_Machine/Rev_1_5_Code)
- [ComputerCard
  library](https://github.com/TomWhitwell/Workshop_Computer/tree/main/Demonstrations%2BHelloWorlds/PicoSDK/ComputerCard)

## Runtime architecture

The v1.5 firmware was rewritten in Pico SDK C++ using the ComputerCard library.
Work is divided between the RP2040's two cores:

- One core runs at 48 kHz, tracks incoming pulses, and updates the clocks.
- The other core updates the LEDs, handles the USB connection to the web
  editor, and writes settings to flash.

The web editor communicates with the card using MIDI SysEx.

## v1.5 changes

### External clocking

- Pulse In 1 replaces tap tempo as the main clock input.
- Channel 2's Diviply clock derives from the external Pulse In 1 clock.
- When the incoming clock changes speed, Diviply waits for a second pulse before
  changing rate rather than attempting to average the transition.
- Pulse In 1 accepts signals into high audio rates, allowing oscillator-like
  behaviour.
- Pulse In 2 replaces the Diviply clock and runs Channel 2 independently.
- With Pulse In 2 connected, Pulse Out 2 follows Pulse In 2.

### Web editor

- The editor was redesigned around the two presets selected by the Z switch.
- Communication moved to MIDI SysEx.
- Google Chrome is the tested browser.
- Safari on macOS does not work with the editor.
- The current editor is hosted at
  <https://tomwhitwell.github.io/Turing_Machine_Workshop_Computer/>.
- The previous editor at
  <https://www.musicthing.co.uk/web_config/turing.html> should redirect to the
  current version.

The editor exposes:

- Seven scales or modes
- Octave ranges from one to four octaves
- Blip, short-variable, and long-variable note lengths
- A Channel 2 loop-length offset
- Clock and Turing-bit pulse modes for both pulse outputs
- Configurable ranges for both Audio/CV outputs

Blip pulses are approximately 1% of the note duration, with a minimum around
2 ms. The short and long variable pulse lengths are generated by their own
Turing sequences, so their patterns lock and randomize with the pitch
sequences.

### CV and reset inputs

- CV In 1 adds a positive or negative voltage to the Channel 2 Diviply setting.
- CV In 2 applies an experimental, chromatically quantized pitch offset to both
  channels. It expects approximately 0–1 V and is not calibrated.
- Audio/CV In 1 resets all internal sequences to their first state on a rising
  edge.
- Audio/CV In 2 provides experimental voltage control of preset selection.
  Approximately +1 V or more selects Z up; approximately -1 V or less selects
  Z middle/down.

Resetting a Turing sequence is not equivalent to rewinding a conventional step
sequencer. A hardware Turing Machine normally has no way to recover prior shift
register states. This firmware stores enough state to return its internal
sequences to their startup position.

## Random initialization

Each Program Card's unique serial number seeds the firmware's random-number
system. Consequently:

- Individual cards can generate different initial patterns.
- A card started in a locked position should reproduce its own initial pattern
  until the sequence is randomized.

## Stored settings

Hold Z down while tapping Reset/Load to clear the stored configuration. A fast
LED animation indicates that Z can be released.

Clearing settings may be necessary after installing a newer firmware build if
the stored configuration format has changed.

## Known issues and limitations

- Automatic card-version checking and upgrade notification are not implemented.
- The web editor's visualizer is not a precise representation of the internal
  clock state because both pulse outputs clock it.
- The editor's responsive layout could be improved for different screen sizes.
- CV In 2's pitch offset is quantized but not calibrated.
- Audio/CV reset and CV preset selection are experimental.

## Repository layout

| Location | Contents |
| --- | --- |
| `Rev_1_5_Code/` | Current v1.5 Pico SDK C++ source |
| `Rev_1_5_UF2/` | Installable v1.5 firmware builds |
| `Arduino Code/` | Earlier Arduino implementation |
| `OLD/` | Superseded material retained for reference |

Repository folder:

<https://github.com/TomWhitwell/Workshop_Computer/tree/main/releases/03_Turing_Machine>

## Related documentation

- [User-facing instructions](README.md)
- [Published Turing Machine card
  instructions](https://www.musicthing.co.uk/Computer_Program_Cards/#03-turing-machine)
- [Current Turing Machine web
  editor](https://tomwhitwell.github.io/Turing_Machine_Workshop_Computer/)
- [Original hardware Turing Machine
  background](https://www.musicthing.co.uk/Turing-Machine/)
- [Workshop System calibration
  guide](https://www.musicthing.co.uk/Workshop_System_Calibration/)