pd2dsy

Utility for converting Pure Data (Vanilla) patches to Daisy projects.

Installation/Setup

If you've already followed the guides or watched the videos for Setting Up Your Development Enviornment, and Creating a New Project you can skip straight to step 3

1. Follow the instructions for installing the Daisy Toolchain for your OS
2. Install python for your OS
   • On Mac OS/Linux you can use your favorite package manager, and python3 may already be installed. (i.e. brew install python)
   • Details for installing python on windows.
3. Clone the repo with git clone https://github.com/electro-smith/pd2dsy
4. Navigate into the cloned repository (cd pd2dsy)
5. Type in ./install.sh and hit enter (make sure you're in the root directry of the project). This should install required python modules, update your libdaisy, and build it for you. It also creates a virtual environment, which is a self-contained python environment for specific projects.

At this point you should be ready to use the tool!

Usage

The first time you start a new session and want to use pd2dsy you will have to activate your virtual environment. This essentially loads a version of python with all of the specific libraries ready to go:

• On Mac OS / Linux: source ./pd_env/bin/activate
• On Windows (from git-bash): source ./pd_env/Scripts/activate

Once activated you should see something like:

Once you see this you can start to use pd2dsy.

After you've made your patch in puredata, you can turn it into cpp by running the command:

python pd2dsy.py --board <BOARD> <FILE>.pd

\<BOARD> should be replaced with the board you're using (pod, patch, patch_init, field, petal).

\<FILE> is the filename of your pd patch.

Your patch will be built and uploaded automatically, assuming you have a Daisy in DFU mode plugged into USB. If you'd like to build and upload manually, you can navigate to the folder that it created and run make, then make program-dfu.

For now, the script leaves the path to libdaisy as ../libdaisy, which works if the generated folder is placed within the root directory. Otherwise, the Makefile should be edited (or the --libdaisy-depth option should be used) to point to a valid libdaisy repository.

Optional features

-c, --custom-json

If you've designed your own prototype or board based on the Daisy platform, you can specify the I/O in a custom JSON file. Details for how this works can be found in the tool that actually performs this generation, json2daisy.

--ram

You can specify whether you'd like to optimize your project's RAM usage for speed or size. The Daisy's internal SRAM has a fast access time, but it can be quite limited at 512kB (or even less if you're using the bootloader!). The external SDRAM (note the D), while it can be slower to access, affords a hefty 64MB of space. Currently, only the heap is placed in SDRAM if size is selected (meaning all dynamic allocations happen in SDRAM), but that's the best use-case for it anyway, since the largest program you could squeeze onto the Daisy would only be around 512kB.

The appropriate linker is automatically supplied and chosen in the makefile if you select size, so all you need to do is rebuild the project.

--rom

You can specify whether you'd like to optimize your project's ROM usage for speed or size. The Daisy's internal flash allows programs to start very quickly, and offers very slightly better performance. However, if your program is too hefty to fit in the Daisy's 128kB of internal flash, then you'll need to execute the program from SRAM using the Daisy bootloader (for up to 512kB). Selecting size will configure your project for the bootloader, and all you need to do is upload the bootloader, build your program, then upload the resulting binary to the bootloader. If you need even more size, you can execute your programs directly from the 8MB QSPI flash chip with double_size, though performance may take a hit in certain scenarios.

Both --ram and --rom default to speed.

-d, --directory

The parent directory of your project can be specified. This is convenient if you'd like to build from somewhere other than your intended project directory, for example:

python pd2dsy.py -d build path/to/source.pd

This would place your project in the build subdirectory. If it doesn't exist, then pd2dsy will ask if you'd like to create it.

--libdaisy-depth

pd2dsy generates a number of helpful files that need to know where your libDaisy folder is located. If you don't want to change them all manually, then you can specify how far away the libDaisy folder is from your project folder:

python pd2dsy.py --libdaisy-depth 2 path/to/source.pd

This will tell all the project files to look two directories above the current one to find libDaisy (as in ../../libDaisy). This does require that libDaisy exists in some parent directory of your project, but you can of course specify it manually if you prefer.

Interacting with the Daisy I/O

Each board has a selection of physical I/O that can interact with your PD patch. Most components have an alias, which allows you to refer to the same input/output by different names if you have a preference. All names and aliases are case insensitive, so you can style them however you like (e.g. GateIn).

Components that act as an input (like a Switch, for example) are accessible with Pd's receive object, and require the @hv_param attribute in order to be recognized as an external input. If your Switch is named sw, then the Pd object would look like r sw @hv_param. Outputs, like an LED, use the send object (i.e. s led @hv_param). The examples make this usage pretty clear.

Some components have variants, which allow you to interact with them in multiple ways. For example, you can receive a bang from a Gate In instead of a float if you add _trig to the end of the gate's name (or any of its aliases). So, if a Gate In's name is gatein1, you would use gatein1_trig.

Here's what each component expects for its default behavior and variants:

Here's how the newly added sensors are addressed:

Daisy Board I/O

patch

patch_init

petal

pod

field

How It Works

There are a few pieces to this:

• HVCC - heavy compiler, a generator for creating portable source code based on Pure Data vanilla patches
• json2daisy - a utility for converting json board descriptions to libDaisy-based C++ headers
• Daisy Interface handling - The controls and features available on the daisy platform need to be accessible from a pure data patch (buttons, knobs, leds, etc.)
• compilation - a distributable copy of the arm toolchain and scripts for building the code without installing extra tools.

Next steps

1. Double check licensing requirements, etc. and bundle a pre-compiled binaries for the arm toolchain into the project for built-in compilation
2. Add a GUI? (Web app / built in tester, similar to OWL platform?)