DruML SysEx Integration Guide

DruML is configured entirely over MIDI SysEx commands.  The device is primarily configured via a getter/setter interface with a list of parameter IDs. 

Connection

DruML devices appear as USB MIDI devices. To discover one programmatically:

Look for a device whose name contains druml (case-insensitive) or whose manufacturer is SOUP LABS

Protocol Basics

• Manufacturer ID: 0x4F
• Data types: 0x00 = INT32, 0x01 = FLOAT
• Checksum: Sum of all bytes between F0 and the checksum byte, masked & 0x7F

Frame Format

F0 4F [Command] [ParamID] [DataType] [Length] [Data...] [Checksum] F7

All multi-byte values are encoded as 7-bit MIDI bytes, MSB first. A 32-bit value requires 5 bytes.

Encoding INT32

Split the value into N 7-bit bytes (N = ceil(bit_length / 7), minimum 1). Send MSB first.

Encoding FLOAT

Reinterpret the IEEE 754 float as a 32-bit unsigned integer, then encode as 5 x 7-bit bytes, MSB first. To decode, reverse the process.

Commands

Connectivity

Byte	Command	Direction	Purpose
0x07	PING	Host→Dev	Check if alive
0x08	PONG	Dev→Host	Response to PING

Firmware Version

Byte	Command	Direction	Purpose
0x0A	GET_BUILD_NO	Host→Dev	Returns firmware build number

The build number is returned in the same frame format as a parameter response. Use this to determine which parameters are supported (see min_build in the parameter table).

Parameter Read/Write

Byte	Command	Direction	Purpose
0x01	SET_PARAMETER	Host→Dev	Write a parameter value
0x02	GET_CONFIG_PARAMETER	Host→Dev	Read a parameter value
0x03	PARAMETER_RESPONSE	Dev→Host	Response with parameter value
0x03	RESTORE_DEFAULTS	Host→Dev	Reset all parameters to factory defaults
0x09	RESTORE_DEFAULT	Host→Dev	Reset a single parameter (by ParamID)

Reading a parameter:

F0 4F 02 [ParamID] 00 00 [Checksum] F7

The device replies with a 0x03 PARAMETER_RESPONSE containing the ParamID, data type, and value.

Writing a parameter:

F0 4F 01 [ParamID] [DataType] [Length] [Data...] [Checksum] F7

The device confirms with a 0x03 PARAMETER_RESPONSE echoing the new value.

Device Identity

Byte	Command	Direction	Purpose
0x3B	GET_HARDWARE_ID	Host→Dev	Returns 20-bit device ID (matches USB descriptor suffix)
0x3C	GET_INSTRUMENT_TYPE	Host→Dev	Returns compile-time instrument type

The hardware ID is a 20-bit value derived from the STM32 UID. Format as a 5-character uppercase hex string (e.g. 0x1A2B3 → "1A2B3").

Calibration

Byte	Command	Direction	Purpose
0x37	CALIBRATE	Host→Dev	Start calibration (N samples)
0x39	GET_CALIBRATION_STATUS	Host→Dev	Returns 1 if calibrated, 0 if not

To start calibration, send a CALIBRATE command with the sample count encoded as an INT32 parameter value (typical: 50). The device will capture sensor data and auto-calibrate its amplifier gains. Poll GET_CALIBRATION_STATUS or re-read the gain parameters (0x3B–0x3D) afterward to confirm completion.

Configuration Parameters

All parameters are read/written via SET_PARAMETER (0x01) and GET_CONFIG_PARAMETER (0x02).

The min_build column indicates the minimum firmware build that supports the parameter. Query the build number first and only access parameters your firmware supports.

MIDI

ID	Name	Type	Min Build	Range	Description
0x37	Note: Center	INT	1365	0–127	MIDI note for center/mesh hits (default: 38 / D2)
0x36	Note: Rim	INT	1365	0–127	MIDI note for rim/hoop hits (default: 76 / F#5)
0x38	Note: Cross-stick	INT	1365	0–127	MIDI note for cross-stick hits (default: 37 / C#2)
0x39	Note: Rimshot	INT	1365	0–127	MIDI note for rimshot hits (default: 40 / E2)
0x3A	Note: Off-center	INT	1365	0–127	MIDI note for off-center hits (default: 35 / B1)
0x46	MIDI Channel	INT	1417	0–15	MIDI channel (0-indexed). Channel 10 (value 9) is GM drums.
0x1D	Rimshot As Note	INT	1365	0 or 1	1 = send rimshot as a single note. 0 = send simultaneous rim + center notes.
0x1E	Off-center As Note	INT	1365	0 or 1	1 = send off-center as a dedicated note. 0 = send as CC position data.
0x20	CC Position Enabled	INT	—	0 or 1	Enable CC16 positional sensing (0=center, 127=edge).
0x1F	CC Position Gain	FLOAT	—	0.0–127.0	Scales hit position into CC16 range. Increase until edge hits reliably reach 127.
0x35	Off-center CC Point	INT	1365	0–127	CC threshold that triggers the off-center note (when Off-center As Note = 1).

Volume

ID	Name	Type	Min Build	Range	Description
0x23	Center Zone Gain	FLOAT	—	0.0–2.0	How much the center sensor contributes to velocity.
0x22	Rim Zone Gain	FLOAT	—	0.0–2.0	How much the rim sensor contributes to velocity.
0x21	Outer Zone Gain	FLOAT	—	0.0–2.0	How much the edge sensor contributes to velocity.
0x33	Volume Nonlinearity	FLOAT	1354	0.1–10.0	Velocity curve shape. <1 = quick rise then plateau. >1 = slow rise then steep.
0x3E	Note Gain: Center	FLOAT	1395	0.0–2.0	Per-articulation velocity scaling for center hits.
0x3F	Note Gain: Rim	FLOAT	1395	0.0–2.0	Per-articulation velocity scaling for rim hits.
0x40	Note Gain: Cross-stick	FLOAT	1395	0.0–2.0	Per-articulation velocity scaling for cross-stick.
0x41	Note Gain: Rimshot	FLOAT	1395	0.0–2.0	Per-articulation velocity scaling for rimshot.
0x42	Note Gain: Muted	FLOAT	1395	0.0–2.0	Per-articulation velocity scaling for muted hits.

Triggering

ID	Name	Type	Min Build	Range	Description
0x34	Min Peak Confidence	FLOAT	1360	0.0–1.0	Overall hit detection threshold. Lower = more sensitive.
0x15	Noise Min Confidence	FLOAT	1365	0.0–1.0	Threshold for rejecting false positives (stick noise, vibration).
0x16	Rim Min Confidence	FLOAT	1365	0.0–1.0	Minimum confidence for a rim hit classification.
0x17	Center Min Confidence	FLOAT	1365	0.0–1.0	Minimum confidence for a center hit classification.
0x18	Muted Min Confidence	FLOAT	1365	0.0–1.0	Minimum confidence for a muted hit classification.
0x1B	Cross-stick Min Confidence	FLOAT	1365	0.0–1.0	Minimum confidence for a cross-stick classification.
0x1C	Rimshot Min Confidence	FLOAT	1365	0.0–1.0	Minimum confidence for a rimshot classification.

Touch Sensor

ID	Name	Type	Min Build	Range	Description
0x43	Touch Latch On (ms)	INT	1405	10–200	Detection window for touch engagement. Quantized to 10ms steps.
0x44	Touch Latch Off (ms)	INT	1405	10–200	Detection window for touch release. Quantized to 10ms steps.
0x45	Touch Sensitivity	FLOAT	1408	0.1–1.0	Detection threshold. Lower = more sensitive.

Hardware / Calibration

ID	Name	Type	Min Build	Range	Description
0x3B	Gain: Center	FLOAT	1380	0.0–10.0	Amplifier gain for center sensor. Typically factory-set; re-calibrate after changing.
0x3C	Gain: Rim	FLOAT	1380	0.0–10.0	Amplifier gain for rim sensor. Increase for easier rimshots. Re-calibrate after changing.
0x3D	Gain: Edge	FLOAT	1380	0.0–10.0	Amplifier gain for edge sensor. Typically factory-set; re-calibrate after changing.