API reference

Everything a firmware can use: manifest, callbacks, platform calls, log, load.

Everything a firmware can use, in one place. The headers are the full reference (every function has its comment there); this page is the map. New here? How a firmware works first. Guides: parameters, UI kit, audio link, performance, debugging, simulator, releasing, storage, fonts, questions.

headerprocessorwhat
platform/nds32/gp5_firmware.hcontrol (NDS32)callbacks, controls, screen, LEDs, storage, log, audio link
platform/nds32/gp5_font.hcontrolsmooth text in any font (fonts.md)
platform/nds32/gp5_ui.hcontrolthe UI kit: a settings page, a menu, value text, messages, knob pickup (ui.md)
platform/dsp/gp5_dsp.hDSP (Cortex-M4F)fw_init, fw_process, fw_command, log, audio link, cycle counters
platform/dsp/gp5_params.hbothparameters and presets (params.md)
platform/dsp/gp5_math.hbothsinf, expf, logf, tanhf, … (neither processor has a C library)
platform/dsp/gp5_fmt.hbotha small printf (gp5_log uses it)

A firmware is a folder with a firmware.json; the build refuses one without it. (The 0.6 API, for firmwares without one, was removed in 0.8.)

A firmware’s folder

my-effect/
  firmware.json        who it is and what it needs (below)
  params.h             its parameters (optional; params.md)
  dsp/firmware.h       the sound: fw_init, fw_process, fw_command, fw_param      (gp5_dsp.h)
  nds32/*.c            screen and controls: fw_draw, fw_foot_down, ...          (gp5_firmware.h)

The folder can live under firmwares/ or in its own repository with OpenGP5 as a git submodule; then give the build its path instead of a name. The quickest start for your own repository is the firmware template: it builds, tests itself in the simulator on every push (GitHub Actions), publishes releases from tags, and opens ready to build in GitHub Codespaces. firmwares/tremolo is the example that uses all of it.

firmware.json

{
  "id": "tremolo",
  "name": "Tremolo",
  "version": "1.0.0",
  "author": "OpenGP5",
  "url": "https://github.com/OpenGP5/OpenGP5",
  "licence": "MIT",
  "description": "The volume rises and falls.",
  "platform": "0.8",
  "presets": 4
}
field
idrequiredlowercase letters, digits and -, up to 31. It names the firmware’s storage: a firmware with another id starts with empty storage, so keep it once released
namerequiredshown by Launchpad and the web flasher
versionrequired1.2.0 or 1.2.0-beta.1
author, url, licence, descriptionoptionalshown by Launchpad (Version / By on the Pedal page)
platformoptionalthe API version it was written for, major.minor; the build refuses a newer minor or another major
presetsoptionalhow many presets the platform keeps for it, 0..64 (params.md)
audio.sample_rateoptional44100 (default) or 48000
audio.linkoptionaltrue: the audio link between the processors (below)
audio.link_wordsoptionalwords each way per block, a multiple of 8 up to 512 (default 128; sets link)
audio.link_earlyoptionalstart the link at boot, before the firmware’s fw_init
control.mhzoptional288 (default) or 320: the control processor’s clock (11 % more cycles)

python3 platform/manifest.py <folder> --check checks it and prints what it says. The build turns it into defines both processors see (GP5_FW_ID, GP5_SAMPLE_RATE, GP5_CTL_MHZ, GP5_AUDIO_LINK, GP5_LINK_WORDS, GP5_PRESETS, GP5_HAS_PARAMS), and puts the manifest in the image as a metadata block, so Launchpad, the web flasher and gp5tool.py info <file.bin> know what a .bin is before it is flashed, and the pedal says what it runs (USB 7E 16).

Control processor: what the platform calls

All optional: the platform has an empty default for each. All run in the main loop, one after the other, so none of them may wait (a loop that waits more than 2 s turns the LEDs full red).

callbackwhen
void fw_init(void)once at start-up, after the storage claim and the saved parameters are loaded
int fw_draw(int force)every pass: draw part of the screen with gp5_blit; return non-zero while more is left. force = draw everything
void fw_tick(void)every 10 ms
void fw_foot_down(void) / fw_foot_upthe foot switch, debounced (30 ms)
void fw_para_down(void) / fw_para_upthe PARA knob pushed / let go
void fw_para_click(void)a push let go within 0.6 s (just before fw_para_up)
void fw_para_hold(void)a push held 0.6 s (once, while still held; no click follows)
void fw_para_turn(int detents)PARA turned, + clockwise
void fw_param_changed(unsigned id)a parameter changed from outside: the computer, a preset load (params.md)
int fw_param_text(unsigned id, int32_t v, char *text)the text of a GP5_U_CUSTOM value, up to 15 characters
void fw_storage_changed(void)the computer changed this firmware’s files or records: read them again
int fw_param_get/fw_param_set(uint32_t id, ...)the firmware’s own live ids past its parameters (Dreamcatcher’s preset commands)

Control processor: what a firmware may call

call
gp5_knob()the volume knob, 0..255, filtered
gp5_ms()milliseconds since start
GP5_CYCLE_COUNT()the core’s cycle counter, for timing code (performance)
gp5_level_own(1), gp5_level_set(0..255)take over the output level (by default the volume knob sets it)
gp5_led(GP5_LED_ON / GP5_LED_BYPASS / GP5_LED_RGB(r, g, b))the LEDs: mint (default), dim red, or a colour (0..32 each)
gp5_blit(x, y, w, h, px)pixels to the 160 × 80 screen (gp5_color(0xRRGGBB) makes one)
gp5_text(line, s)the built-in 5×7 font, 5 lines of 13 characters
gp5_draw_text, gp5_text_at, gp5_text_widthsmooth text (gp5_font.h, fonts.md)
gp5_param, gp5_param_set, gp5_preset_*parameters and presets (params.md)
gp5_ui_page_*, gp5_ui_menu_*, gp5_param_format, gp5_pickup_*the UI kit (ui.md)
gp5_store_save(id, p, len) / gp5_store_load(id, p, max)a record of up to 1 KB, kept across power-off (storage.md)
gp5_file, gp5_file_check, gp5_file_eachfiles the computer wrote (captures, IRs): read straight from flash
gp5_log(fmt, ...)a line for the log (below)
gp5_link_start(on_block)start the audio link (below)

DSP

One header, dsp/firmware.h, compiled into the platform’s DSP program:

static void fw_init(void)once, before audio starts
static void fw_process(const int32_t *in, int32_t *out_left, int32_t *out_right)every block: 64 samples, mono in, stereo out, full scale ±2³¹. The platform applies the output level afterwards
static void fw_param(uint32_t id, int32_t value)a parameter changed, before the next fw_process (a firmware with params.h defines it, even empty)
static int fw_command(uint32_t cmd, const uint8_t *p, uint32_t n)the firmware’s own link commands from 0x7F11; return 0 for one it doesn’t know

It may use gp5_param(id) (the current value), gp5_reply / gp5_ack (answer a command), gp5_log, gp5_link_in() / gp5_link_out(), GP5_LARGE (put a buffer in the 122 KB block; ordinary variables have 19.5 KB), GP5_CYCLES_LAST, GP5_CYCLES_WORST, GP5_LATE_BLOCKS, GP5_CYCLE_COUNT() (the core’s cycle counter now, for timing a piece of code), and GP5_FAST (put a function that runs for every sample in RAM: performance).

Budget: about 278,000 cycles per block at 44.1 kHz (255,900 at 48 kHz). Code runs from flash unless you put it in RAM; see “Speed” in platform/README.md.

With "audio": {"link": true} both processors exchange link_words 32-bit words after every block. On the control processor, gp5_link_start(on_block) (in fw_init) makes on_block(in, out) run in an interrupt once per block: keep it shorter than a block. On the DSP, gp5_link_in() holds what arrived and gp5_link_out() takes what to send. Words take two exchanges to arrive. This is how NAM Loader and Dreamcatcher run part of their sound on the control processor.

Log

gp5_log("rate %ld, depth %d %%", rate, depth) on either processor. printf-style (%d %u %x %s %c %f, width, precision; gp5_fmt.h), at most about 110 characters a line, stamped with the time. The control processor keeps the last 4 KB; the DSP’s lines travel over the link and are marked dsp:. uint32_t is a long on both processors: print it with %lu / %lx. A DSP line costs a few thousand cycles: not every block.

python3 tools/gp5_link.py log -f        # follow it while you play

On the computer (tools/run_effect.py) the DSP’s gp5_log prints to the terminal.

Load and memory

python3 tools/gp5_link.py status [--reset]

shows, for both processors, the cycles per block used (last and worst), the main loop’s longest pass, late blocks and memory in use. --reset starts the worst values again. Check it with the heaviest settings before a release.

Trying things without a pedal

python3 tools/simulate.py tremolo --script controls.txt --in guitar.wav

runs the whole firmware on the computer, both halves and the audio link, with scripted controls, the screen as PNGs and the sound as a WAV (the simulator). For the DSP half alone, tools/run_effect.py is quicker: python3 tools/run_effect.py tremolo in.wav out.wav --set Rate=800 --set Shape=Square.

Talking to a running firmware

gp5_link.py infothe firmware’s name, version and author
gp5_link.py paramsits parameters, values and ranges
gp5_link.py set Rate 800set one (a choice by name: set Shape Square)
gp5_link.py presets, preset load / save / name <n>its presets
gp5_link.py log [-f], statusabove

Launchpad’s Live page shows the same for any firmware with parameters. The USB commands behind them are in protocols.md.

Versions

The platform’s version is GP5_VERSION_TEXT in gp5_firmware.h; firmware.json’s platform says which API a firmware needs. Until 1.0 final the API may still change; after it, a minor version only adds.

What 1.0 promises, for all of 1.x:

  • a firmware written for 1.0 builds and behaves the same: every name on this page, every callback and when it is called, every firmware.json field;
  • what a pedal has saved stays readable: parameters and presets, store records, files;
  • the USB commands keep their meaning and only grow at their end (protocols.md), so older tools keep working.
  • the memory a firmware has never shrinks: the platform stays within its share (known-limits.md lists the firmware’s; tools/check_budget.py checks it in CI).

The examples as released with 1.0 are kept in compat/1.0 and tested against every change (tools/test_compat.sh, CI). If something has to go, it is marked first: using it warns when you build (GP5_DEPRECATED) for at least a whole minor release, and only a 2.0 removes it. Not promised: the platform’s internals, the layout of the UI kit’s structs beyond the fields you set, and limits that only grow (link words, presets, store size).