soundtower-controller/docs/PROTOCOL.md

Samsung control protocol notes

These original interoperability notes describe observations from an MX-T40 and analysis of the Android Sound Tower app version 0.0.80. Vendor application code and firmware are not included. The working desktop transport is BLE; the iOS app's internal transport/framework has not been established.

BLE endpoints

Role	UUID
Samsung service	0000ffa0-0000-1000-8000-00805f9b34fb
Write, with response	0000ffa1-0000-1000-8000-00805f9b34fb
Notify	0000ffa2-0000-1000-8000-00805f9b34fb

Subscribe before sending the connection request. Commands currently exposed by the GUI fit within 20 bytes; no larger-command fragmentation scheme is claimed. The speaker also exposes a separate Qualcomm service with UUID 00001100-d102-11e1-9b23-00025b00a5a5, which this controller does not use.

MX-T40 model advertisements include FE40/FF40; the Android discovery code also maps FE41/FF41 to T40 names. An advertisement UUID identifies discovery, not necessarily a writable control service.

Framing

00 BB TYPE SEQUENCE LENGTH_HI LENGTH_LO PAYLOAD... CHECKSUM

Type 0 is an acknowledgment; type 1 carries data. Length counts payload bytes only, in big-endian order. Outgoing sequence numbers cycle 1–127, matching the Android app's signed-byte rollover. Incoming notifications use a separate sequence counter, observed above 127 as well.

Outgoing checksums sum type, sequence, both length bytes, and payload, modulo 256. Incoming packets have several observed checksum variants:

• Connection/source reports: sum excluding type.
• Sound reports: sum including type.
• Lighting reports 51 03 MODE: captured packets match a checksum calculated as though MODE were 1, across Ambient/Dance/Star/Lover/Off observations.
• Play/pause echoes 70 11: the two captured replies similarly match a key slot of 1. This compatibility rule is scoped to that specific payload.

Why the firmware emits these variants is unknown. Strict decoding recognizes these observed rules. BLE uses advisory mode, retaining structurally framed packets with unfamiliar checksums and flagging them in the activity log. This is compatibility behavior, not a cryptographic integrity guarantee.

Handshake

1. Send payload 01.
2. Receive ACK and connection information beginning 02.
3. Send payload 04 (link complete).
4. Receive the ACK matching that outgoing sequence; only then enable controls.
5. Query source (32) and EQ (42 03).

The captured connection info contains model byte 34 and source IDs 01 02 04 05: Bluetooth, USB 1, AUX 1, AUX 2. The two bytes following the initial 02 are interpreted by the Android app as protocol version.

Payloads

Numbers below are hexadecimal unless explicitly called decimal.

Action	Payload
Remote key	70 KEY
Select source	30 SOURCE
Query source	32
Set sound option	40 TYPE OPTION VALUE EXTRA
Query sound option	42 TYPE
Set system option	50 TYPE VALUE
Query system option	52 TYPE
Set RGB color	60 02 RED GREEN BLUE

Sound TYPE: volume=1, subwoofer=2, EQ=3, bass=4, DJ=5, tempo=6, mute=7. For the implemented EQ/bass controls OPTION and EXTRA are zero. Sound replies use 41 TYPE VALUE VALUE2, a different layout from writes.

EQ values (decimal): Party=1, Standard=2, Hip-hop=3, EDM=4, Rock=5, Latin=6, House=7, Reggae=8. Bass values: on=0, off=1. Mute reports: on=1, off=2.

System TYPE=3 controls lighting. Mode values (decimal): Off=0, Ambient=1, Party=2, Dance=3, Thunder=4, Star=5, Lover=6, Color=7. Reply: 51 03 MODE. The speaker displays COLOR when the owner chooses an RGB color. The desktop queries lighting mode after RGB writes rather than treating ACK as mode proof.

Remote keys: volume up=0F, volume down=10, play/pause=11, mute=14. A reply 70 11 is a button-event echo, not an absolute playing/paused state.

Additional app commands, untested here

The app defines grouping 05 TYPE CONTROL, USB playback/browsing/status and repeat controls, DJ selection/levels, tempo, and Bluetooth multi-connect state. See FEATURES.md for the distinction between discovered and verified behavior. Do not infer arbitrary EQ-band access from the firmware configuration schema.

Evidence and limits

Tests contain small, independently captured packet fixtures: connection info, ACKs, source/EQ replies, lighting checksum variants, and play/pause echoes. Real Bluetooth addresses are replaced with synthetic ones. Physical verification covers one MX-T40 on Windows; other models, firmware versions, and platforms remain unverified. RFCOMM channel 1 worked initially but later failed repeatedly; no general explanation or guaranteed workaround has been established.