Write DROID patches in VS Code, step by step.

What Droider is

A DROID patch is a plain text file (droid.ini) that lists circuits and how they are wired. You can write it in any text editor, but a text editor knows nothing about DROID. If you misspell a parameter or use a jack that doesn't exist, you only find out when the module blinks an error.

Droider is an extension for VS Code. It teaches VS Code the DROID language: every circuit, parameter, register and controller from the official manual. With it, VS Code:

• checks your patch as you type, with the same rules the DROID master uses;
• suggests circuits, parameters, jacks and cables, and shows their documentation;
• colours inputs, outputs and each cable differently, so a patch is easy to read;
• draws your rack and a graph of the patch;
• writes the patch to the SD card and ejects it safely;
• adds an optional .droider syntax with reusable megacircuits and free arithmetic.

It is free, open source, works offline and doesn't need an account.

What VS Code is

Visual Studio Code (VS Code) is a free text editor from Microsoft for Windows, macOS and Linux. Programmers use it to write code, but it works well for any text that follows rules, like a DROID patch.

Some things that make it a good home for patches:

• Extensions add support for new languages. Droider is one of them.
• You open a folder and see all its files in a sidebar, so all your patches are one click away.
• Errors are underlined in red and listed in a Problems panel, like a spell checker.
• Undo history, search and replace across files, split views, and automatic saving if you want it.

Install VS Code

Download VS Code from code.visualstudio.com/download. Choose your system:

The first time VS Code opens it shows a Welcome page. You can close it with the × on its tab.

Install Droider

1. In VS Code, open the Extensions view: click the icon made of four squares in the bar on the far left, or press Ctrl+Shift+X (⌘+⇧+X on a Mac).
2. Type Droider in the search box at the top.
3. Click Droider — DROID Patch Language by oliverlsanz, then click Install.

That's it. There's nothing to configure: Droider switches on as soon as you open a .ini, .droider or .blueprint file.

Droider updates itself when a new version comes out, like every VS Code extension.

VS Code in five minutes

These are the only parts of VS Code you need for patching:

A few keys worth knowing:

• Ctrl+S / ⌘+S saves. A dot on a tab means the file has unsaved changes. Turn on File → Auto Save if you'd rather not think about it.
• Ctrl+Z / ⌘+Z undoes, as many steps as you like.
• Ctrl+Space shows suggestions at the cursor at any time.
• Ctrl+F / ⌘+F finds text; Ctrl+P / ⌘+P opens a file by name.

Open your patches

Keep your patches together in one folder on your computer, for example Documents/DROID Patches. Then:

1. Choose File → Open Folder… and select that folder. If VS Code asks Do you trust the authors of the files in this folder?, click Yes, I trust the authors. Droider only runs in trusted folders.
2. Your patches appear in the Explorer. Click one to open it.
3. Check the bottom-right corner of the status bar: it should say DROID Patch. That means Droider is checking the file.

You can also edit a patch straight on the SD card: open the card itself as the folder. But it's safer to keep the originals on your computer and let Droider write the card for you.

Want examples? Download the example patches used in this guide.

Your first patch, step by step

Let's build a small generative melody: a clock, a Euclidean rhythm, random notes snapped to a scale and a plucky envelope. You need a DROID master and a P2B8 controller, but you can follow along without them.

1. Create the file. In the Explorer, click the New File icon next to your folder's name, type melody.ini and press Enter. Droider recognises the .ini extension.
2. Declare your controllers. Controllers go at the very top, in the order they're chained to the master. Type [p2, and Droider suggests p2b8. Press Enter to accept it; the ] is added for you.
   melody.ini

   [p2b8]

   From now on, the pots P1.1, P1.2 and the buttons B1.1…B1.8 exist. Without this line, Droider would mark them as unknown registers.
3. Add a clock. On a new line, type [lfo and accept the suggestion. Press Enter: the next line is indented, and the LFO's parameters pop up. Pick hz, type = P1.1 * 8 + 1, then add square = _CLOCK.
   melody.ini

   # --- Clock ---
   [lfo]
       hz     = P1.1 * 8 + 1
       square = _CLOCK

   _CLOCK is an internal cable: a name starting with _ that carries a signal from one circuit to others. Notice it's underlined: internal cable '_CLOCK' has no input. Nothing reads it yet. Droider will remind you until the wiring is complete.
4. Add a rhythm. A Euclidean rhythm spreads a number of beats over 16 steps. When you type the value of clock, type _ and choose _CLOCK from the list of cables. The underline on _CLOCK disappears.
   melody.ini

   # --- Rhythm ---
   [euklid]
       clock  = _CLOCK
       length = 16
       beats  = P1.2 * 12 + 2
       output = _GATE

   Not sure what beats does? Rest the mouse on it: its description, type and default appear.
5. Make a melody. On every beat, random picks a new voltage and minifonion snaps it to C minor. Its output goes straight to the jack O1.
   melody.ini

   # --- Melody ---
   [random]
       clock   = _GATE
       maximum = 2V
       output  = _RANDOM
   
   [minifonion]
       input   = _RANDOM
       degree  = 7       # natural minor
       select1 = on
       select3 = on
       select5 = on
       select7 = on
       output  = O1

6. Add an envelope and a gate output.
   melody.ini

   # --- Envelope ---
   [contour]
       trigger = _GATE
       attack  = 0.01
       decay   = 0.25
       sustain = 0
       output  = O3
   
   [copy]
       input  = _GATE
       output = O2

7. Check the status bar. When it shows 0 errors, the patch is valid. Save it with Ctrl+S / ⌘+S.
8. Load it. Insert your DROID SD card and click Write to DROID in the status bar. Put the card in the master and press its Load button. More about writing the card.

Patch O1 to a VCO's 1 V/oct input, O3 to a VCA, and turn P1.1 and P1.2. The complete patch, with a label legend, is examples/melody.ini.

Write faster with autocomplete

Suggestions appear by themselves as you type. Use the arrow keys to choose and Enter or Tab to accept. Press Ctrl+Space to bring them back.

Pressing Enter after a circuit header indents the next line and shows the parameters. Pressing Enter after a parameter keeps the same indentation. When you've finished a circuit, press Enter twice: the first suggestion on an empty line is ↵ end circuit, which leaves a blank line and starts the next line at the left edge, ready for the next circuit.

Look things up without the manual

Rest the mouse pointer on a word to see its documentation:

• A circuit header like [minifonion]: what the circuit does.
• A parameter: whether it's an input or output, its type, default value, range and description.
• A register like P1.2 or G3: what that jack or control is.
• A cable: how many times it is used.
• A megacircuit: its description and ports, from the comments in its .blueprint.

The documentation is adapted from the official DROID manual (blue-7), with the author's permission.

Read the colours

Droider colours each part of a patch by what it does, not only by how it looks:

# comments are green
[lfo]                  # circuit names, in yellow brackets
    hz     = P1.1      # inputs blue, registers teal
    square = _CLOCK    # outputs magenta, each cable its own colour
    bipolar = on       # on and off in blue

• Inputs are blue and outputs are magenta. You can tell at once which lines feed a circuit and which send something out.
• Registers (jacks, pots, buttons, LEDs) are teal.
• Each internal cable gets its own colour, always the same for the same name. Follow _CLOCK by its colour through the whole patch.
• The content of a circuit Droider doesn't know is shown in grey, because it can't be checked.

You can change these colours: see Customise colours.

Find and fix errors

Droider runs the same checks as the DROID master when it loads a patch, every time you type. Problems appear in three places:

1. A wavy underline under the mistake: red for errors, yellow for warnings. Rest the mouse on it to read the message.
2. The status bar counts errors and warnings in the bottom-left corner.
3. The Problems panel (Ctrl+Shift+M / ⌘+⇧+M) lists them all. Click one to jump to its line.

Errors would stop the DROID from loading the patch: fix them all. Warnings point at things that work but probably aren't what you meant, like a label that's too long to display.

What each error means

Label your jacks and controls

A label legend is a block of comments at the top of a patch that says what each jack and control does. The DROID ignores it (it's just comments), but the DROID Forge reads it, and so does Droider: the labels appear in the hardware view and the circuit graph.

# LABELS: master=16
# INPUTS:
#  I1: [RESET] Restart the rhythm
# OUTPUTS:
#  O1: [PITCH] Melody, 1 V/oct
#  O3: [ENV] Plucky envelope
# GATES ON MODULE 1:
#  G1: [CLK] Clock out
# CONTROLLER 1:
#  P1.1: [RATE] Clock speed
#  B1.1: [OCT] Hold for one octave up

• Each entry is register: [SHORT] long description. Both parts are optional.
• Sections are # INPUTS:, # OUTPUTS:, # GATES ON MODULE n:, # GATES ON X7: and # CONTROLLER n: (n is the controller's position in the chain).
• Droider suggests the right registers in each section and warns about registers that don't exist, are in the wrong section, or have a short label longer than five characters.

See your rack

Click the circuit board icon at the top right of the editor, or run DROID: Show Hardware View from the Command Palette. A panel opens next to your patch with:

• the master (MASTER or MASTER18), any G8 and X7 expanders, and every controller you declared, in order;
• the short labels from your legend on each jack, pot and button.

The view follows the patch you're editing and updates as you type. It's a quick way to check what each knob does before a performance.

Follow the signal in the graph

Click the hierarchy icon at the top right of the editor, or run DROID: Show Circuit Graph. Every circuit becomes a box and every cable a wire, laid out from left to right in the direction the signal flows.

• Jacks and controls are the round nodes on the edges. Untick Hardware I/O to hide them.
• Attenuation and offset on an input (× 8, + 1) are shown under it; fixed values appear as small tags.
• Click a box to jump to that circuit in the patch. Drag boxes to rearrange them, drag the background to pan, and pinch or scroll to zoom.
• Re-layout tidies everything again; Fit zooms to show the whole patch.
• In .droider patches, megacircuits are a single box. Open a .blueprint and show its graph to see its inside: its inputs and outputs are drawn as jacks.

Write the patch to the SD card

1. Take the micro SD card out of your DROID master and insert it in your computer (with a card reader if needed). If you use an X7 with USB, switch it to USB mode instead.
2. Open your patch. A Write to DROID button appears on the right of the status bar. Droider recognises a card that has a droid.ini on it or is named DROID.
3. Click Write to DROID. Droider:
   • saves the patch, and builds it first if it's a .droider file;
   • refuses to write if the patch has errors, so a broken patch never reaches the module;
   • writes it as droid.ini at the root of the card, reads it back to verify it, and ejects the card.
4. When you see “Patch written and verified… card ejected safely”, put the card back in the master and press Load (or return the X7 USB switch to the centre).

The button works on macOS, Windows and Linux (cards mounted under /media or /mnt). You can also run DROID: Write Patch to DROID Card and Eject from the Command Palette.

Several patches on one card

A DROID card can hold alternative patches named droidXY.ini, where X is a controller and Y a button. For example, hold button 4 of the first controller while pressing Load to load droid14.ini.

• Droider's button always writes droid.ini. For alternative patches, write the file to the card yourself (for a .droider patch, copy the built file from dist/).
• Every alternative patch needs its own controller declarations at the top, or the buttons won't work to switch patches.

.ini, .droider and .blueprint

Droider understands three kinds of file. You choose the kind with the file's extension:

Any .ini patch is also a valid .droider patch: rename droid.ini to my-patch.droider and start using the extras.

Free arithmetic

On the DROID, an input can only do A * B + C: one multiplication, then one addition. In a .droider file you can write any expression with +, -, * and parentheses, on any input. For example, a pot that morphs between two melodies:

# Pot 1 morphs from O2 (left) to O1 (right)
[copy]
    input  = (O1 - O2) * P1.1 + O2
    output = O3

When the patch is built, Droider splits the expression into as few [copy] circuits as possible, each one a valid A * B + C:

[copy]
    input = O1 - O2
    output = _MATH1
[copy]
    input  = _MATH1 * P1.1 + O2
    output = O3

The cables it creates are called _MATH1, _MATH2…, so you can tell them from yours. In the circuit graph the whole expression is shown as one formula.

Create a megacircuit

A megacircuit is your own reusable circuit: a few circuits wired together, with named inputs and outputs, that you can then use in any patch like a built-in one. You define it once in a .blueprint file, and the file's name becomes the circuit's name: randomnote.blueprint defines [randomnote].

Let's make one that plays a random note in C minor on every clock, so you can add a melody to any patch with four lines.

1. Create a file anywhere in your open folder, for example blueprints/randomnote.blueprint.
2. Describe it in a comment at the top. Droider shows that comment when you hover the megacircuit.
   blueprints/randomnote.blueprint

   # A megacircuit is your own reusable circuit.
   # This file defines [randomnote]: a random note in C minor on every clock.

3. List its inputs and outputs. A comment just above a port documents it. An input with = value has a default and is optional; one without it must always be wired.
   blueprints/randomnote.blueprint (continued)

   [input]
       # a new note on each clock
       clock
       # how far the melody can jump (1V = one octave)
       range = 2V
   
   [output]
       # the note, 1 V/oct
       pitch

4. Write the body with ordinary circuits. Refer to the ports by their bare names (clock, range, pitch), and use _cables for the wiring inside:
   blueprints/randomnote.blueprint (continued)

   # a random voltage on every clock…
   [random]
       clock   = clock
       maximum = range
       output  = _VOLTAGE
   
   # …snapped to the notes of C minor
   [minifonion]
       input   = _VOLTAGE
       degree  = 7       # natural minor
       select1 = on
       select3 = on
       select5 = on
       output  = pitch

Droider checks the blueprint like any patch, and also warns about inputs you never use. Cables inside a blueprint are private: every copy of the megacircuit gets its own, so two copies never interfere. A blueprint can also use other megacircuits, as deep as you like.

Use a megacircuit

In any .droider patch in the same folder, the megacircuit works like a built-in circuit: it autocompletes after [, shows its documentation on hover and is checked. Here it gives a patch two melodies:

# Use your megacircuit in any .droider patch,
# just like a built-in circuit.
[p2b8]

[lfo]
    hz     = 4
    square = _CLOCK

[euklid]
    clock  = _CLOCK
    length = 16
    beats  = 5
    output = _RHYTHM

# Two melodies from the same megacircuit
[randomnote]
    clock = _RHYTHM
    pitch = O1

# this one moves on every clock, within one octave
[randomnote]
    clock = _CLOCK
    range = 1V
    pitch = O2

The first copy leaves out range, so it uses the default 2V. The second one sets it.

The complete files are in examples/: melodies.droider and blueprints/randomnote.blueprint.

Build to a plain .ini

The DROID only reads plain patches, so a .droider file is built into one. You rarely need to do it by hand: Write to DROID builds automatically. To see the result:

1. Open the .droider file.
2. Click the package icon at the top right of the editor, or Build to dist in the status bar (shown when no card is inserted), or run DROID: Build .droider to dist/*.ini.
3. Droider writes dist/<name>.ini in your folder and tells you if the result has errors.

During the build, private cables are renamed for each copy: _VOLTAGE in the first [randomnote] becomes __randomnote_1_VOLTAGE, and in the second one __randomnote_2_VOLTAGE. Arithmetic is split into [copy] circuits. If a line ends up longer than the DROID's 63 characters, cable names are shortened, and comments in the output list the short names. The built patch is checked again before it can be written to a card.

DROID language cheat sheet

A summary of the patch language. For every circuit, hover it in VS Code or see the official manual.

Commands and buttons

Command-line linter

The same checks are available in a terminal, for scripts, continuous integration or AI assistants. You need Node.js:

git clone https://github.com/OliverLSanz/droider.git
cd droider
npm install
npm run compile
node out/cli.js path/to/patch.ini          # human-readable
node out/cli.js --json path/to/patch.ini   # JSON output

The exit code is 0 when there are no errors, 1 when there is at least one, and 2 for a wrong command or unreadable file. Warnings don't fail. Megacircuits are read from every .blueprint under the current folder.

Customise colours

Open Preferences: Open User Settings (JSON) from the Command Palette and add your own colours:

"editor.semanticTokenColorCustomizations": {
  "enabled": true,
  "rules": {
    "droidInput": "#4FC1FF",
    "droidOutput": "#C586C0",
    "droidRegister": "#4EC9B0",
    "droidBoolean": "#569CD6",
    "droidUnverified": "#808080"
  }
}

Droider works with any VS Code colour theme, light or dark. Cable colours are chosen automatically from each cable's name.

Troubleshooting

Nothing is coloured or checked

• Look at the language in the status bar. If it doesn't say DROID Patch, click it and choose DROID Patch.
• If a banner says Restricted Mode, the folder isn't trusted. Click Manage and trust it: extensions don't run in restricted mode.

My other .ini files are treated as DROID patches

Droider handles every .ini file. For a non-DROID .ini, click the language in the status bar and choose Ini. Or keep your DROID patches in their own folder.

The Write to DROID button doesn't appear

• The patch must be the active editor, and must be a .ini or .droider file.
• The card must have a droid.ini at its root or be named DROID. For a brand-new card, name it DROID when you format it (FAT32), or copy any droid.ini onto it once.

It says my megacircuit is an unknown circuit

• Megacircuits only work in .droider files, not .ini.
• The .blueprint must be inside the folder you opened in VS Code (in any subfolder).

Something else?

Open an issue on GitHub with the patch (or the smallest part of it that shows the problem).