Hacking Mutable Instruments Plaits

This should also get you started with other Mutable STM32F modules including Elements, Warps, Marbles and Clouds.

If you don't feel like going through all this rigamarole, you can download a wav of the firmware instead.

Download Just Intonation Chords Firmware for Plaits

What you’ll need

If you don’t want to scratch your module’s faceplate, maybe get a spanner head screwdriver like this.

I’ve made Amazon Affiliate links here, so I get a bit of money (eventually, maybe) if you buy anything via this page. The downside is Bezos gets paid too, but that’s quite hard to avoid these days isn’t it?

YouTube Video






Instructions on the Mutable Website

Here are the instructions on the Mutable Instruments website:
https://mutable-instruments.net/modules/plaits/open_source/

The important bits are:

If you don’t mind installing Vagrant and VirtualBox a cozy environment for firmware hacking is available.

See step 1 below for details on what this means and how to do it.

Then (at time of writing) it says:

Firmware programming
The recommended solution for firmware programming is to use a ST Discovery board.
Connect the 4 SWD lines of the board to the 4 programming lines of Plaits (RESET, SWDIO, SWCLK and GND).
Make sure that the programming interface (PGM_INTERFACE variable) is set to stlink-v2 in stmlib/programming.inc.
Upload the firmware with:
make -f plaits/makefile upload

There’s a lot to unpack here. And it wasn’t quite right in my case so I’ll share my findings along with the more detailed steps below.

Disclaimer

I am in no way responsible if you break something following this guide. The steps below are indicative of the journey I took and should not . This is not 100% straightforward so please be careful.

1. Set up VirtualBox

First you have to get get VirtualBox and the Mutable Dev Environment up and running.

  1. Get Git
  2. Get the Mutable Dev Environment
  3. Get VirtualBox and VirtualBox Extension Pack
  4. Get Vagrant
  5. Run vagrant up
  6. Jump in with vagrant ssh

I covered this in much more detail in my previous video where you can follow along until about 4:00 before coming back here.






https://youtu.be/Eex-iLuUdiw

2. Solder a New Connector onto Plaits

Unlike Grids, Plaits does not come with a header to connect a programmer. This was to cut costs apparently. So we need to solder a header on the back.

2.1 Disassemble Plaits

Plaits, disassembled Plaits, disassembled

2.2 Solder in a header

You need to solder a four pin header to the board at the location shown below:

It goes here It goes here

Board with soldered-on Blue header Board with soldered-on Blue header

2.3 Reassemble the module

3. Connect Plaits to Development Board

As per the instructions we need to:

Connect the 4 SWD lines of the board to the 4 programming lines of Plaits (RESET, SWDIO, SWCLK and GND).

3.1 Identifying Pins on Plaits

These aren’t labelled on the board itself but I found the labels in the PCB design. I used the free EAGLE app to view the PCB.

Top-to-bottom: RESET, SWCLK, SWDIO, GND Top-to-bottom: RESET, SWCLK, SWDIO, GND

3.2 Identifying Pins on Development Board

I checked the user manual for my board to see how to connect it, searching for SWD in the document.

So I saw that

  1. The four pins Plaits needs (RESET, SWDIO, SWCLK and GND) are available on pins 5, 4, 2 and 3 respectively - with pin 1 marked •
  2. I needed to take off some jumpers to enable “debug mode”

3.3 Using Jumper Cables to Connect the Boards

Carefully cross-reference the two guides and use jumper cables to connect each pin to its counterpart of the same name on the other board.

I would recommend making sure at least one side uses the leads in-order so it’s easy to disconnect and reconnect without checking the pin diagrams again.

4. Connect Board to Dev Environment

4.1 Connect Development Board to Computer via USB

There might be multiple USB ports so make sure you connect the right one

4.2 Verify that you host machine can see the device

My board showed up as an external drive on macOS when I plugged it in.

You could also check About This Mac to look for it under USB.

4.3 Verify that the device is available to VirtualBox

Jump into the dev environment:

$mac vagrant up
$mac vagrant ssh

Then inside the dev environment type lsusb

vagrant@vagrant-ubuntu-trusty-64:/vagrant/eurorack-modules$ lsusb
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub

If you don’t see anything that says something like ST-LINK--* then your board probably isn’t connected.

Launch the VirtualBox app, select the mutable-dev-environment and click USB to see the device whitelist.

Click the “Add Device” button Click the “Add Device” button
Your board should be available to add Your board should be available to add

Then you need to restart the VM and try lsusb again.

$vagrant exit
$mac vagrant halt # stop virtual machine (VM)
$mac vagrant up # start VM
$mac vagrant ssh # log into VM
$vagrant lsusb # list connected usb devices
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 002: ID 0483:374b STMicroelectronics ST-LINK/V2.1 (Nucleo-F103RB)
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub

My board showed up as ST-LINK/V2.1 (Nucleo-F103RB).

4.4 Make sure Plaits is Still Happy

If Plaits isn’t responsive when plugged in, you might need to disconnect the jumper cable, turn your rack off and on again and then reconnect to the development board.

Plaits should run okay once it’s connected.

On the website the instructions say this:

Make sure that the programming interface (PGM_INTERFACE variable) is set to stlink-v2 in stmlib/programming.inc.

But this isn’t quite right.

More up-to-date instructions for setting PGM_INTERFACE are available on the Github repo.

Using a different programmer
To use a programmer other than the default (AVR ISP mkII, ARM-USB-OCD-H) it is no longer necessary to edit the makefiles. Instead, the programmer can be set in the shell for the current session, e.g.

export PGM_INTERFACE=stlink-v2

export PGM_INTERFACE_TYPE=hla

You also need to match the stlink version with your board

My board is named STMicroelectronics ST-LINK/V2.1 (Nucleo-F103RB) so it turned out I needed this: 

export PGM_INTERFACE=stlink-v2-1

I found all the possible devices here in OpenOCD in case you’re wondering.

5.2 Build and Upload

Now you now upload firmware with 

> make -f plaits/makefile upload

It takes a few seconds during which you should see light flashing on your development board. Plaits will be unresponsive until the upload is complete.

The state of my rack when I got the upload to work The state of my rack when I got the upload to work

We did it!

Now we can try some new code…

6. An Easy Change

You can change Plait’s chord arrangement by uncommenting one line of code in plaits/dsp/engine/chord_engine.h.

Change this:

// #define JON_CHORDS

to this:

#define JON_CHORDS

Then upload this with: 

> make -f plaits/makefile upload

You will now have a new chord layout in the Chords engine, described here.

7. How I Implemented Just Intonation

I referenced this page to create an array of Just Intonation ratios based on the JON_CHORDS layout, like so:


This array is called chordsAsRatios so I replaced the call to SemitonesToRatio to use the defined ratios directly.

// OLD CODE: ratios_\[i * kChordNumNotes + j] = SemitonesToRatio(chords[i\][j]);
// NEW_CODE:
ratios_[i * kChordNumNotes + j] = chordsAsRatios[i][j]; // NEW CODE

Here it is on Github, with the main commit being here.

Or if you just want to try it out, download the wav below. Otherwise, hopefully see you on my Twitch soon!

Download Just Intonation Chords Firmware for Plaits

Home

More Stuff from Michael Forrest / Good To Hear