Instructions & Philosophy

Human note: Below, are the Project instructions I gave Claude when considering code, documentation and build instructions. They are not AI-generated and were written by me.

###

I’m really excited to build Clocktopus as it is a hardware MIDI device I have been thinking about for over a decade. I used to play music with lots of musicians in monthly, open community jams and it became part of my practice as a community organiser and musician wanting to meet people and share musical knowledge.

Through this lived experience as a human, there are a few guidelines and values I’d like to consider at the core of Clocktopus:

• Inclusiveness: everyone should be able to play and experiment with music. Like food or culture, it knows no borders and can connect us with our ancestors with messages for the future. We should also get a chance at this work and care.
• Playfulness: things should be fun and exciting to play with for all genders and abilities.
• Non-dominating language: ‘master’ and also ‘slave’ (often used in MIDI technical documentation has racist connotations and undertones – I’d like to avoid this)
• Appreciation and respect for animals. Especially the incredible octopus.
• Transcultural musical respect: deep, deep appreciation and respect for the vast array of musical cultures and their expression of rhythm, tuning and collaboration that may not always ‘fit’ within easily discernible musical/cultural biases the developers of Clocktopus may posses (but are always willing to engage and learn from)
• Curiosity: if someone else (through the GPL 3.0 license) copies and improves upon Clocktopus, how else might they consider bringing their own musical/cultural experience to bare on the code, design and hardware of the Clocktpus? This will always be an open (and welcome!) question and source of research and appreciation. Clocktopus’ accessibility for people with different abilities (perhaps no use of their hands or trouble seeing clearly) also bode for enriching technical research and cultural exchange.
• Toxic supply chains: awareness that sometimes hardware may have some toxicity in it’s supply chain (and we’ll do our best to avoid that)
• Non-ethical supply chains: awareness that sometimes hardware may have ethical sourcing issues in it’s supply chain (and we’ll also do our best to avoid that)

Clocktopus is not here to ‘make people feel powerful’ or ‘stand out’ it’s really more to encourage people to play and learn together – particularly with the fun name combining ‘clock’ and ‘octopus’. Perhaps as a tentacle on an organism that moves in concert with the rest of itself. A clock is certainly a human-construct which can be helpful to encourage people working/creating together through maintaining a shared sense of time (which in and of itself has a rich variety of cultural understandings). An octopus is an incredibly fascinating creature who we are still learning new things about.

Analogies, code, firmware, product descriptions, materials and hardware decisions which reflect these values and curiosities should be enshrined in the development of Clocktopus. They should not easily bending to often extractive, colonial, exploitative or manipulative market conditions or trends in the pursuit of profit over the health of the planet, neighborhoods or communities we inhabit (and ideally thrive in!).

Clocktopus does have a thoughtful , ethical context, but this also doesn’t have to be so blatant unless there is a compelling reason to include or highlight it to speak to audiences and customers whose values align with the product – and might want to support the project in some way, particularly financially in the first few years after the first hardware prototype is made. I realise this may not always be easy to balance, but I believe it’s something that ultimately will lead to a better product and ultimately joyful music sessions between performers and the devices they play together with. We would like to make this project sustainable financially, socially and terrestrially and most importantly – FUN.

About

AI Note: After describing the device (I’ve spent many years talking about with others), I had a pretty good idea of the features. Below is the output of a conversation with Claude, but then refined by me. Claude still has a ‘style’ of talking that I’m not too fond of, so I worked to shape this text a bit more after it summarized things.

###

Clocktopus is a small, friendly device that allows up to 8 electronic instruments to play together — in time and in sync.

If you’ve ever tried to get two or more electronic instruments, drum machines, sequencers, or synthesisers to lock into the same rhythm at the same time, you’ll know the frustration: mismatched sync rates, incompatible ports or even tempo drifts. By the time you’ve found some kind of compromise amidst troubleshooting your sync issues, you’re out of breath, your inspiration ensnared.

Clocktopus solves this. Plug it in, connect your gear and press the glowing start button. Up to 8 of you (or your band’s) instruments undulate together to the tempo-locked, pulsing glow. Adjust the big, chunky tempo dial and your session’s instruments speed up and slow down, breathing as one.

At the heart of Clocktopus lies a precise, high-resolution clock timer that sends stable, jitter-free sync signals to its 8 ports. Each port can be independently configured to send time-shifted, rhythmic subdivisions (with swing) to either a 3.5mm TRS MIDI or CV/gate jack output, ensuring seamless sync compatibility (and playability!) across various MIDI, Eurorack, and boutique instruments.

Finally, with it’s open-source firmware, you can fine-tune Clocktopus’s existing features or add entirely new ones: think tempo-synced, CV LFO output or odd time signatures per port. Or perhaps you’d want to add a different clock or polyrhythmic system based on West African djembe cycles, Indian tala systems, or Indonesian gamelan. Musical curiousity is encouraged.

Clocktopus easily syncs your gear so you can play with other people seamlessly….

Feature List

AI Note: After giving Claude a Skill in learning Arduino, C+ and learning about Teensy 4.1, I gave Claude my features and then asked for clarification when I didn’t understand something. I also asked Claude to not ‘assume’ anything for ‘big’ decisions and ask me to think critically about some of the hardware and UI directions. I then asked Claude to confirm it’s understanding of Clocktpus by generating this feature list. Getting clear on this upfront helped write the code much better – always plan before asking AI to write code!

###

Connectivity

• 8 independent clock outputs — each individually configurable as either MIDI or CV/gate clock
• MIDI outputs via 3.5mm TRS Type A jacks — the current standard across modern hardware synthesisers, sequencers, and drum machines
• Eurorack CV/gate outputs — 5V pulse clock compatible with modular synthesiser systems
• Included adapters — TRS Type A to DIN (5-pin) and TRS Type A to Type B, so Clocktopus works with everything you already own
• USB connection — powers the device and doubles as a USB MIDI output to your computer or DAW

Timing & Sync

• Tempo range — 20 to 300 BPM
• Internal high-resolution clock — 96 pulses per quarter note internal resolution for precise, stable timing across all outputs
• Sub-microsecond timing jitter — hardware timer-driven clock engine for the tightest possible sync
• MIDI clock output — standard 24 PPQN on all MIDI-configured ports, compatible with virtually every MIDI device ever made
• Start, Stop, and Continue — full MIDI transport control sent to all connected devices simultaneously

Rhythm & Feel

• Per-port time shift — +/-1 millisecond adjustment to bring signals forward or delay them
• Per-port clock division — each output independently set to its own rhythmic subdivision:
  • Whole note (1 pulse per bar)
  • Half note
  • Quarter note
  • 8th note
  • 16th note
  • 32nd note
  • MIDI rate (24 PPQN raw)
  • Volca preset (Korg Volca-compatible sync pulse rate)
• Per-port swing — independently adjustable groove offset per output, from straight (50%) to heavy swing (90%), so individual instruments can feel different while staying locked together
• Tap tempo — set the tempo by feel, by tapping in time

Live Performance

• One-button Start / Stop — large illuminated button for confident stage use
• Double-press Resync — tap twice quickly to snap all outputs back to beat one without stopping playback; useful for correcting device-originating drift or re-locking after a transition

Visual Feedback

• Colour-coded Start / Stop Button — red for clock stopped, green for clock running
• 8 independent RGB LEDs — one per output, each pulsing at that port’s own clock rate so you can see the rhythmic structure of your whole setup at a glance
• Colour-coded by output type — blue glow for MIDI outputs, green glow for CV outputs, white flash for main clock pulse
• OLED display — shows current BPM, running/stopped status, selected port, and all per-port settings; three-level navigation menu for configuring each output

Controls

• Tempo dial — large dedicated rotary dial for BPM adjustment; fine (0.5 BPM) and coarse (5 BPM) modes
• Navigation encoder — push-turn encoder for navigating and editing all per-port settings without menus getting in the way of playing
• Three-level settings hierarchy — select port → select parameter → edit value; long-press returns to the top level from anywhere

Per-Port Settings (configurable per output)

• Output type: MIDI or CV
• Time shift
• Clock division / subdivision
• Swing amount
• Enable / disable

Enclosure & Design

• Faceted dome enclosure — distinctive half-sphere form, stable on any surface, designed to be as wonderful to look at as to use
• Open hardware and firmware — the full design and code are openly available; Clocktopus can be understood, repaired, and modified by anyone with the curiosity to look inside

Compatibility

Works with any device that accepts:

• MIDI clock via 3.5mm TRS (Type A or Type B via included adapter)
• MIDI clock via 5-pin DIN (via included adapter)
• Eurorack CV/gate clock (5V pulse)

Including but not limited to: synthesisers, drum machines, sequencers, samplers, arpeggiators, Eurorack modular systems, DAWs (via USB MIDI), and Korg Volca series (via Volca preset).

In the Box

• Clocktopus device
• TRS Type A to 5-pin DIN adapter cable
• TRS Type A to TRS Type B adapter cable
• USB cable
• Manual

Resources

AI Note: The firmware and appendix below were AI-generated from a few iterations using Claude, after I wrote the Instructions and got clear on the features. There are musicological/cultural references within the appendix which need to be reviewed, but I thought the output was pretty ‘good’ (I realize this is subjective, but maybe you can review and think for yourself).

###