Creating your own effects - clevelandmusicco/HothouseExamples GitHub Wiki

Overview

In the root of the HothouseExamples repository there is a helper script named create_new_proj.py. You can use this script to "bootstrap" a fresh new effect project, complete with all of the necessary includes, bypass logic, and the minimum files needed for a VS Code project with basic tasks and debug capabilities. Of course, you don't have to use this script; if you've got the knowledge to do everything from scratch, rock on! :metal:

Prerequisites

  • Python 3.x - The helper script and the commands on this page have been tested with Python 3.10.14 and Python 3.12.3. It's assumed you've aliased one of these versions to the local python command, but adjust the commands as needed. (For example, python3.12 create_new_proj.py might work on your system.)

Using create_new_proj.py

Use the create_new_proj.py helper script to create a bare effect project in the src dir:

python create_new_proj.py -h
usage: create_new_proj.py [-h] --proj_name PROJ_NAME
                              [--your_name YOUR_NAME]
                              [--your_email YOUR_EMAIL]

options:
  -h, --help            show this help message and exit
  --proj_name PROJ_NAME
                        Name of the new project in camelCase or PascalCase.
  --your_name YOUR_NAME
                        Your name for use in the license and README.
  --your_email YOUR_EMAIL
                        Your email address for use in the license and README.

[!NOTE] --your_name and --your_email are optional. If they are omitted, the literal strings Your Name and your@email will be used in the new project code. Specifically, they will appear in the comments of the main .cpp file and in the generated README.md.

cd HothouseExamples
python create_new_proj.py --proj_name MyAwesomeEffect \
                          --your_name "John Developer" \
                          --your_email [email protected]

You should see output similar to this:

Creating src/MyAwesomeEffect/Makefile ...
Creating src/MyAwesomeEffect/README.md ...
Creating src/MyAwesomeEffect/my_awesome_effect.cpp ...
Creating src/MyAwesomeEffect/.vscode/.cortex-debug.peripherals.state.json ...
Creating src/MyAwesomeEffect/.vscode/.cortex-debug.registers.state.json ...
Creating src/MyAwesomeEffect/.vscode/STM32H750x.svd ...
Creating src/MyAwesomeEffect/.vscode/c_cpp_properties.json ...
Creating src/MyAwesomeEffect/.vscode/launch.json ...
Creating src/MyAwesomeEffect/.vscode/tasks.json ...
Done!

This results in a new directory under src with this structure:

src/MyAwesomeEffect
├── Makefile
├── my_awesome_effect.cpp
├── README.md
└── .vscode
    ├── c_cpp_properties.json
    ├── .cortex-debug.peripherals.state.json
    ├── .cortex-debug.registers.state.json
    ├── launch.json
    ├── STM32H750x.svd
    └── tasks.json

Straight away, the project can be compiled and flashed as usual, but until you add your own code, the new effect will just write silence to the output when not bypassed. By default, AudioCallback() looks something like this (note the TODO comment):

void AudioCallback(AudioHandle::InputBuffer in, AudioHandle::OutputBuffer out,
                   size_t size) {
  // Stuff omitted for brevity

  for (size_t i = 0; i < size; ++i) {
    if (bypass) {
      // Copy left input to both outputs (mono to dual-mono)
      out[0][i] = out[1][i] = in[0][i];
    } else {
      // TODO: replace silence with something awesome
      out[0][i] = out[1][i] = 0.0f;
    }
  }
}

Build your new effect as you would any other:

cd src/MyAwesomeEffect
make clean
make

Now flash the Hothouse with program-dfu for USB or program for JTAG/SWD.

Flash via USB (DFU)

make program-dfu

Flash via JTAG/SWD

make program

Your new effect will also be automatically recognized by the build_examples.py helper script, and will be built along with all the other examples when running the script.

[!TIP] When executed, the create_new_proj.py script copies content from a template project directory while replacing some string tokens along the way. The template project is in resources/_template and can be customized to your liking.

The README file

The script will give you a README.md file with a suggested template for describing your effect and how the Hothouse hardware interacts with it. If you specified your name and email with the --your_name and --your_email parameters, you'll see them near the top of the file.

image
README.md in the VS Code Preview window

[!NOTE] This is the preferred format if you plan to submit a pull request for your effect to be included in the HothouseExamples repository!

Tips for programming the Hothouse

This is a living list of tips submitted by customers and some general pointers on getting the most out of the Hothouse.

More coming soon...