Development setup¶

Two toolchains, and you need the second only for hardware:

The simulator: CMake and a C++17 compiler. Enough for writing and testing machines and plugins.
ESP-IDF for the ESP32-P4: to build the firmware and flash it over USB.

No debug probe is needed. RP2350 apps use PlatformIO instead: see App Development Setup.

Get the source¶

git clone --recursive https://github.com/dadamachines/ctag-tbd.git
cd ctag-tbd

The --recursive flag fetches the submodules (Ableton Link, esp-dsp, the simulator’s audio and web libraries). If you cloned without it:

git submodule update --init --recursive

The simulator¶

You need CMake 3.13 or newer, a C++17 compiler and Boost (thread, filesystem, program_options).

macOS (Homebrew):

brew install cmake boost

Linux (Debian/Ubuntu):

sudo apt install build-essential cmake libboost-filesystem-dev \
  libboost-thread-dev libboost-program-options-dev libasound2-dev

Windows (MSYS2) is described in simulator/readme.md.

Build and run:

cd simulator && mkdir -p build && cd build
cmake .. && make tbd-sim
./tbd-sim --list              # the sound cards and their numbers
./tbd-sim --device <N>        # <N> from the list

The simulator needs a sound card at 44.1 kHz; --output uses an output-only device.

Page	What it is
`http://localhost:8080/`	The WebUI: the plugins and the rack’s machines with their parameters.
`http://localhost:8080/ctrl`	MIDI for the `GrooveBoxRack`; CV, triggers and pots for CTAG plugins.

make without a target also builds the DSP unit tests (run_tests) and the headless tools (load-test, routing-test, rack-lint). The Desktop simulator page has the details.

ESP-IDF for the ESP32-P4¶

The firmware builds with ESP-IDF v5.5.3 (the repository’s CI builds in the espressif/idf:v5.5.3 image) and needs xxhash for its SD card checksums.

mkdir -p ~/esp && cd ~/esp
git clone -b v5.5.3 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32p4

brew install xxhash          # macOS; on Linux: sudo apt install xxhash

On Windows use Espressif’s ESP-IDF Tools Installer.

Build the firmware¶

In every new terminal, load ESP-IDF first:

. ~/esp/esp-idf/export.sh

Then, from the repository root:

idf.py build

This builds the TBD-16 configuration (SD card and RP2350). The build writes build/dada-tbd.bin (the app), the bootloader, the partition table, the OTA data and build/dada-tbd-sd.zip (the SD card archive). The first build takes several minutes; later builds are incremental. Other hardware configurations are built with an overlay, for example idf.py -DSDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.defaults.tbd-sd-only" build; HARDWARE_CONFIGURATIONS.md in the repository lists them. When you switch configurations, run idf.py fullclean first.

Next: Flash your build.

Troubleshooting¶

“Missing xxh128sum”: Install xxhash (see above).
Errors about missing files in a submodule: Run git submodule update --init --recursive.
``idf.py`` not found, or the wrong ESP-IDF version: Run . ~/esp/esp-idf/export.sh in this terminal; idf.py --version should say v5.5.3.
A new machine or plugin does not appear in the simulator: Re-run cmake .. once so that the new source file is found, and see Registering a New Plugin on the Desktop simulator page.