Bose ControlSpace / PowerMatch

Control of Bose Professional ControlSpace ESP and EX processors, PowerMatch and PowerShare amplifiers over the ASCII serial-over-Ethernet protocol on TCP 10055. Drives named Gain and Source Selector modules, physical input/output channels, ControlSpace Groups, and Parameter Set recall, and tracks level and mute state back into GEM zones.

This is the commercial-install path: the DSP design — module labels, group numbers, parameter sets — is authored in ControlSpace Designer by the audio contractor, and this driver addresses those objects by name and number. It does not commission the DSP.

Prerequisites

• The ControlSpace Designer project (or a printed schedule) giving the exact Module labels, Group numbers, and Parameter Set numbers you intend to control.
• Module labels must be unique across the design. If an Output module and a PEQ module are both named Left, neither will respond correctly to module commands.
• Network reachability from GEM to the processor on port 10055.

Enable live feedback while you are still in Designer

The processor only pushes asynchronous change notifications for modules whose label begins with # (for example renaming Hall to #Hall). Without that prefix, GEM learns about changes made from CC-16 / CC-64 wall panels only on the next poll. It costs nothing to add and it is much easier to do during commissioning than afterwards.

Setup steps

1. Confirm third-party control is enabled and note the port. It is fixed at 10055 on ESP-00, PowerMatch and PowerShare; on 1U ESP (880/1240/4120/1600) and EX devices it can be changed or disabled in the device properties in ControlSpace Designer.
2. Go to System → Devices → Add Device and choose the Bose ControlSpace / PowerMatch driver (registry key bose_controlspace).
3. Set Processor IP (ip) to the device address.
4. On a PowerMatch or PowerShare, set Maximum Level (dB) (max_db) to 0. Those outputs have no gain stage and stop at 0 dB — leaving it at the ESP default of 12 makes the top fifth of every GEM volume slider do nothing.
5. Create one Zone per controllable point, using the address forms below.
6. Run get_volume from the Script Console against a zone and confirm a value comes back before wiring the zone into a UI.

Zone address format

The three address forms map onto the three control surfaces the protocol exposes. Pick per zone.

Address form	Example	Targets	Wire commands
Module label	Main Volume	A named Gain module in the design	SA / GA with index 1 (level) and 2 (mute)
slot.channel	2.1	A physical input or output channel	SV / GV, SM / GM, SI
group:N	group:4	A ControlSpace Group	SG / GG, SN / GN, SH

Write slot, channel and group numbers in decimal

The protocol carries these as hexadecimal ASCII, but GEM zone addresses are written in decimal and converted by the driver. Dante input 12 on slot 10 is the zone address 10.12, which the driver sends as GV a,c. You never type hex.

Bose recommends addressing inputs and outputs by Module label rather than by slot and channel where you have the choice — module commands are stable across design changes that renumber physical slots, and they take plain dB rather than encoded steps.

For slots that carry both inputs and outputs, the output channels follow the inputs in one continuous range. On a 16-channel Dante card, Dante Out 1 is channel 17.

Attribute reference

Scope	Attribute	Direction	Notes
device	ip	required	LAN address of the processor or amplifier.
device	port	optional	Default 10055.
device	min_db	optional	dB mapped to 0%. Default -60 (the protocol floor).
device	max_db	optional	dB mapped to 100%. 12 for ESP/EX, 0 for PowerMatch/PowerShare.
device	status_interval	optional	Poll cadence in ms. Default 30000.
device	command_throttle	optional	Minimum ms between command lines. Default 100.
device	parameter_set	runtime, read-only	Last recalled Parameter Set. 0 means none since power-up.
device	standby	runtime, read-only	Amplifier standby state (PowerMatch / PowerShare).
device	power_state	runtime, read-only	on / off, derived from standby.
device	output_configuration	runtime, read-only	PowerMatch per-channel output mode reported by GC.
zone	volume	runtime	Level as 0–100 percent, scaled between min_db and max_db.
zone	gain	runtime	Level in absolute dB.
zone	mute_state	runtime	on / off.
zone	state	runtime	on when unmuted, off when muted.

Commands

Command	Arguments	Notes
on / off	address	Un-mute / mute. A DSP zone has no power, so on/off is mute.
mute_on / mute_off / mute_toggle	address	Toggle is native on all three address forms — no cached-state emulation.
set_volume	address, level	level is 0–100 percent, scaled between min_db and max_db.
set_gain	address, gain	Absolute dB, bypassing percent scaling.
volume_up / volume_down	address, steps	steps counts 0.5 dB increments. Default 2 (1 dB).
get_volume / get_mute	address	Replies update zone state asynchronously.
set_source	address, source	Selects input 1–16 on a Source Selector module. address must be a module label.
recall_parameter_set	preset	Parameter Set 1–255 in Designer numbering.
get_parameter_set	—	Queries the last recalled Parameter Set.
standby_on / standby_off / get_standby	—	PowerMatch and PowerShare only. ESP and EX reject these.
get_configuration	—	PowerMatch output configuration per channel.
get_zones	—	Reports the zones configured in GEM and re-polls each.
raw	command	Sends a raw protocol line. The trailing carriage return is added for you.

Protocol notes

Commands are ASCII lines terminated with a carriage return (0x0D). The two command families encode numbers differently, which is the single most common source of confusion when reading a packet capture:

• System and Device commands (SS, SG, SN, SH, SV, SM, SI) use hexadecimal numerals, and levels are 0.5 dB steps anchored at −60 dB. So 0x00 is −60 dB, 0x78 is 0 dB, 0x90 is +12 dB. SV 1,3,50 sets slot 1 channel 3 to −20 dB.
• Module commands (SA, GA) use plain decimal ASCII with the units stripped. SA"Main Volume">1=-6.5 sets that gain module to −6.5 dB.

Acknowledgement also differs by family. Module commands answer ACK (0x06) on success or NAK (0x15) plus a two-digit error code on failure:

Code	Meaning
01	Invalid module name — no match, or the label is duplicated in the design
02	Illegal index — wrong index value or count for that module type
03	Value out of range for that parameter
99	Unknown error

System and Device set commands are not acknowledged at all. The driver follows those sets with a query rather than assuming they landed, which is also why recall_parameter_set emits a GS immediately afterwards.

Because ACK and NAK arrive as bare control bytes with no carriage return, this driver frames the inbound stream itself instead of relying on a terminator split — a bare ACK sitting in the buffer would otherwise stall the next real response.

Known limitations

• No discovery. get_zones reports what GEM already has configured. Module labels, group numbers and parameter set numbers are not enumerable over this protocol; they live in the Designer project.
• Set Volume is ignored while a channel is muted. This is processor behaviour, not a driver limitation. Send mute_off first, or control level through a Gain module.
• volume_up / volume_down on a Gain module is computed, not native. Groups and physical channels have real increment commands (SH, SI); Gain modules do not, so the driver steps from the last known level. If the level has never been read it returns an error and requests state — retry a moment later.
• Only Gain and Source Selector modules are wrapped. Every other module type in the design (PEQ, compressor, matrix mixer, router, AEC, …) is reachable through the raw command using the index tables in the Bose protocol document, but has no first-class GEM command.
• Change notifications need the # prefix. Without it, and for any change GEM itself made, state comes only from the poll loop.
• Standby is amplifier-only. SY / GY are PowerMatch and PowerShare commands; ESP and EX processors reject them.
• Endpoints and MSA12X are out of scope. WP/EP/EX Dante endpoints and the MSA12X steerable array use UDP on port 49494 with a different command set. This driver speaks only the TCP 10055 protocol.

Troubleshooting

Symptom	Check
Connection refused	The device is at its connection limit — 8 on ESP-00 and PowerShare, 32 elsewhere — shared with any ControlSpace Remote clients. Close one and retry.
Connection drops when the contractor is on site	Expected. The processor closes third-party connections when ControlSpace Designer goes online to load a design. GEM reconnects automatically once Designer disconnects.
NAK 01 on every module command	The module label does not match, or two modules share that name. Labels are case- and space-sensitive and must be unique across the design.
NAK 02	Wrong index for that module type. A Gain module only has index 1 (level) and 2 (mute).
NAK 03	Value out of range — most often a dB value beyond the module's limits.
Volume commands do nothing	The channel is muted. The processor ignores Set Volume while muted.
Top of the volume slider does nothing	On PowerMatch / PowerShare set max_db to 0.
Levels track, but wall-panel changes do not	Add the # prefix to the module label in Designer, or shorten status_interval.
Standby commands rejected	The device is an ESP or EX. Standby is PowerMatch / PowerShare only.

Related

• Devices — device and attribute administration.
• AV Zones — binding a DSP zone as the volume device for an AV zone.