The UI kit

A settings page, a menu, value text, messages and knob pickup.

platform/nds32/gp5_ui.h: the screen and control pieces most firmwares need, built on parameters. Everything here is optional. A firmware with its own look, like Dreamcatcher, uses none of it or only some of it. A firmware that doesn’t use the kit doesn’t carry it: its image is the same with or without the kit.

piecedoes
gp5_param_format()a value as text, the way Launchpad shows it
gp5_ui_page_ta settings page: a row per parameter, PARA picks and adjusts
gp5_ui_page_message()a short message in the page’s last row
gp5_ui_menu_ta menu of actions: PARA picks, a click runs one, risky ones ask “Sure?” first
gp5_pickup_tthe volume knob takes over a parameter without a jump

A settings page

#include "gp5_ui.h"
#include "fonts/sans_16.h"

static const uint8_t rows[] = { GP5_P_RATE, GP5_P_DEPTH, GP5_P_SHAPE, GP5_UI_PRESETS };
static gp5_ui_page_t page = { .rows = rows, .n = 4, .font = &gp5_font_sans_16, .row_h = 20, .upper = 1 };

void fw_para_turn(int d) { gp5_ui_page_turn(&page, d); }
void fw_para_click(void) { gp5_ui_page_click(&page); }
int fw_draw(int force)   { return gp5_ui_page_draw(&page, force); }

The tremolo’s page

How it works on the pedal:

  • Turn PARA to pick a row. The row picked is highlighted, and the page scrolls when there are more rows than fit.
  • Click to adjust it. A bar on the left and < > around the value show you’re adjusting. Turning now changes the value; click again when done.
  • Numbers stop at their range, choices go round, and read-only parameters can’t be adjusted.
  • The presets row (GP5_UI_PRESETS, if the manifest has "presets") shows P2 name, with * when the sound differs from it. Adjusting it loads presets as you turn; empty ones are shown but not loaded. Saving is the firmware’s choice of control. The tremolo saves on a PARA hold:
void fw_para_hold(void)
{
    if (gp5_preset_save(gp5_ui_page_preset(&page))) gp5_ui_page_message(&page, "Saved", 1500);
}

What you can set (leave anything else 0 for its default):

field
rows, nthe rows: parameter ids and GP5_UI_PRESETS. Without rows, every parameter that isn’t GP5_P_HIDDEN, then the presets
stepsper row, how much one click changes it. Default: about 1/50 of the range, rounded to 1, 2, 5, 10, 20 …; values stay on that grid
fontrequired: a font your firmware includes (fonts.md)
row_hrow height; default the font’s line height. sans_16 with 20 px rows gives 4 rows; sans_12 with 16 px gives 5
y, hthe part of the screen the page uses (default: all of it), e.g. below a header you draw yourself
titlea title row at the top
upperlabels in capitals
themecolours: { bg, ink, dim, accent, on_accent } as 0xRRGGBB; default dark grey, white and teal
fadedset to 1 to grey the values out, e.g. while the effect is bypassed; the page redraws when it changes

gp5_ui_page_draw draws one changed row per call and returns non-zero while more are left, like any fw_draw. Return its result from yours. Values that change from elsewhere (a preset load, the computer) show up by themselves. gp5_ui_page_row() tells you which row is picked, for a firmware that wants to show more about it.

A menu

Actions to choose from: save, reset, go back. Turn PARA to pick an item, click to run it. An item marked confirm shows “Sure?” and runs only on a second click; turning away or waiting 3 s cancels. An item’s value() shows text on the right, such as the preset “Save” would write to.

A menu asking to confirm

The tremolo’s page with a menu on a PARA hold (it runs as it is in the simulator):

static const uint8_t rows[] = { GP5_P_RATE, GP5_P_DEPTH, GP5_P_SHAPE, GP5_UI_PRESETS };
static gp5_ui_page_t page = { .rows = rows, .n = 4, .font = &gp5_font_sans_16, .row_h = 20, .upper = 1 };
static int in_menu, switched;                    /* switched: draw everything once after a switch */

static void close_menu(void) { in_menu = 0; switched = 1; }
static void save(void)
{
    if (gp5_preset_save(gp5_ui_page_preset(&page))) close_menu(), gp5_ui_page_message(&page, "Saved", 1500);
}
static void reset(void)
{
    for (unsigned id = 0; id < GP5_NPARAMS; id++) gp5_param_set(id, gp5_param_table[id].def);
    close_menu(); gp5_ui_page_message(&page, "Reset", 1500);
}
static const char *save_slot(void)               /* the preset "Save" writes to: the one the page shows */
{
    static char t[4] = "P1";
    t[1] = (char)('1' + gp5_ui_page_preset(&page));
    return t;
}
static const gp5_ui_item_t items[] = {
    { "Save", save, save_slot, 0 },
    { "Reset all", reset, 0, 1 },                /* asks for a second click */
    { "Back", close_menu, 0, 0 },
};
static gp5_ui_menu_t menu = { .items = items, .n = 3, .font = &gp5_font_sans_16, .row_h = 20, .upper = 1, .title = "MENU" };

void fw_para_turn(int d) { if (in_menu) gp5_ui_menu_turn(&menu, d); else gp5_ui_page_turn(&page, d); }
void fw_para_click(void) { if (in_menu) gp5_ui_menu_click(&menu); else gp5_ui_page_click(&page); }
void fw_para_hold(void) { in_menu = !in_menu; switched = 1; if (in_menu) gp5_ui_menu_pick(&menu, 0); }

int fw_draw(int force)
{
    if (switched) { force = 1; switched = 0; }
    return in_menu ? gp5_ui_menu_draw(&menu, force) : gp5_ui_page_draw(&page, force);
}
item field
labelthe item’s name
runcalled on a click (or the second click, with confirm); 0 for an item that only shows something
valueoptional: a function returning the text on the right; asked whenever the menu draws, so it can change
confirm1: ask “Sure?” first

The menu takes the same font, theme, title, y, h, row_h and upper as the page. gp5_ui_menu_message() shows a message in its last row, gp5_ui_menu_pick() picks an item (the first, say, when the menu opens) and gp5_ui_menu_item() says which is picked.

Value text

char t[16];
gp5_param_format(GP5_P_TIME, gp5_param(GP5_P_TIME), t);     /* "350 ms", "1.50 s" */

It shows choices by name, and the unit as Launchpad does: 50 %, -6 dB, +5.5 dB, 440 Hz, +7 st. For GP5_U_CUSTOM it asks your fw_param_text(), so the screen and Launchpad always agree.

Knob pickup

When the volume knob takes over a setting (Dreamcatcher’s knob does this), the setting shouldn’t jump to wherever the knob happens to be:

static gp5_pickup_t knob;

void fw_init(void) { gp5_level_own(1); gp5_level_set(255); gp5_pickup_start(&knob, GP5_P_MIX); }
void fw_tick(void) { gp5_pickup_poll(&knob); }

Nothing changes until the knob passes the parameter’s current value; from then on the knob sets it over its whole range. Start it again (gp5_pickup_start) whenever the knob gets a new job or the value changes elsewhere (a preset load). Without gp5_level_own(1) the knob stays the output level as well.

Trying it without a pedal

python3 tools/simulate.py <firmware> --script s.txt runs your page and menu with scripted controls and saves the screens (simulator). firmwares/tremolo/test/screen.sh runs the tremolo’s control half on the computer, presses its controls and saves each screen as a PNG, kit and all. Copy it for your own firmware. platform/nds32/test/ui_test.sh tests the kit itself.