# Protocol reference (draft v0.1)

> The network control protocol EDC loudspeakers already speak — documented for third parties. Transport, discovery, framing, commands, telemetry, errors and versioning.
>
> Status: draft-spec. Canonical: https://www.edcacoustics.com/developers/protocol/

> **Status: draft specification for review.** EDC loudspeakers are controlled over Ethernet today by the Pro and Rapid apps. This page documents that path for third-party developers. Items marked `<TBD>` are facts EDC's engineers must confirm before the reference is final; nothing on this page should be coded against until it is marked *available*.

## What exists today

From EDC's published documents:

- Every S-Series cabinet has an RJ45 Ethernet port for **monitoring and control** (10/100 Mbit).
- The Rapid app's release notes record **UDP network control** (v1.1), **multicast support for VPN networks** (v1.7) and **wired network interfaces** (v2.0).
- The apps work **offline** on a project and apply changes to hardware on **Push / Apply**.
- All cabinets must be on the **same subnet**; static IP addressing is recommended; DHCP is on by default.
- The monitored version reports **per-transducer, thermal and amplifier faults**; cabinets carry an inbuilt measurement microphone.

## Transport

| Item | Value |
|---|---|
| Transport | UDP/IP |
| Control port | `<PORT_TBD>` |
| Reply port | `<PORT_TBD>` (paired listen/reply, following the d&b DS100 convention) |
| Multicast group | `<GROUP_TBD>` — used for discovery and VPN operation |
| Authentication | `<TBD>` — none on an isolated LAN is common in this category; state it explicitly |
| Versioning | Every message carries a protocol version; breaking changes announced 12 months ahead |

## Discovery

Devices answer a discovery request with model, serial, firmware, IP and array membership. Mechanism (broadcast, multicast or mDNS) `<TBD>`. Proposed device naming pattern for mDNS: `edc-<serial>.local`.

## Command groups

| Group | Commands | Notes |
|---|---|---|
| Device | identify, blink, reboot, get info, set network | |
| Inputs 1–3 | gain, mute, 8-band parametric EQ (type, bypass, frequency, gain, Q), compressor (attack, threshold, ratio, release, post-gain) | Mirrors the app's input page |
| Beams 1–4 | enable, aim (pan ±60°, tilt ±60°), shape (H/V width 2°–120°, H/V skew dB/°), level, delay, source input | Whether the cabinet accepts beam *parameters* or only pre-computed filter sets is `<TBD>` — see below |
| Presets | list, recall, store | Device- or array-level |
| Apply | commit staged changes | Mirrors Push/Apply |
| Status | temperature, fault list (transducer index, code, since), input levels, firmware | Subscribe for periodic push |

## The one design question

The apps calculate beam filters and push results to the cabinet. If the beam maths runs in the app, third parties can recall presets but cannot aim a beam from their own code without EDC's algorithm. If the cabinet accepts aim/shape parameters and computes filters itself, `/beam/n/aim` becomes a first-class command. EDC's answer decides the shape of the API, the SDK and the simulator.

## Errors

Every command returns `ok` or an error with a stable code and a human-readable message. Codes are documented here once the protocol is confirmed.

## Licence

The specification will be published under CC-BY-4.0 or an explicit royalty-free "implement freely, no NDA" statement; reference code under MIT. See [licence](/developers/license/).