Building and Running

Building with CMake

The easiest way to build BitMasher source code is by using CMake.

Building BitMasher requires the GNU ARM Embedded Toolchain and the ARM CMSIS library. Additionally, BitMasher depends on the MW_AudioFX library for the DSP elements which can be found here.

Once CMake and the dependencies are downloaded, set the appropriate variables in the included CMakeLists file with the correct paths:

set(TOOLCHAIN_PATH <path_to_toolchain>)
set(MW_AUDIO_FX_PATH <path_to_mw_audio_fx_files>)
set(CMSIS_PATH <path_to_cmsis_lib>)

Next, in a command line terminal go into the BitMasher directory, create a build directory and go into it:

$ mkdir build
$ cd build

Then run the CMake configuration:

$ cmake ..

Finally, build the source:

$ make all

The BitMasher.axf executable should appear in the build directory.

Building BitMasher in Release Mode

The previous instructions built BitMasher source in DEBUG mode (ie with no compiler optimizations enabled). To build with compiler optimizations (-O3), simply enter the following commands:

$ cmake .. -DCMAKE_BUILD_TYPE=Release
$ make all

Running the Executable

There are two ways to upload the BitMasher executable onto the device. The first is through a hardware debugger (JLink, JTAG etc) which will not be covered in this documentation. The second way is through the BitMasher uploader tool.

When using the uploader tool, you will not have any debugging capabilities that a hardware debugger offers (i.e. you will not be able to set breakpoints in code).

The uploader tool is a simple python script that sends the executable over a serial port using the XMODEM protocol. Therefore, before running the script, ensure that you have the pySerial and XMODEM modules installed. If you are using pip:

$ pip install pySerial
$ pip install XMODEM

Set the switch near the top-right of BitMasher to Boot and connect a USB cable from your computer to BitMasher. The device should now be in bootloader mode and nothing should appear on the screen. Next, find the name of the serial port that is connected with BitMasher. On MacOS, you can do this by typing the following in the command line:

$ ls /dev/tty.*

This will give a list of all devices. BitMasher's serial port will be named something like:


Where xxxxxxxx is a series of alphanumeric characters.

To execute the script and send the binary, type the following into the command line:

python -d /dev/tty.usbserial-xxxxxxxx -f /path/to/binary/BitMasher.axf

After the upload finishes, set the top-right switch on BitMasher to App and press the reset button found on the bottom-left of the device. The binary should now run.