BB84.MPX1

Introduction

BB84.MPX1 is a clean-room reimplementation of a MIDI System Exclusive (SysEx) editor and librarian for the Lexicon MPX 1 multi-effects processor (firmware V1.00 and V1.10). It replaces the 1998 16-bit Windows editor MPX1EDIT.EXE (WazWare), which cannot run on 64-bit operating systems. The implementation is written in C# on .NET 10, published with Native AOT, and is derived exclusively from Lexicon’s published MIDI Implementation document.

1. Purpose & Scope

Purpose: Define the architecture, protocol behavior, data contracts, constraints and acceptance criteria for BB84.MPX1 so that it can be implemented incrementally (see docs/roadmap.md).

In scope (release 1.0):

Out of scope (release 1.0):

Audience: Developers and AI coding agents implementing BB84.MPX1.

Assumptions:

2. Definitions

Term Definition
MPX 1 Lexicon MPX 1 Multi Processor FX unit.
SysEx MIDI System Exclusive message: starts with F0, ends with F7.
EOX End of Exclusive, byte F7.
Header First 5 bytes of every MPX 1 SysEx message: F0 06 09 <device id> <message class>.
Lexicon ID Manufacturer ID 06.
Product ID MPX 1 product ID 09.
Device ID 7-bit unit address 0x00–0x7F, set on the unit. 0x7F addresses all devices.
Message class Byte 5 of the header; identifies the message layout (section 4.3).
Nibble-ization Encoding where each data byte is sent as two bytes, each carrying 4 bits in its low nibble, least-significant nibble first.
Word 16-bit little-endian value; nibble-ized as 4 bytes, least-significant nibble first.
Control address Ordered list of 16-bit control level values (A, B, C, …) that locates a node in the control tree. The null address (zero levels) is the root.
Control level One position (A, B, C, …) in a control address. MPX 1 uses at most 5.
Node Any control address that holds a parameter.
Parameter type 16-bit ID of a parameter definition (name, size, flags, limits, display units). Many nodes can share one type.
Parameter description Message class 04 payload describing one parameter type.
Option Secondary parameter type attached to a parameter (for example, units). Option data follows parameter data. 0xFFFF = no option.
Control flags Bit field in a parameter description: 0x01 Patchable, 0x02 Automation, 0x04 Control Level (branch), 0x08 Bottom Control Level.
Branch Node whose control flags have 0x04 set; it has children.
Leaf Editable node; control flags 0x04 clear.
Dump Large parameter (for example, Setup, Display, LEDs) transferred through message class 01.
Program One of 250 stored effect programs: 0–199 presets, 200–249 user registers. 0xFFFF = active program.
Handshake Message class 12; carries flow-control commands (BUSY/READY, etc.).
Learned database Local cache of all parameter descriptions plus the control tree for one firmware version.
Simulator In-process software model of an MPX 1 that implements the transport interface.
Native AOT .NET ahead-of-time compilation to a self-contained native executable without JIT.
WinMM Windows Multimedia API (winmm.dll) used for MIDI I/O.
AC Acceptance criterion.

3. Requirements, Constraints & Guidelines

3.1 Protocol codec (PRO)

ID Class Name Direction Requirement
PRO-010 00 System Configuration Tx Parse major/minor version, 8-char build time, 11-char build date, parameter type count, bottom parameter number, max control levels.
PRO-011 01 Parameter Data Tx + Rx Parse/build byte count (word), data (parameter followed by option bytes), control address.
PRO-012 02 Parameter Display Tx Parse character count (word), string, control address.
PRO-013 03 Parameter Type Tx Parse parameter type word.
PRO-014 04 Parameter Description Tx Parse type, name length (byte), name, size in bytes (word), control flags (byte), option type (word), unit count (byte), then n × {min word, max word, display-units word}.
PRO-015 05 Parameter Label Tx Parse character count (word), string, control address.
PRO-016 06 Request Rx Build requests: requested class (nibble-ized byte) followed by class-specific arguments (section 4.4).
PRO-017 12 Handshake Tx + Rx Parse/build command byte: 0 NOP, 1 ARE_YOU_THERE, 2 IM_ALIVE, 3 BUSY, 4 READY, 5 ERROR.
PRO-018 16 Database Dump Tx + Rx Parse/build 250 entries × {effect-type word, source-type byte} (sort flags; bit tables in section 4.6).
PRO-019 18 Report Effect Parameters Tx Parse effect/controller type (byte), number (byte), 11-char name, parameter count (byte, 1–30), 30 parameter-type words (unused slots ignored).
PRO-020 19 Report All Effect Parameters Tx Parse program number (word), then 6 blocks (Pitch, Chorus, EQ, Mod, Reverb, Delay) × {11-char name, count byte, 30 type words}.
PRO-021 1A Program Information Tx Parse program number (word), 12-char name, 6 algorithm-number bytes (Pitch 0–10, Chorus 0–11, EQ 0–18, Mod 0–8, Reverb 0–5, Delay 0–8).
PRO-022 1B Program Dump Tx + Rx Parse/build the full program layout in section 4.5. Program number 0–249 or 0xFFFF.
PRO-023 1C Compact Program Dump — Documented as “Lexicon development use only”. Recognize the class, keep the raw bytes, and pass them through unchanged. Do not interpret the payload.
PRO-024 — Universal Device Inquiry Rx / Tx Build F0 7E <id> 06 01 F7; parse Identity Reply F0 7E <id> 06 02 06 00 00 09 00 <major> <minor> <phase> 00 F7.

3.2 Transport (TRN)

3.3 Session (SES)

3.4 Learning & database (LRN)

3.5 Parameters & values (PAR)

3.6 Programs & librarian (PRG)

3.7 Dumps & system (DMP)

Each dump is a Parameter Data (01) transfer at the control address the learned tree gives for its type. The dump shall be parsed into a typed model when its layout is documented, and kept as raw bytes otherwise.

ID Dump Type V1.00 / V1.10
DMP-001 All LEDs 0x012F / 0x0130
DMP-002 Display (32 chars) 0x011E / 0x011F
DMP-003 Custom Character Bitmap (8 chars) 0x0130 / 0x0131
DMP-004 Setup (5 stored + active) 0x0128 / 0x0129
DMP-005 Global Patches (10) 0x012D / 0x012E
DMP-006 Bypass Controllers (7) 0x012C / 0x012D
DMP-007 Remap Controllers (163) 0x012B / 0x012C
DMP-008 Current Choices 0x0125 / 0x0126
DMP-009 Patches (5 per active program) 0x0129 / 0x012A
DMP-010 Soft Row (10 per active program) 0x012A / 0x012B

3.8 Simulator (SIM)

3.9 User interface (UI)

3.10 Security (SEC)

3.11 Constraints (CON)

3.12 Guidelines (GUD)

3.13 Patterns (PAT)

4. Interfaces & Data Contracts

4.1 Solution layout

Project Kind Depends on
src/BB84.MPX1.Core Class library (AOT/trim compatible) —
src/BB84.MPX1.Midi Class library: transport abstraction + session Core
src/BB84.MPX1.Midi.WinMM Class library: WinMM adapter (Windows only) Midi
src/BB84.MPX1.Simulator Class library: simulated device + replay Core, Midi
src/BB84.MPX1.App Avalonia application, PublishAot=true Core, Midi, Midi.WinMM, Simulator
tests/BB84.MPX1.*.Tests MSTest projects, one per library project under test

4.2 Transport contract

public interface IMidiTransport : IAsyncDisposable
{
    IReadOnlyList<MidiPortInfo> GetInputPorts();
    IReadOnlyList<MidiPortInfo> GetOutputPorts();
    ValueTask OpenAsync(MidiPortId input, MidiPortId output, CancellationToken ct);
    ValueTask CloseAsync(CancellationToken ct);
    ValueTask SendSysExAsync(ReadOnlyMemory<byte> frame, CancellationToken ct);   // frame includes F0..F7
    ValueTask SendShortAsync(int message, CancellationToken ct);
    IAsyncEnumerable<MidiInput> ReadAllAsync(CancellationToken ct);              // SysEx frames + short messages
}

public sealed record MidiPortInfo(MidiPortId Id, string Name);
public readonly record struct MidiPortId(string Value);
public abstract record MidiInput(DateTimeOffset Timestamp);
public sealed record SysExInput(DateTimeOffset Timestamp, ReadOnlyMemory<byte> Frame) : MidiInput(Timestamp);
public sealed record ShortInput(DateTimeOffset Timestamp, int Message) : MidiInput(Timestamp);

4.3 Core message model

Namespace BB84.MPX1.Core.Protocol (program model in BB84.MPX1.Core.Programs).

public readonly struct ControlAddress : IEquatable<ControlAddress>     // structural equality; Root = no levels
{ public ImmutableArray<ushort> Levels { get; } public ControlAddress Child(ushort value); public ControlAddress Parent(); }
public readonly record struct DeviceId(byte Value);                    // 0..127, DeviceId.All = 127

public abstract record Mpx1Message(DeviceId Device) { public byte[] ToBytes(); }
public abstract record LexiconMessage(DeviceId Device) : Mpx1Message(Device) { public abstract MessageClass MessageClass { get; } }

// One sealed record per class (PRO-009):
// SystemConfiguration, ParameterData, ParameterDisplay, ParameterType, ParameterDescription, ParameterLabel,
// Request (static factories per spec 4.4), Handshake, DatabaseDump, EffectParameters, AllEffectParameters,
// ProgramInformation, ProgramDump (wraps Programs.ProgramData), RawLexiconMessage (1C and unknown classes),
// DeviceInquiry, IdentityReply (universal, not nibble-ized).

[Flags] public enum ParameterAttributes : byte { None = 0, Patchable = 0x01, Automation = 0x02, ControlLevel = 0x04, BottomControlLevel = 0x08 }
public enum HandshakeCommand : byte { Nop = 0, AreYouThere = 1, ImAlive = 2, Busy = 3, Ready = 4, Error = 5 }

public static class Mpx1Codec
{
    public static Mpx1Message Decode(ReadOnlySpan<byte> frame);          // throws Mpx1FormatException (Error.Offset)
    public static bool TryDecode(ReadOnlySpan<byte> frame, out Mpx1Message? message, out Mpx1FormatError? error);
    public static byte[] Encode(Mpx1Message message);
}

The “control flags” of a parameter description are modelled as ParameterAttributes, and the program sort flags as ProgramCategories (EffectCategories word + SourceCategories byte), because analyzer rule CA1711 forbids type names ending in “Flags”.

4.4 Request arguments (class 06)

After F0 06 09 <id> 06, the requested class is sent as one nibble-ized byte, followed by:

Requested class Arguments (all nibble-ized)
00 System Configuration 3 unused bytes (00 00 00 00 00 00)
01, 02, 03, 05 Control address: level count word + one word per level
04 Parameter Description Parameter type word
12 Handshake Command byte
16 Database Dump 3 unused bytes
18 Report Effect Parameters Effect type byte, algorithm number byte, 1 unused byte
19 Report All Effect Parameters Program number word, 1 unused byte
1A Program Information Program number word, 1 unused byte
1B Program Dump Program number word (0xFFFF = active), 1 unused byte

Effect/controller types for 18: 0 Pitch, 1 Chorus, 2 EQ, 3 Mod, 4 Reverb, 5 Delay, 6 Knob, 7 LFO 1, 8 LFO 2, 9 MIDI Arpeggiator, 10 ADSR 1, 11 ADSR 2, 12 Random Number Generator, 13 A-B Generator, 14 Sample and Hold, 15 Envelope Generator 1, 16 Envelope Generator 2. For types 6–16 the algorithm number is ignored.

4.5 Program Dump (1B) layout

Byte offsets are frame offsets (1-based, as in the source document). Sizes are un-nibble-ized bytes.

Frame bytes Field Size
6–9 Program number 2
10–393 Effect data: Pitch, Chorus, EQ, Mod, Reverb, Delay 6 × 32
394–399 Sort flags (effect word, source byte) 3
400–479 Audio routing: 8 blocks × {effect type, upper input, lower input, routing, patch type} 40
480–491 Algorithm numbers (Pitch, Chorus, EQ, Mod, Reverb, Delay) 6
492–515 Program name (space padded) 12
516–517 Effect status (bit 0 Pitch … bit 5 Delay; 1 = active) 1
518–557 Soft values: 10 × {effect/controller type, parameter index} 20
558–561 Tempo (41–400 BPM) 2
562–563 Tempo source (0 internal, 1 MIDI) 1
564–565 Beat value (0 eighth … 6 whole) 1
566–567 Tap source (Appendix A) 1
568–569 Tap average (1–8) 1
570–571 Tap source level (0–127) 1
572–573 Meter (0–24) 1
574–575 Master level 1
576–577 Master mix 1
578–697 Patches: 5 × 12 bytes 60
698–721 Knob: value, min, max, 9-char name 12
722–843 LFO 1 (8), LFO 2 (8), Arpeggiator (5), ADSR 1 (9), ADSR 2 (9), Random (4), A/B (5), Sample & Hold (5), Env Gen 1 (4), Env Gen 2 (4) 61
844 F7 —

Total frame length: 844 bytes. Total payload: 419 bytes.

4.6 Database Dump (16) sort flags

4.7 Persistence formats

Artifact Format Notes
Learned database JSON (source-generated), schemaVersion field Key: firmware major/minor + build date/time.
Application settings JSON Ports, device ID, timeouts, retries, inter-frame gap.
Program/backup files Raw .syx (concatenated frames) Interoperable with generic SysEx tools.
Simulator fixtures JSON Descriptions, tree, programs, dumps.
Recorded sessions JSON lines: {t, dir, hex} Input for replay transport and regression tests.

5. Acceptance Criteria

6. Test Automation Strategy

7. Rationale & Context

8. Dependencies & External Integrations

External Systems

Third-Party Services

Infrastructure Dependencies

Data Dependencies

Technology Platform Dependencies

Compliance Dependencies

9. Examples & Edge Cases

// Nibble-ized word 0x01C0 (parameter type count in System Configuration)
00 0C 01 00

// Parameter Data request: Program > EQ > 1 Band (M) > Gain  (A:0 B:2 C:1 D:2), device 0
F0 06 09 00 06 01 00 04 00 00 00 00 00 00 00 02 00 00 00 01 00 00 00 02 00 00 00 F7

// Request Report All Effect Parameters for the active program (0xFFFF)
F0 06 09 00 06 09 01 0F 0F 0F 0F 00 00 F7

Known inconsistencies in the source document that the implementation must handle:

# Location Issue Resolution
E1 Device Inquiry reply Header printed as 0xF0, 0xFE Use F0 7E (MIDI 1.0 Universal Non-Real-Time). Accept both when parsing.
E2 Handshake example F0 06 09 00 12 01 F7 sends one nibble for a 1-byte field Send 01 00. When parsing, accept a single nibble before F7.
E3 Classes 19, 1A Marked “Receive only” though the unit transmits them Treat as Tx (device to editor).
E4 Device ID range “0–127 transmit, 0–126 receive” vs. “all devices (127)” Allow 0–127. Treat 127 as broadcast; responses carry the real device ID.
E5 Database Dump byte offsets Offsets in the table are inconsistent Derive layout from field sizes: 250 × 3 bytes payload.
E6 Request class 10 “Memory Tool” Undocumented Never send (PRO-025).
E7 Text extraction Tables flattened in *.md Verify layouts against the original Lexicon PDF (kept outside the repository) before implementing.
E8 Tap Source range Starts at “Footswitch Pulse 1 (tip)”, not in Appendix A Start at Sw1 (0x1C, momentary foot switch 1). Confirm on hardware.
E9 Panel Button combinations Text names TIP/RING as a combination; table has no code Offer only Left + Right (15/2B/41); Tip and Ring are single buttons.
E10 Appendix D bug 2 address Dead end documented at A:1 B:2 C:0; a V1.00 unit (Nov 21 1996) has type 0x015B “Cont Remap” at A:1 B:2 C:3 and answers every address below it with 0x015B Detect the dead end by the echo (LRN-007), not by address. Observed on hardware in M8.
E11 Global Patch / Bypass sources DMP-011 ranges start at Pedal (0x18) and Tog1 (0x19); a V1.00 unit stores 0x17 / 0x18 in unused slots and describes the sources with that minimum and display units 0x29 (“None”) Accept the value below the first source as “None” in validation and display. Observed on hardware in M8.
E12 Setup dump size Layout is 44 bytes; “Global Bypass Level” exists only in V1.10. A V1.00 unit reports 43-byte setups (SetupDump, type 0x014C) and a 258-byte combined dump (0x0128, 6 × 43) Accept 43-byte setups with the V1.00 layout. Observed on hardware in M8.
E13 Setup dump order and single setups “5 stored setups and an active setup”; order not stated. On a V1.00 unit the combined dump (0x0128) holds the active setup first, then stored setups 1–5, and every single-setup address (A:1 B:13 C:n, type 0x014C) returns stored setup 1 Back up and restore setups only through the combined dump; skip single setups on restore when the firmware has it. Observed on hardware in M8.
E14 Parameter-type shift Rev1 says most types are +1 in V1.10. Rev0 shows why: V1.10 inserts 0x010B “Global Bypass Level” (Program Name is 0x010B in V1.00). Types below 0x010B keep their number; types from 0x010B up shift by +1 Still resolve every type through the learned database (LRN-005). Use the rule only to cross-check the documents.
E15 Rev1 V1.10 “parameter index” type Patch and Global Patches tables give 0x0140 for V1.10, which breaks the +1 rule (V1.00 0x0139) and collides with “Destination parameter index” (0x0140). Expected 0x013A Resolve through the learned database (LRN-005). Verify against the original Rev1 PDF (kept outside the repository) and a V1.10 unit.
E16 Merge/parallel block limit Rev0 states a maximum of 3; Rev1 states 2 in V1.10 and 3 in V1.00 Limit by firmware version (AudioRouting.MaxMixingBlocks).
E17 Panel Button codes Tap (0x44) and Toggle A/B (0x45) are listed as new in V1.10; Rev0 has neither Send them only to V1.10 units (PAR-007).
E18 Database Dump receive (16) “Transmit & Receive” with one layout. A V1.00 unit stores a received table with an offset in its first 100 bytes: received bytes 2–99 become bytes 0–97, bytes 98–99 become FF FF, bytes 100–749 are stored unchanged. It sends no BUSY/READY. The transmitted table has no offset, so writing back a backup shifts the sort flags of programs 1–33 Write sort flags only when they differ from the unit’s. On V1.00, write changed user programs as Program Dumps and send presets’ changes shifted by 2 bytes (SortFlagTable); the flags of programs 33 and 34 can then still differ and are reported. Read back after every write. Observed on hardware (issue #25); V1.10 not tested.
E19 Program Dump to a preset (1B) Not described. On a V1.00 unit a Program Dump to a preset (0–199) does not change its sort flags; a Program Dump to a user program does. A Program Dump read reports the sort flags of the Database Dump. Effect-data bytes after the loaded algorithm’s parameters vary between preset reads with the unit’s state (presets 1–138, mostly offsets 6 and 45: 04/42 before a restore, 02/4B after it, back to 04/42 later without any preset write) Restore user-program sort flags through their Program Dumps and preset flags through the Database Dump (E18). Compare programs without the unused effect-data bytes (ParameterDatabase.WithoutUnusedEffectBytes); they do not change the sound. Observed on hardware (issue #25).

Edge cases:

10. Validation Criteria