Mappings

01 The big picture

What a mapping is, before any hex — read this page and the rest is detail.

Open the Nerd Menu with SHIFT + AUTOMATE (NERD), then press SHIFT + AUTOMATE again: you are on the Mapping screen. 70 numbered rows, six small fields each. It looks dense, but every row says one thing, always in the same way:

1. Watch this a source — a CV input, a MIDI note, a track’s state, a variable
2. Calculate optional — compare, count, scale, quantise
3. Do that a destination — a CV output, a track parameter, a MIDI message

A row is a small rule: whatever this does, make that follow it — or follow something calculated from it. You write up to 70 of these rules and the NerdSEQ keeps all of them running in the background while you play, on top of whatever your patterns already do. Clock dividers, quantisers, step sequencers, random melodies in a scale, probability gates and self-refilling patterns are all built from these rules, without anything you would call code.

It never stops checking

Every row is checked 1000 times a second, always in the same order, from row 00 to the last used row, then from the top again. It runs whether the Mapping screen is open or not, and whether the sequencer plays or not.

Because the order is fixed, a row that reads the result of a row above it sees this pass’s value. A row that reads a row below it sees the value from the pass before — at most 1 ms old. You won’t hear the difference, but in a chain of rows the rule is simple: put the rows that produce a value above the rows that use it.

“Is it on?” is not “did it just turn on?”

A held key or an open gate reports 1 on every one of those thousand checks, for as long as it is held — not once. When something should happen once, at the moment a signal changes, you use one of the tools made for edges (chapters 07 and 13).

Destinations act on change

So a simple row doesn’t hammer its destination a thousand times a second, a destination normally acts only when the row’s value differs from the value it sent last time. A plain CV-in → CV-out row updates the output when the input moves, and does nothing while it stands still.

A few destinations act on every pass on purpose — a SETV variable write, the song start and jump commands, the TRG* / VAL* triggers. They are named where they appear. Point one of those at MIDI or an expander and it sends a thousand messages a second, so they need a gate in front of them.

Starting and stopping the mapping

Editing a GLOB button, screen or mode destination also stops the mapping, whatever Stop On Edit says — those rows could otherwise press buttons or change screens while you type. SHIFT + START and SHIFT + STOP keep their sequencer meaning on this screen.

↑ Contents

02 How values work

One number range for everything — and the three places a number can be kept.

Every source hands its row one number, 0–FFF (0–4095). A CV input already lives in that range; a MIDI CC (0–127) or an I2C value (0–16383) is rescaled into it before the row sees it. Every destination takes the same range and scales it to what it needs. That shared range is why almost anything can drive almost anything.

One number, several meanings

A gate cable is not a boolean

A gate patched into a CV input still arrives as a full-range reading with a little noise on it — never exactly 0. Used as a condition, that noise alone fires at 1000 passes a second. The CV source has the fix built in: its extra offers TH and !TH next to VAL. With TH the row compares the input with the global Threshold (Nerd Menu) and delivers a clean 1 / 0.

MAPPING Hex:001 Dec:0001 Bool:1 ▶
00 CV   IN 1 TH    > TRIG TRIG TR 1  · a clean trigger from a noisy gate

An envelope’s GATE and STAT extras are already clean. For any other analog source — an automator, an envelope’s VAL — build the same comparison with a CALC IF> row against TH or a constant, and use that row’s result as the gate.

Centred at 800

A bipolar destination puts its neutral point at 800 (2048): below means negative, above means positive. Track transpose, for example, is 120 × v / 4095 − 60: 0 is −60 semitones, 800 is 0, FFF is +60. An unpatched CV input reads 0 V, so a raw CV IN 1 VAL → TRCK TPS row would drop the track five octaves. Add an offset instead:

MAPPING Hex:99A Dec:2458 Bool:1 ▶
00 CV   IN 1 VAL   > ---- ---- ----  · the CV, unchanged
01 CALC ADD  00|VA > TRCK TRK3 TPS   · VA holds 811h

Why 811 and not 800: 1 V reads about 409 counts, and 800 + 409 lands exactly on the boundary of +12. If the input reads a count low, the result drops to +11. The extra 11 keeps every octave safely inside its step and still gives 0 at 0 V.

Where a value lives

↑ Contents

03 Reading and editing a row

Six fields, a marker, a status line — and a selector that explains every value.

MAPPING Hex:027 Dec:0039 Bool:1 ▶
08 CV   IN 1 TH    > ---- ---- ----
09 CTRL XSHT 1RW   > ---- ---- ----
0A CALC INCW =0|=7 X ---- ---- ----  · X: not in the regular pass
0B CALC LDI  0A|=0 > CV   NOTE CV 1
0C GLOB RAND ----  > CV   PTCH CV 2
0D CALC SCAL 3D|=0 > CV   NOTE CV 3  · 3D shown inverted: constant 61
0E SKIP 02 = 0A|=0 > ---- ---- ----
Pass Variable B to Dest.

The six fields

Fields 1–3 pick the source: the base (the family — CV, MIDI, TRCK…), the function (which input, which track, which operation) and, where needed, the extra (which reading, which parameter). Fields 4–6 do the same for the destination. A source or destination with an empty field it needs does nothing.

Between the halves sits a marker: > means the row runs in the regular pass, a red X means it doesn’t — it sits in a block that its CTRL row runs, or a SKIP just skipped it (chapter 13).

Keys on the grid

The Mapping Selector

Mapping selector       11/15
Select source base
CV    CV/MOD in- and outputs
TRIG  Trigger and gate outputs
TRCK  A track's playback state
…
VAR   A variable or a row value
CALC  Calculate from two operands
SKIP  Skip rows on a condition
GLOB  Clock, run and reset
EXT   Keyboard, gamepad, buttons
CTRL  Enable/disable other rows
OK->Set SHIFT+OK->Abort

Every entry shows the four-letter name it will have in the row and a short description, so you don’t need to learn the abbreviations. A whole source or destination takes three presses of OK. A function without an extra ends there and says so. Picking a learn function (LRN) closes the selector and leaves the row listening.

Mapping selector
Select CALC->SCAL ->
  Operand Y          Operand Z
  Constant   61      Constant   0
  Scale RW0C to 61 key 0
OK->Set SHIFT+OK->Abort

↑ Contents

04 Sources I — the direct signals

What the NerdSEQ is already doing: jacks, tracks, automators and envelopes.

CV and TRIG — the jacks

Reading an output back lets a row react to what another row, or the sequencer, just wrote there — no patch cable needed.

Trigger16 and Dualchord can’t report their outputs over NSA, so the NerdSEQ answers from a mirror of what it last sent. A gate on, off or toggle (including a binary or all-off command) holds until the next command. Any shorter trigger reads 1 exactly once, and the read clears it — if two rows watch the same output, only the first sees the pulse. What a Trigger16 generates by itself (Triggers Galore, Triggers Square 8) is not mirrored.

TRCK — a track’s own state

AUTM and ENV — the modulators

AUTM gives the output of one of the 8 automator slots, 0–FFF; it has no extra. ENV gives one of the 8 envelopes, and its extra chooses what you read:

00 ENV  #  3 VAL   > CV   PTCH MOD6  · envelope 3 out of MOD 6
01 ENV  #  3 GATE  > TRIG GATE TR 6  · and its gate out of trigger 6

↑ Contents

05 Sources II — the outside world

MIDI notes, CCs, NRPNs and I2C — each with a learn function, so you rarely need to know a channel.

The function of MIDI, MCC and NRPN picks the port and channel: TC 1–16 for TRS, HC for USB host, DC for USB device. The last entry, LRN, waits for the next matching message on any channel and fills in the real channel for you.

MIDI — notes and more

MCC — a CC as a level or as an event

On the grid, SHIFT + ◀ / ▶ steps a level row through the controllers; SHIFT + ▲ / ▼ switches it to event mode. In event mode the large step walks the controller and the small step the value; stepping the value below its first position goes back to level mode. LRN learns in the mode the extra is already in: a level extra learns channel and controller, an event extra learns controller and value — the quickest way to capture one encoder click or one button.

00 MCC  TC 1 2001  > SETV V  A INC^  · CC 32 = 1: one step up
01 MCC  TC 1 207F  > SETV V  A DEC^  · CC 32 = 127: one step down
02 VAR  #  A SRC   > CV   PTCH CV 2

NRPN — 14-bit control

The same channel layout; the extra is an NRPN number 0–9999. 7-bit and 14-bit values are told apart by what arrives. Use it when 128 steps of a CC are too coarse — a long filter sweep, a delay time.

I2C — from an expander bus

Two functions: SC.CV (a value arriving over SET.CV from another I2C module, a fader bank for example) and LRN. The extra is the port, 0–127. Values arrive with 14 bits and are scaled to 0–FFF.

↑ Contents

06 Sources III — memory, machine, buttons

The mapping’s own memory, the sequencer’s state, and every button you can press.

VAR — read memory

VAR reads one of the 16 variables (# A–# P) or one of the 70 row results (RW00–RW45). With the extra on SRC it passes the value on. Any other extra is a value: the row writes it into the variable or row and passes it on in the same step. The row shows that value in hex, #800. That is how a load-time block seeds its starting values (chapter 12).

GLOB — the machine watching itself

EXT — keyboards, gamepads, buttons, encoders

The function picks the device — a USB or PS/2 keyboard’s numpad (KEYB), a Sega gamepad (SEGA), the NerdSEQ’s own buttons plus the Multi-IO’s MIOX / MIOY / MIOZ (BUTN), or an encoder. The extra picks the key; a button reads 1 while held.

The two encoders work differently. MENC (Multi-IO encoder) and PENC (PC keyboard encoder) hold a value the knob walks up and down between 0 and FFF, without wrapping. Their extra names the variable or row the step size comes from: 1 walks by ones, 10 by tens, 0 counts as 1.

Each button and encoder can have its built-in job switched off in Setup → ENCODER & MIO BUTTONS, which leaves it free for mappings only.

00 EXT  SEGA STRT  > GLOB BUTN STRT  · gamepad Start presses START

↑ Contents

07 The built-in calculator

CALC turns a patch bay into something that can count, compare, remember and decide.

CALC is a source that needs no outside input: it computes a value from two operands, and that value becomes the row’s result — readable by other rows, routable to any destination.

The two operands, Y and Z

Pointing an operand at a row is how rows talk to each other. A larger number than 167 goes into a variable.

The operations, by family

You don’t need to memorise them. Pick CALC in the selector, and the operand editor writes out what the row will do: Divide 4 by VarC, Scale RW0C to 61 key 0.

Chained operations — a third input

A chained operation reads a third value: on the source side, the result of the row directly above; on the destination side (below), the row’s own source value. Y and Z are the settings. Each one replaces two to four rows of hand-built arithmetic:

• SCAL

  Quantise a note into a scale. Y = scale number, Z = key (0 = C). 61 is minor pentatonic, 47 major, 57 minor, 12 dorian.

• CDIV

  One pulse every Y rising edges; a rise on Z resets the count. A clock divider in one row.

• PROB

  On each rise, roll once: with chance Y (800 = 50 %) pass Z for the whole gate. No chattering.

• CLMP · WIN · FOLD

  Hold, test or fold a value into the range Y..Z.

• XFAD · XFDS · MUX

  Crossfade from Y to Z (linear or S-curve), or select Y or Z.

• CURV

  Bend a value: logarithmic below 800, exponential above, an S when Z is set.

Two small examples

00 CV   IN 2 VAL   > ---- ---- ----  · raw pitch, no destination
01 CALC P2NT 00|=0 > CV   NOTE CV 2  · snapped to the nearest note

00 CV   IN 1 TH    > ---- ---- ----  · clock in, made clean
01 CALC CDIV =4|=0 > TRIG TRIG TR 1  · every 4th clock

CALC as a destination — two calculations in one row

A row’s destination can be CALC again: the same 72 operations, run a second time on the same row. It is not an output. The result becomes the row’s own result, which the next rows read. You still need a following row to reach a real output; what you save is the row that would have sat between the two calculations.

00 CV   IN 1 VAL   > CALC P2NT 00|=0 · pitch → note, in one row
01 CALC ADD  00|=7 > CV   NOTE CV 1  · a fifth up

↑ Contents

08 Destinations I — the workhorses

CV, triggers and tracks — the destinations you will use in most mappings.

Every destination scales the incoming 0–FFF to what it needs. The exact formulas are in the manual and in nerdseq_mapping_coding.md; here is what to expect.

CV — pitch or note

The function is PTCH (the value as-is) or NOTE (the value modulo 120, as a note). The extra picks the output: the 6 CV jacks, the 6 MOD jacks, or the 16 channels of up to four CV16 expanders.

TRIG — five ways to fire

The extra reaches the 6 local triggers and up to four Trigger16s, and continues into M1-1–M8-16: every drum-matrix cell of every track. A cell fires whatever that track’s matrix has it set to — a Trigger16 output on a Trigger16 track, an I2C command or MIDI note on an I2C track. Other track types ignore it.

TRCK — every parameter a track has

The function picks the track: TRK1–TRK8, SLCT (the track under the cursor), a track chosen by a variable (V A…) or by a row’s result (RW00…). The last one lets one row re-target a different track whenever that row’s value changes.

The extra is the parameter — over fifty of them: mute, solo, pattern order, transpose, trigger delay, the nine probabilities, glide, track clock, fire a patch, pattern length, jump to a pattern row, shift the pattern, sync, reset, the four FX overrules, the song start / jump / stop family, the euclidean controls, and direct writes into the notes of any of the 64 steps.

PNC1–PNC8 write a note into the row the track is playing now, note column 1–8. The row above supplies the note (0 removes it); this row’s source rising from 0 is the moment it is written. The note sounds the next time the playhead reaches that row — a way to build up a pattern while it loops. They do nothing on row 00 or while the track is stopped.

↑ Contents

09 Destinations II — modulation & audio

Turn the knobs of the automators, envelopes, audio tracks and CV16 modulators from a row.

AUTM and ENV

Both pick their slot like TRCK picks a track: directly, by variable or by a row’s result. The automator’s LFO exposes start and reset, speed, offset, invert, clock source, amplitude, waveform, bit depth and phase. An envelope exposes attack, attack peak, decay, sustain, release, offset, and its gate, fire and toggle. Every knob on those screens, a row can turn.

00 CV   IN 2 VAL   > ENV  #  3 ATK   · CV in 2 sets envelope 3's attack

AUDI — the audio tracks

The function picks one of 4 audio channels, or one of 12 sample slots (loop start, end and position, for live scrubbing). A channel’s extra reaches pitch (exponential), note, gate and stop, waveform or sample, offset, backwards, the delay (type, time, send, feedback), FM boost, volume, glide, mute, note cloning with coarse and fine detune (centre 800), modulation source, PWM, wavefolder, bitcrush and distortion.

CV16 — the expander’s own modulators

Each of a CV16’s 16 channels can run its own envelope and LFO on the expander. This destination reaches glide speed and resolution, the envelope’s attack, sustain, release and fire, and the LFO’s type, speed, amplitude, start and reset.

↑ Contents

10 Destinations III — out into the world

MIDI out, I2C, Dualchord and the video expander — where flooding matters.

MCON — MIDI CC and NRPN out

The function picks port and channel (TRS, USB host, USB device). The extra is a CC 0–127 (value scaled to 0–127) or, further up, an NRPN 0–9999 (scaled to 14 bits).

MIDI — notes, bend, program change

00 VAR  #  A SRC   > ---- ---- ----  · the note number
01 CV   IN 3 TH    > MIDI TC 1 NTGT  · note on/off from the gate

I2C — drive an expander bus

Ten functions: bus A or B, each as CV with slew, CV without slew (scaled or raw), trigger, or AESC / BESC — the ES.CO command for a disting EX/NT controller. The extra packs address and port into one 4-digit hex value; the default address is 31 (41 for the ES.CO variants).

DUAL — the Dualchord

The function picks one of four units. The extra reaches notes, pitches and per-wave on/off, then nearly every knob: both LFOs, stereo spread, each wave’s pulse width, detune, level and morph, glide, velocity, the voice envelope, the filter, noise, filter mode and the wavefolder. Knob values are scaled to 0–255, the resolution of the hardware knobs; filter mode (19 modes) and preset select (0–3) are the exceptions.

VISU — the video expander

With a video expander connected, VISU selects and cues shaders and drives their position, amplitude and alpha, 16 modulator inputs, and per-shader envelopes and LFOs. SENV with E?GT gates a shader envelope and E?FI fires one — use them when the envelope should follow something that isn’t a trigger output.

↑ Contents

11 Destinations IV — random, tables, Fill

The NerdSEQ’s generative tools — and the whole Fill Pattern screen — driven by rows.

RNDM — random ranges

Sixteen ranges, each with a LOW and a HIGH bound, 0–99. The firmware keeps them from crossing. Patterns and tables draw their random values from these ranges.

00 CV   IN 2 VAL   > RNDM RG 3 HIGH  · a knob widens range 3

TABL — tables

The function picks a table (TB00–TB1F), a track’s running table, or the running table at the cursor’s column. The extra reaches speed, type, quantise, chord, range, preset, add tick, and start / stop. Nothing happens to a table without a track type.

GLOB — the whole machine

FILL — a track that refills itself

FILL puts the Fill Pattern screen behind mapping rows. Its extra has two halves:

• Actions

  FI 1–FI 8 fill one track, FI * all playing patterns; FIM… do the same with the Magic settings. They fire on a rising value, only while the sequencer plays.

• Settings

  Every field of the Fill Pattern screen — note range, density, trigger types, drum mask, sample range, volume, scale, interval mode, offset, columns, remove %, new length — set continuously from the value.

00 GLOB TICK ----  > ---- ---- ----  · main-clock ticks, 6 per row
01 CALC MOD  00|30 > ---- ---- ----  · modulo 48 = every 8 rows
02 CALC IF=  01|=0 > GLOB FILL FI 1  · fill track 1

↑ Contents

12 Variables & state

Write, step and reset values on purpose — and seed them when a project loads.

SETV — the write destination

The function is the target: V A–V P, or a row, RW00–RW45. The step functions turn “something happened” into “count one up or down” — the encoder in chapter 05 works this way.

Seeding values when a project loads

A CTRL XLOD row marks the rows below it as a block that runs once, right after the project loads, and never in the regular pass. Inside it, VAR rows write their values.

MAPPING Hex:000 Dec:0000 Bool:0 ▶
00 CTRL XLOD 2RW   > ---- ---- ----  · next 2 rows: once, after load
01 VAR  #  A #800  X ---- ---- ----  · variable A = 800
02 VAR  #  B #000  X TRCK TRK1 STRW  · start the song at row 00
Exec.Rows 01->02 after load

Rate-limiting through a variable

00 CALC EVRY =0|64 > ---- ---- ----  · true once per 100 runs
01 SKIP 01 = 00|=0 > ---- ---- ----  · skip the send otherwise
02 VAR  #  A SRC   > MCON TC 1 # 74  · CC 74, 10 times a second

↑ Contents

13 Control flow, without the jargon

Skip rows on a condition, and keep blocks of rows that run only when something calls them.

SKIP — leave out the next rows

When its comparison is true, SKIP leaves out the next 1–16 rows for this pass only; next pass they run again unless skipped again. The row shows the count and the comparison: SKIP 02 = 0A|=0 skips two rows while row 0A is 0. It exists as a source and as a destination; the destination version runs on every pass. To switch more than 16 rows with one condition, put them in a plain XMAP block and the SKIP in front of the XMAP row (below).

CTRL — blocks that run when called

A CTRL row’s extra is a row count (2RW); its function says when the block below runs. Rows run by a block are forced: their destinations fire even without a change. A SKIP inside a block has no effect — put the condition in front of the CTRL row, or use IF / PASS inside.

00 CV   IN 1 TH    > ---- ---- ----  · clean clock
01 CTRL XSHT 2RW   > ---- ---- ----  · next 2 rows: once per clock
02 CALC SHTR 02|=8 X ---- ---- ----  · 8-bit shift register
03 CALC BAND 02|=1 X TRIG TRIG TR 1  · its lowest bit

00 CV   IN 2 TH    > ---- ---- ----  · the switch
01 SKIP 01 = 00|=0 > ---- ---- ----  · skip row 02 while it is off
02 CTRL XMAP 2RW   > ---- ---- ----  · next 2 rows: every pass
03 CV   IN 1 VAL   X CV   PTCH CV 1  · pitch through
04 CV   IN 1 TH    X TRIG GATE TR 1  · gate through

CTRL as a destination

XSH^, XSHv and XSH! run the block below once on a rising, falling or any edge of this row’s own source — a MIDI note, a gate, a button — instead of the row above.

Several blocks, one destination

The change filter is kept per row, not per destination. If three SKIP-gated blocks take turns writing the same CV output, a block whose value equals what it sent last time stays silent — even if another block has written something else since. The output shows a stale value. Two fixes:

• Local outputs

  CV, triggers, track parameters: make each block’s last row CALC FORC. It writes on every run.

• MIDI, I2C, expanders

  Let every block write a variable with SETV, and add one unconditional row that sends the variable. That row alone owns the destination.

↑ Contents

★ Recipes — eight mappings that work

Each of these was run on the V3.03 mapping engine and does what it says. Build them, then change them.

1 · A random melody in a scale

00 CV   IN 1 TH    > ---- ---- ----  · clock in
01 CTRL XSHT 2RW   > ---- ---- ----  · once per clock
02 CALC RNDM 24|3C X ---- ---- ----  · a random note 36–60
03 CALC SCAL 3D|=0 X CV   NOTE CV 1  · into C minor pentatonic

2 · A clock divider

00 CV   IN 1 TH    > ---- ---- ----
01 CALC CDIV =4|=0 > TRIG TRIG TR 1  · every 4th clock

3 · Transpose a track by CV, 1 V per octave

00 CV   IN 1 VAL   > ---- ---- ----
01 CALC ADD  00|VA > TRCK TRK1 TPS   · VA = 811

4 · An eight-step sequencer you edit on the Variable screen

00 VAR  #  A SRC   > ---- ---- ----  · step 1 … rows 00–07 read A–H
07 VAR  #  H SRC   > ---- ---- ----  · step 8
08 CV   IN 1 TH    > ---- ---- ----  · clock in
09 CTRL XSHT 1RW   > ---- ---- ----  · once per clock
0A CALC INCW =0|=7 X ---- ---- ----  · step counter 0–7
0B CALC LDI  0A|=0 > CV   NOTE CV 1  · play row 00–07

5 · A gate that passes half the time

00 CV   IN 1 TH    > ---- ---- ----
01 CALC PROB VA|=1 > TRIG GATE TR 1  · VA = 800: 50 %

6 · A pattern that refills every 8 rows

The GLOB TICK → MOD 30 (48) → IF= … FILL FI 1 rows from chapter 11. Remember it only fills while the sequencer plays.

7 · A relative encoder

The two MCC event rows and SETV INC^ / DEC^ from chapter 05. Tested: each CC 32 = 127 message steps the variable once; a value of 5 does nothing.

8 · Start the song when the project loads

The XLOD block from chapter 12. Combine it with a VAR row per variable you want to preset.

↑ Contents

14 Rules & pitfalls

Read this before you call a mapping finished — every “it doesn’t do what I expected” ends up here.

↑ Contents

15 Saving, sharing & writing mappings with an LLM

A mapping travels with its project — and can also live on its own, as a file you share or have written for you.

Export and import

On the Mapping screen, SHIFT + AUTOMATE (NERD) opens the Nerd Menu:

Importing a part file replaces nothing: its rows are inserted at the cursor, and the rest of the mapping, its variables and its name stay. If the rows would overwrite used rows or don’t fit into the 70 rows, a popup asks first.

Let an LLM write the mapping

nerdseq_mapping_coding.md is a complete reference written for people and for AI tools. It describes how the engine runs, every source and destination with the exact numbers stored in a file, the 72 operations, worked examples and common mistakes, the scaling of every destination, the .MAP file format with all lookup tables (the same content as mapping_file_definition.txt), and a reference writer in Python.

1. Download the mapping programming guide (nerdseq_mapping_coding.md) and give it to an LLM tool — attach it, or paste it into the conversation.
2. Describe what you want in plain words: what comes in (which CV input, which MIDI channel), what should happen, and where it goes. “Clock on CV input 1; every clock a random note from C minor pentatonic between C2 and C4 on CV 1, and a gate on trigger 1 half the time.”
3. Ask for the rows as a table first, the way the Mapping screen shows them, with one line per row on what it does. Read them; ask about anything that looks odd.
4. Type the rows in, or ask for a .MAP file made with the reference writer. Copy it to projects/ on the SD card and use Import Mapping.
5. Test on the module: STOP the mapping, step with SHIFT + OK, watch Hex:, then START.

↑ Contents

16 Cheat sheet

One page to keep next to the Mapping screen.

The 15 source bases

The 19 destination bases

Keys

More about any of this: the NerdSEQ manual, and the NerdSEQ Field Guide, from the XOR downloads page.

↑ Contents