User Manual: SoundBlocks Configurator

Syntax specifications, wireless network architecture, and diagnostic troubleshooting guide for SoundBlocks modules.

1. Introduction

SoundBlocks Configurator is the software environment designed to define interactive communication and sound synthesis between SoundBlocks hardware modules over a local wireless network.

Each physical module has a unique numerical identifier (ID) within the range of 2 to 254. A module transmits its sensor readings to the network or acts as a receiver, triggering audio samples and sound synthesis parameters.

Sender Node ID: 122
Tilt Sensor (ax)

➔ 122->ax:108

Wireless Network Data Packet

➔ 108<-ax:122@Vol[0,15]

Receiver Node ID: 108
Volume Adjustment

2. Quick Start

A SoundBlocks configuration script consists of concise, line-by-line declared rules. Below is a complete, interactive configuration script:

Basic Configuration Example

# Basic setup: Audio control using a touch sensor
# 1. Module 10 transmits the touch sensor t1 signal to Module 20
10->t1:20

# 2. Module 20 listens to Module 10 and plays audio sample #3 when t1 is triggered
20<-t1:10@Play[3]

📌 Deployment Sequence for Modules:

Write or paste your rules into the software editor.
Select the active network interface in Configure ➔ IP Address.
Click Verify (Ctrl+R) to check syntax validity.
Click Upload (Ctrl+U) to transmit the configuration to the module network.

3. Send Rules (`->`)

Specifies which local onboard sensors a module broadcasts to the network and sets the authorized destination modules.

Send Rule Structure

SENDER_ID -> SENSOR_1,SENSOR_2 : DESTINATION_1,DESTINATION_2

Structural Specifications

SENDER_ID: Transmitting module identifier (range: 2 to 254).
SENSORS: Comma-separated sensor codes (e.g., t1,ax,gz).
DESTINATIONS: Authorized receiver modules:
- Explicit modules: 102,105
- Continuous ranges using hyphens: 105-108 (covers 105, 106, 107, and 108).
- Broadcast Mode: Use ID 255 to transmit to all network nodes.

⚠️ Compiler Limits for Send Rules:

Maximum 3 destination blocks or ranges per instruction line.
Maximum 5 explicit receiver modules per rule.
Maximum 40 send rules per individual module.

Practical Send Example

Sensor Data Transmission

# Module 122 transmits touch sensor t1 and accelerometer ax to modules 102, 105, 106, 107, and 108
122->t1,ax:102,105-108

# Module 50 transmits gyroscope angular velocity gx to ALL connected network modules (Broadcast)
50->gx:255

4. Receive Rules (`<-`)

Configures the audio action or synthesis parameter executed by the local module when receiving sensor data from a transmitter node.

Receive Rule Structure

RECEIVER_ID <- SENSOR : SENDER_ID @ACTION [MAPPING]

Value Mapping `[Min, Max]`

The parameter inside square brackets [...] defines the control scaling range:

Two parameters [min, max]: Proportionally scales incoming sensor data. E.g., Vol[0,15] scales volume between 0 and 15.
Single parameter [value]: Sets a fixed selector parameter. E.g., Play[5] strictly selects audio sample #5.
No parameters / Default: Defaults to [0,0] if omitted. Commands such as Stop, Pause, or Resume require no brackets.

⚠️ Receive Memory Limit:

A module can store a maximum of 30 receive rules in physical memory.

Practical Receive Example

Mapping and Executing Actions

# Module 108 scales volume (range 0-15) based on acceleration 'ax' from Module 122
108<-ax:122@Vol[0,15]

# Module 102 triggers audio sample #3 when receiving touch signal 't7' from Module 108
102<-t7:108@Play[3]

# Module 40 stops playback upon receiving 't1' from Module 10
40<-t1:10@Stop

5. Sensors Reference

Interactive index of built-in hardware sensors:

Code (SBC)	Sensor Description
`t1` - `t7`	Capacitive touch sensors (7 independent inputs).
`ax`, `ay`, `az`	Accelerometer: Tilt / Linear acceleration along X, Y, Z axes.
`aax`, `aay`, `aaz`	Absolute Accelerometer: Absolute values (\|X\|, \|Y\|, \|Z\|).
`gx`, `gy`, `gz`	Gyroscope: Angular velocity along X, Y, Z axes.
`agx`, `agy`, `agz`	Absolute Gyroscope: Absolute angular rotation speed.
`rx`, `ry`, `rz`	3D Spatial Orientation (Yaw, Pitch, Roll).

No matching sensors found.

6. Actions Reference

Playback commands and sound synthesis parameters:

Command	Function Description	Valid Range
`Play`	Plays the specified audio sample.	1 - 127
`Loop`	Plays the specified audio sample continuously.	1 - 127
`Pause`	Pauses currently active sample playback.	No parameter
`Stop`	Stops playback completely.	No parameter
`Resume`	Resumes paused audio playback.	No parameter
`Vol`	Adjusts the master volume of the module.	1 - 30
`PlayStop`	Toggles between play and stop on trigger.	1 - 127
`PlayPause`	Toggles between play/pause and resume on trigger.	1 - 127
`PlayTouch`	Plays sample only while touch input is held.	1 - 127
`PlaySweep`	Progressively sweeps through audio samples.	1 - 127
`Wave1` - `Wave3`	Oscillator waveform (1=Triangle, 2=Sawtooth, 3=Square).	1 - 3
`Freq1` - `Freq3`	Synthesizer oscillator frequency.	1 - 127
`Gain1` - `Gain3`	Individual oscillator volume level.	1 - 127
`GainNoise`	White noise generator volume level.	1 - 127

No matching actions found.

7. Troubleshooting (Console & Errors)

Diagnostics based on error messages returned by the compiler checker:

⚠️ Error: Send ID must be between 2 and 254.

Cause: Transmitter module ID is outside the assignable hardware range (e.g., ID 0, 1, or greater than 254).

Fix: Check module hardware labels and assign an ID between 2 and 254.

⚠️ Error: Maximum 5 IDs per message.

Cause: The combined number of receiver IDs in a single send line (->) exceeds 5 nodes.

Fix: Split targets across multiple instruction lines or use Broadcast ID 255.

⚠️ Error: Maximum number of sends (40) reached for module X.

Cause: The module has exceeded its memory allocation limit for outgoing transmission rules.

Fix: Combine multiple sensors onto single send lines (e.g., 12 -> t1,t2,ax : 20 instead of 3 separate rules).

⚠️ Error: on upload connect.

Cause: Failed to open a WebSocket communication connection with the target IP address on Port 12001.

Fix:
1. Ensure your computer is connected to the same wireless network as the SoundBlocks modules.
2. Confirm that the subnet in Configure ➔ IP Address matches your active network adapter.