# The EUCLIDEANUser Guide

### A DIY Subharmonic Synthesizer and Polymetric Drum Machine and Sequencer.

Looking for the Build Guide? Find it here
Looking for the firmware source? Find it here

## Foreword Theory Samples Specs Controls Top

As an amateur but serious pianist (predominantly classical & jazz styles), but with a strong interest in synthesis, I have become similarly interested in exploring the difference between writing music for synthesisers and music for piano. Furthermore, as a professional mathematician, I have a natural fascination with the mathematical underpinnings of music and harmony. So, in addition to being fun to play and tinker with, The EUCLIDEAN allows me to directly experiment with mathematical models that can drive melody, harmony and rhythm.

Consider that with a traditional synth, a particular patch can be quite an interesting and dynamic sound. However, with The EUCLIDEAN, a single patch is actually a fully-fledged and self-consistent musical idea (especially when the sequencer cycling is enabled). The 30 second samples of the built-in presets illustrate this quite well — they are each just set and hit play. And once you incorporate interactive control changes and MIDI input, the musical horizons provided by the device are massively expanded!

If you share any of these interests, or are simply looking for a fun and slightly different DIY music project, read on below, check out the Build Guide, and make one of your own.

## Theory Foreword Samples Specs Controls Top

### Subharmonic Synthesizer

Given a frequency f, it's harmonics are the frequencies 2f, 3f, 4f and so on. The presence and relative amplitudes of these harmonics in a wave is what gives it a particular character, e.g. a sawtooth has all harmonics with amplitudes decreasing linearly, whereas a square wave has only the odd harmonics, and if the amplitudes decrease quadratically the square wave becomes triangular.

Analogously, the subharmonics of a frequency f are f ⁄ 2, f ⁄ 3, and f ⁄ 4 etc. Setting a sub-oscillator to one of these frequencies guarantees a harmonic relationship with the primary frequency f.

The EUCLIDEAN has two independent 4-voice oscillator sections, each with 2 (detunable) voices for the primary oscillator and 2 voices for the sub-oscillator. The frequency for the primary oscillator can be set to any note in a 3 octave range from middle C, and the sub-oscillator frequency is specified by a divisor from 2 to 16.

### Polymetric Sequencer

A polymeter is when 2 or more different meters, each based on the same beat unit, are played together. They will move in and out of alignment at a rate that depends on the least common multiple of their lengths, leading to potentially complicated but repeating rhythmical patterns.

When the different meters have the same length, they are called polyrhythms.

The EUCLIDEAN produces three independent meters that can be combined to generate an enormous variety of interesting and unusual, but nevertheless natural rhythms. The beats within each rhythm are distributed according to the Euclidean algorithm (and so are often called Euclidean Rhythms), thus giving the device its name.

### Putting it all together

The musical output of the EUCLIDEAN results from the interaction of each of these aspects.

Each oscillator has an associated 4 step sequencer, where each step can alter either or both the primary oscillator frequency and the sub-oscillator divisor, thus producing both a melody and a bass line. Progression through the steps is by selected aspects of the rhythm — specifically a beat from any one of the three available meters, or an offbeat.

Since the sequencers are independent, different rhythms will produce interweaving melodies that develop over the full range of the polymeter.

Additionally, drum sounds may be overlaid, where a different percussion instrument is optionally associated with the beats from the three meters and the offbeats.

Other aspects of the sound production are via standard subtractive synthesis — with an AD envelope, a low-pass resonant filter, an LFO and some effects. MIDI integration makes for even richer musical expression by allowing keyboard interaction to transpose the sequences, or play one of the oscillators manually while the other is driven by its sequencer.

## Samples Foreword Theory Specs Controls Top

The following are simple 30 second samples of the default presets, playing without any additional interaction.

Wah
Pluck
SciFi
Meditation
Echo
Funk
Dance
Stroll
Flap
Bells

## Specifications Foreword Theory Samples Controls Top

### The Synthesizer

• Oscillators
• Two independent oscillator units, each with the specifications that follow.
• 2 unison primary voices (detunable).
• 5 primary oscillator waveshapes (bandwidth limited to minimise aliasing): sine, triangle, square, sawtooth, and variable width pulse.
• 2 unison sub-voices with frequency determined by dividing the primary frequency by an integer from 2 to 16.
• 4 sub-oscillator waveshapes: sine, triangle, square, and sawtooth.
• Optionally quantise the primary frequency to any one of:
• 12 note Chromatic scale
• 8 note Diatonic major or minor scale
• 5 note Pentatonic major or minor scale
• 8 note Just Intonation major or minor scale
• 8 note Pythagorean major or minor scale
• The quantisation applies to both oscillators.
• Transposable +/- 24 semitones via a panel control, or arbitrarily via notes from a MIDI keyboard.
• Mixer
• Independent level control for each oscillator and sub-oscillator.
• Independent mute toggle for each oscillator and sub-oscillator.
• LFO
• A single low frequency oscillator allows optional modulation of any of the following parameters:
• oscillator frequency,
• pulse width,
• low-pass filter cut-off frequency.
• Supported LFO waveshapes: sine, triangle, square, sawtooth, reverse sawtooth, and sample and hold.
• Envelope
• There are three independent Attack/Decay envelopes, one for each oscillator unit, and one for the filter.
• Although independent, their settings are common and they can only be adjusted in unison.
• When being played manually via a MIDI keyboard, the envelope becomes Attack/Sustain/Release.
• Low-pass resonant filter
• positive and negative adjustable envelope response.
• Effects
• Chorus
• Flanger
• Delay
• Chorus + Delay
• Only one effect can be active at a time, and each effect has three preset levels: slow, medium and fast.
• The delay timing is synchronised with the overall tempo.

### The Rhythm Generator and Sequencers

• Rhythm
• Three independent "Euclidean Rhythm" generators.
• Configure each one according to the following three parameters:
• the bar length,
• a number of beats to distribute throughout the bar (from 1 to the bar length),
• an offset to shift the whole pattern (from 0 to 1 less than the bar length).
• The maximum bar length is 32.
• The tempo ranges from 30bpm to 1200bpm
• Sequencers
• There are two independent 4 step sequencers.
• The step settings can be applied to only the main oscillator, only the sub-oscillator, or both.
• Sequencer 1 drives oscillator 1, and sequencer 2 drives oscillator 2.
• The sequencers progress on beats from any selected rhythm, and/or on offbeats.
• The sequencer play mode has three states:
• Run — progress as specified according to the rhythm,
• Hold — play and hold a single step,
• Pause — repeat the current step.

### Drum machine

• Instruments
• There is a range of predefined 3 instrument kits provided, where each instrument is associated with one of the 3 rhythm generators.
• The instrument for offbeats is handled independently.
• Available instruments are: bass, snare, rim-shot, closed hi-hat, open hi-hat, low tom, medium tom, high tom, cymbal, ride cymbal, low conga, medium conga, high conga, claves and maracas.
• Play mode
• The play mode is also independent between beats and offbeats, and can be one of:
• Off – do not play,
• Sel – play according to the beat selection buttons across both sequencers,
• R1 – play according to the first rhythm setting,
• 123 – play according to all 3 rhythm settings (regardless of the beat selection button states).
• The offbeat instrument can additionally be configured to an All mode, where it will play on every beat.
• Volume
• The first beat of each rhythm is accented (if played).
• The relative volume of the drums can be controlled independently.

### Other Functions

• Presets
• Up to 100 presets can be saved on an SD card.
• MIDI
• If any sequencer is inactive (either because stopped or not set to advance with the rhythm) then the corresponding oscillator (and sub-oscillator) will play any incoming MIDI notes.
• If both sequencers are active, played MIDI notes transpose the sequences.
• The rhythm can be driven from an external MIDI clock (in this mode the tempo knob supports switching between 36, 24, 12, 6 and 4 clocks to a beat).
• Note on/off and clock messages are output.
• Both 5-pin DIN and USB MIDI connections are supported.
• MIDI CC support is not yet in place.
• Audio output
• 3.5mm line-out socket.
• Serial connection
• A serial connection allows control of parameters from a computer.
• Preset files on the SD card can be queried and restored from backup using serial commands.

## Controls Foreword Theory Samples Specs Top

### Encoder Matrix

The majority of the internal parameters are managed using the Encoder matrix at the top left of the front panel. The left most encoder (the Select encoder) acts to select a row of parameters, with the selected row indicated by the lighting of its corresponding LED.

The top row of parameters controls the oscillators and can be applied to either of the oscillators separately, (the left LED indicating oscillator 1, and the right LED oscillator 2) or both together (indicated by both LEDs being lit).

The 4 other encoders control the selected parameter in their corresponding column.

Clicking the Select encoder toggles "shift" mode (indicated by the select LED flashing), allowing the secondary parameter (as shown in brackets) to be selected and adjusted.

The LCD indicates the value being changed, and will also show a summary of the values for the entire row.

### Run Buttons

The run control buttons work as follows:
• Run — start, or reset to the first beat if already running, the current sequence.
• Stop — stop the current sequence.
• Pause — continually repeat the current sequence step, making it easy to hear the effect of adjusting the settings and tunings. The sequence steps forward with each subsequent press.
• Hold — play a single step of a single oscillator, starting with oscillator 1 & sequencer step 1. Move to the next step (and after the first 4 steps to the next sequencer) with each subsequent press.
The last two modes are particularly useful for tuning the oscillators and the sequencer steps.

### Meter

The meter settings are shown on the LCD as a 3x3 array of numbers. Each row corresponds to one of the Euclidean Rhythm generators, and each column shows the number of beats, the bar length, and the offset respectively.

Turning the Meter encoder moves the cyan outline through these 9 numbers, and there is also the option to select all three bar lengths together (since a common use case is to have these all at the same value).

Clicking the Meter encoder converts the cyan outline to a block cursor, and in this state turning the encoder will adjust the selected value.

Whenever editing the rhythm, the LCD shows a graphical view of the beat pattern. When playing, a dynamic view of the rhythm is scrolled along the bottom left, with red squares showing the beats and blue squares the initial beat in a rhythm. If this initial beat is not played, it is shown as an open square.

The tempo is adjusted simply by turning the tempo pot, with the updated value shown in beats per minute on the LCD.

### Presets

If an SD card is present (in the slot on the Teensy Audio Shield) then, in addition to the 10 ROM presets shown earlier, up to 100 sets of parameter values can be saved as user presets.

Turn the Preset encoder to select a specific preset by number, then click to choose one of the following actions:

• Save – save the current settings to the chosen preset,
• Delete – delete the chosen preset,
• Cancel – return from the menu without taking any action.

The Preset encoder also presents the following options:

• Save new preset – save the current settings to the first available preset number,
• Init settings – setting parameters to a default set,
• Set to manual – make all sequencer steps match the current potentiometer positions.

Each startup the entire set of presets are backed up on the SD card, and, if necessary, serial commands can be used to restore an accidentally overwritten or deleted preset. To avoid this backup, hold down the Pause button when starting.

The preset files are plain text and can be backed up and/or edited externally, but keep in mind that there is only minimal validation on load. See the source code for details of the format.

### Volumes

The Volume potentiometer controls the overall output volume, but the relative drum machine volume can be adjusted independently using the Drum vol. potentiometer.

The volume settings are not saved with the preset data.

### Sequencer

Each sequencer step has a corresponding potentiometer control and LED. Turning the pot adjusts the offset for that particular step, and, when playing, the LED lights to show active steps.

When applied to the main oscillator, each step selects an offset from -24 to +24 semitones (prior to any chosen quantisation).

When applied to the sub-oscillator, each step adjusts the divisor by -8 to +8, but the final result always remains in the range from 2 to 16.

The active sequencer steps are always displayed on the LCD.

Simultaneously clicking the Select encoder and the Sequencer Apply button puts the corresponding sequencer into "Permute" mode (indicated by the Sequencer label on the LCD being shown in green). In this mode it will cycle through all 24 permutations of the 4 steps — remaining on each permutation for 8 loops.

This allows a wider exploration of the melodic options generated the current step values, while maintaining the basic character and relationships inherent in the overall settings.

If both sequencers are permuting, the 8 loop cycles are staggered by 4 loops.

### Beats

Progressing through the steps of each sequencer is handled by the Beat 1, Beat 2, Beat 3 and Offbeat buttons.

For any Beat button that is selected for a sequencer, a step occurs when the corresponding rhythm has a beat. If both sequencers have the same button set, they will step together.

In this context, an offbeat is any beat where none of the selected rhythms (across both sequencers) has a beat. So offbeats can be used to fill in the gaps if desired.

### Drum Machine

Beats and offbeats are configured separately in the drum machine.

The Beat encoder allows you to choose a mode for on-beat drumming as follows:

• Off – do not play,
• Sel – play according to the beat selection buttons across both sequencers,
• R1 – play according to the first rhythm setting,
• 123 – play according to all 3 rhythm settings (regardless of the beat selection button states).

Rotate the Beat kit encoder to select a kit from the options shown on the LCD. Each kit is comprised of three instruments, with each instrument playing on the beats of the corresponding rhythm.

Similarly, choose an offbeat definition and mode with the Offbeat encoder from the similar options:

• Off – do not play,
• Sel – play according to the beat selection buttons across both sequencers,
• R1 – play according to the first rhythm setting,
• 123 – play according to all 3 rhythm settings (regardless of the beat selection button states),
• All – play on every beat.

The offbeat instrument is chosen by rotating the Off inst..

There is an accent on the first beat of each rhythm. Also, the drum sounds pass through the filter and as such can also be modulated, but they are not affected by the amplitude envelope.

### Startup

If you hold down the Run button when starting, the unit will enter a "Demo" mode where it will progress through every preset on the SD card, spending 8 seconds on each.

If you hold down the Stop button when starting, the unit will require an external MIDI clock to drive the sequencer (12 clocks to each beat).

As mentioned above, if you hold down the Pause button when starting, the presets will not be backed up.

### Serial Commands

When a serial terminal is connected to the Teensy, the following commands can be sent.
```	Help:      help|?        (print this message)
Run:       run|r
Stop:      stop|.
Hold:      hold|h
Pause:     pause
Select:    sel n         (n from 1 to 6)
Shift:     shift         (apply shift to current selection)
Turn:      turn n d      (n from 1 to 4, d +/- or value)
Step:      step i n d    (i = 1 or 2, n from 1 to 4, d +/- or value)
Beat:      beat i b123 o (i = 1 or 2, b123 is 0 to 7 and o is 0 or 1)
Apply:     app i os      (i = 1 or 2, os is 0 to 3)
Meter:     meter n i j k (n = 1-3 rhythm, i = beats, j = length, k = offset)
Tempo:     tempo t       (t is value 0-127, or +/- value for relative change)
Print:     conf          (print the current config)
Preset:    pre n         (load preset n)
Save:      save n        (save file data for preset n)
Dump:      dump n        (n or * to print one or all presets)
Restore:   rest n        (n or * to restore one or all presets)
Memory:    mem           (print maximum memory usage)
Mix:       mix os vol    (os is o1, o2, s1 or s2, vol is 0 to 127)
Mute:      mute os       (os is o1, o2, s1 or s2 - toggle mute status of osc1/sub1/osc2/sub2)
Transpose: +/-n          (transpose by the given number of semitones)
Osc:       osc i f sh    (set oscillator note [40,76] and shape - i = 1 or 2, sh [sin,tri,sq,saw,p])
Sub-osc:   sub i d sh    (set sub-oscillator divisor [2,16] and shape - i = 1 or 2, sh [sin,tri,sq,saw,p])
Osc mod:   omod i pw mod (set oscillator pw [0,127](+/-) and modamt [0,127] - i = 1 or 2, optional (+/-) toggles pw mod)
Detune:    det n         (set detune to n [0,32] for both oscillators)
LFO:       lfo rate sh   (set lfo rate [0,127] and shape [sin,tri,sq,saw,s+h] - '.' for no change)
Envelope:  env a d       (set attack and decay - [0,127] or '.' for no change)
Filter:    f co res      (set cutoff and resonance - [0,127] or '.' for no change)
Filter mod:fmod env mod  (set env amt [-64,63] and mod amt [0,127] - '.' for no change)
Effects:   eff e s       (set eff e [off,ch,fl,dl,chdl] to s [0,1,2,3]
Volume:    vol n         (n from 0 to 127)
Drum vol:  dv n          (drum volume from 0 to 127)
```
I use the unix program screen, connecting to /dev/tty.usbmodem[nnnnnn].