Step by step

From a firmware to the library: labelled, playable, and listed in the Synthux community directory. Every step ends with checks; tick them as you go. This browser remembers them.

Where do you start?
Built with

The order, and why

Your repository first, because everything else points at it. Then the pull request to the community directory, as soon as the repository has a README and a release. A person reviews it, and that can take days. Everything after it works without it: the designer, your label file, the browser build and your own page don't wait for the review. When the entry is merged the library lists your firmware with whatever is in your repository by then, so the entry never needs changing for a new label or build.

1. Your repository

  1. Set upEditorGitGitHub

    An editor (VS Code, say), Git and a GitHub account. For libDaisy, the Daisy Toolchain builds and flashes. For Plugdata, Plugdata with its Daisy export, and the Simple Touch board file (a custom JSON).

  2. Make the firmware

    Start from an official firmware (TouchBass, Touch String, …), a community one, or nothing. Building on someone's code? Keep their licence and credit them in the README.

  3. A public repositoryGitHub

    On GitHub, New repository, set to Public, then push your code. The directory needs GitHub; the library also reads Codeberg.

  4. Check the repositoryGitHub

    Its default branch is where everything below goes: the library and the designer read nothing else. You see it on the repository's front page and under Settings › Branches, usually main. Work on another branch? Merge it before you check anything in the library.

  5. A README

    What the firmware does and how to install it. A short one is enough for now: the designer's Repository kit writes a full one with the control map in step 3, which you can merge into yours.

  6. A release with the .binGitHub

    Releases › Draft a new release, a tag such as v1.0.0, and the firmware attached, named in lowercase with hyphens: my-firmware-v1.0.0.bin. People flash that file with the Daisy Web Programmer. The directory recommends it (it warns without one) and will need it for one-click flashing later.

2. Get in the queue: the community directory

  1. Directory entryDesignerGitHub

    In the designer, fill in Firmware: name, author, a one-line description (up to 200 characters) and the repository. Then Directory entry…: it checks the entry the way the directory does, and opens a pull request on GitHub with the file filled in. GitHub asks you to fork the directory first; that's normal.

    Red? The pull request's Files changed tab marks what's wrong on your file (/author/url is the url in author). Fix it in your fork and push: the check runs again. A reviewer then looks at whether the repository matches the entry, has a README and targets the Simple Touch. Nobody tests the firmware. It can take days: carry on below.

3. Labels

  1. Label every controlDesigner

    Start from Blank, or from the official firmware you built on. Reference names: Synthux shows S30, P03 and so on under each label. Then, in the Labels tab:

    • Line 1 for what a control does, line 2 for detail (a switch's positions: "off / on / latch").
    • Pads held for a second function: tick Mod, and fill their column for what the other controls do while it's held (or after it's tapped: click hold for tap).
    • A switch that changes what everything does, such as a playmode switch: Modes. The labels without a mode are the print set, as wide as fits every mode.
    • The MIDI column if it sends or listens to MIDI, and Notes for what doesn't fit on a label.
  2. Your look optionalDesigner

    The Style tab: a faceplate of your own (download the template there), colours, label boxes; the font in the toolbar. The library shows it as the Creator theme.

  3. Into the repositoryDesignerGitHub

    Repository kit… downloads a .zip; its HOW-TO.txt says where each file goes. In short: simple-touch-labels.json at the root, the control map at docs/ (a new folder, even if you have a doc/), your faceplate at the path the label file names. Have a README? Keep it at the root and copy in the parts you want. Then commit to the default branch.

    Just pushed and the file isn't there yet? GitHub caches raw files for a few minutes.

4. Make it playable (libDaisy only, for now)

simple-touch-web runs libDaisy firmware. A Plugdata patch can't be played in the browser yet; skip to step 5.

  1. Setup and loopsimple-touch-web

    Split main() into Setup() and a Loop() that runs one pass, as the simple-touch-web README shows. Leave out what a browser can't do (flash writes, bootloader jumps) with #ifdef SIMPLE_TOUCH_WEB.

  2. The workflowGitHub Actions

    Add .github/workflows/browser-build.yml from the simple-touch-web README and push. Every push then builds the firmware for the browser, checks that it boots, and adds the build to a simple-touch-web branch.

  3. Listen, then approveTest benchDesigner

    In the designer, under Browser build, Find builds in the repository lists the builds with a Test bench link. Only you can say whether it sounds like your firmware. If it does, tick "drives the OLED" if it has one, then Use this build, Save file, and commit the label file again.

5. A page of your own optional

  1. Web appDesignerGitHub Pages

    Web app… packs your manual as a site: copy the folder into docs/ on the default branch, then Settings › Pages: Deploy from a branch, your default branch, /docs. It's yours from day one, listed or not; link it from your README.

6. When the entry is merged

  1. In the libraryLibrary

    The directory publishes on every merge, and the library lists your firmware under Community. It reads your repository each time, so labels and builds you add later show up by themselves.

    Changes requested on the pull request? Edit the file in your fork, on the same branch: the pull request updates and the check runs again.

Later: keeping it up to date