Braids – Open source

Braids is open-source. The code and hardware files can be found in the braids directory in our Eurorack modules git repository.

After having cloned the repository, don’t forget to run git submodule init && git submodule update to make sure the sub-projects referenced in the code are also pulled.

Firmware hacking

Playground

A simple way of testing the oscillators code locally on a desktop computer, without long flash/test cycles, is to use the command line program in braids/test. It can be built and run with make -f braids/test/makefile && ./oscillator_test. No embedded toolchain is needed for that! The program generates a .wav file, oscillator.wav. Playing with the methods of the MacroOscillator class is a good way of familiarizing oneself’s with Braids code.

Toolchain

To build Braids’ code, an ARM EABI toolchain must be installed. We recommend jsnyder scripts (which include a lot of useful extras).

The path to the toolchain binaries must be specified in the TOOLCHAIN_PATH variable in makefile.inc.

To build the code, use the following command:

make -f braids/makefile

If you modify lookup tables and want the big resources.cc file to be regenerated:

touch braids/resources/resources.py && make -f braids/makefile resources

Updating the firmware

A first solution is to simply use the firmware update procedure. A .wav file for firmware upgrade can be generated with:

make -f braids/makefile wav

The firmware can then be loaded into the module using the procedure described in the manual.

Past this point, we assume you know what you are doing and we are not responsible for any damage to your module!

Another solution is to use the built-in serial bootloader of the STM32F. Connect a FTDI dongle with a 3.3V output level (such as this) to the 6 pin connector at the back of the module. If necessary, edit the serial port special file corresponding to the FTDI dongle in the PGM_SERIAL_PORT variable in stmlib/makefile.inc. GND must match GND, TX must match RX and vice-versa.

Hold the RESET switch on the side of the module. Press the SYSBOOT switch next to it, and release RESET. Nothing is shown on the module display (it is in bootloader limbo…)

Upload the firmware with:

make -f braids/makefile upload_combo_serial

The last – and recommended – solution for firmware updating is to use a JTAG interface and openOCD. We recommend Olimex’ ARM-USB-OCD-H devices. Their older ARM-USB-OCD product is also known to work – and is in the fact used for factory programming. Configuration data for both are listed in stmlib/programming/jtag/interface.cfg – uncomment the one which is not needed.

An adapter must also be purchased for the mini-JTAG connector used by Braids. The red stripe of the mini-JTAG connector must be on the same side as the JP2 marking on the board.

Upload the firmware with:

make -f braids/makefile upload_combo_jtag

Hardware hacking

Schematics, board layout and panel files can be found in the braids/hardware_design directory of the github repository. For expansion projects, we recommend using the 3.3V UART RX/TX lines at the back of the module. Access to two GPIO pins on the back of the module (X0, X1) is also provided.

The hardware description files are released under a cc-by-sa-3.0 license. The source code is released under the MIT license.

Olivier Gillet, Mutable instruments SARL 2011-2017. Except where otherwise noted, content on this site is licensed under a cc-by-sa 3.0 license.