The DigiNet surface protocol (Control|24, ProControl)

What is known about the protocol the Digidesign Control|24 and ProControl speak over Ethernet, gathered from the projects listed below. Every claim names its source. Nothing here was taken from a vendor document. Items marked unknown are settled by captures on a real unit (see the end of this file).

Sources

Line citations below are to these commits.

The protocol

Transport

The header (16 bytes after the 14-byte Ethernet header, big-endian; control24d.py:137-150):

Discovery and handshake:

1. The desk broadcasts an e0 announce about every 7 s when idle (ProControl: 4 in 30 s, 104 in 740 s; procontrol-linux docs/observations-2026-09-13.md:60,73). The body is 14 unknown bytes, then the version from byte 14 (v1.08: byte 14 is the letter v), then the device name from byte 24: CNTRL|24 for a Control|24, MAINUNIT for a ProControl (control24d.py:168-176; ReaControl.py:624-636; test/emulator.py:14-17). C24-Engine reads the version at body bytes 14–24 and the name at 24–32 (motore.py:1191-1198), which every announce in r15b.pcap and walk2.pcap bears out. ReaControl's layout, and this library's (diginet_frame.c:148), read the version from byte 15, so they give 1.08 without the v.
2. The host sends e2 with no body (control24d.py:414), at send counter 0: a Control|24 takes a session on no other (#41). ReaControl then sends a clock-clear frame F0 13 01 30 19 00 … F7 with checksum 02 44 (control24d.py:415-418). After the 30 it carries 9 or 10 bytes: the counter address 19 and eight zeros, or with the dots byte as the counter message has it. The zeros add nothing to the sum, so 02 44 fits both. procontrol-linux showed the clock frame is not needed (docs/session-reference.md, "Essai local").
3. The desk ACKs (a0, ack counter = our sequence). A ProControl then switches its broadcasts to e1, which carries the host MAC, so on a ProControl an e1 announce is the "online" proof and an ACK alone is not (procontrol-linux docs/online-2026-09-13.md:35-36). A Control|24 enters its session only once the host has sent in it (firmware 1.08, captures on the desk, #41, #48). After a boot it announces e0, answers an e2 at send counter 0 with a0 (an e2 at any other counter it only ACKs), and keeps announcing e0. A host that goes online on that a0 and sends sees every frame ACKed; at the desk's next e0 it sends another e2, and 1 ms later the desk announces e1 naming the host, and e1 only from then on. That second e2 opens a new session on the desk, which blanks its scribbles (the faders keep their place), so its first e1 is ONLINE again for the host (DIGINET_R_RENEWED), which shows everything again. A host that waits for e1 before it sends is answered a0 to every e2 and never sees one: so on a Control|24 the a0 is the online proof. Out of session it still ACKs every host data frame and shows Offline. Once an e1 has named the host, an e0 is a desk out of session, after a reboot: it ends the session, which the host then wakes again. A Control|24 that boots while large unknown broadcasts reach it ignores every host: booted with reac-pw sending about 32 REAC frames of 1492 bytes a second on its link, it ACKed no e2, ours nor ReaControl24's, and stopping the traffic did not bring it back; booted on a quiet link it took the session at once. Such a desk keeps announcing and lets every e2 time out, and nothing on the wire names the cause, so the session reports it on its own: after deaf_wakes (3) wakes in a row that time out while the desk still announces (an announce within offline_ms), it gives DIGINET_N_DESK_DEAF once (#35). An a0 for an e2, an e1 naming another host (DIGINET_N_FOREIGN, a different notice: that desk hears hosts) or a timeout with no recent announce ends the count.
4. Disconnect is e3 with no body. It drops the session (C24-Engine motore.py:1069-1079, "the CORRECT way to disconnect"). A Control|24 (firmware 1.08, measured 2026-10-29, #33) then keeps announcing e1 naming that host for about 30 s (34 s and 30 s), until its own timeout, before it falls back to e0. With auto_wake the session therefore sends e2 on an e1 naming its own host as it does on an e0, so a restarted host need not wait for the desk to time out.

C24-Engine sends e2 five times 5 ms apart, waits 200 ms and then drives the desk without waiting for an ACK or an e1 (motore.py:1172-1189). It treats any frame from the desk as the desk being there.

Acks, sequencing, retransmit:

• Every desk data frame gets a host ACK. ReaControl sends it about 0.8 ms after receipt (TIMING_BEFORE_ACKT, control24d.py:48, :445-447), with the desk's sendcounter in our cmdcounter field (:499-500). ReaControl does not advance its own counter on an ACK; C24-Engine does (motore.py:940-948). Both work, so the desk tolerates either.
• Host→desk is stop-and-wait: one frame in flight. receive_handler blocks on sendlock until the desk's a0 arrives (control24d.py:460-468). It logs every 100 ms and never gives up or retransmits: #TODO implement daw-desk retry packets (:463). procontrol-linux kept the same one-frame window (docs/fader-echo-2026-09-14.md, "une seule trame en attente d'ACK").
• When the desk sends a retry frame, ReaControl pauses its own sending for 300 ms (TIMING_BACKOFF, control24d.py:53, :433-437).
• C24-Engine does not wait for ACKs at all: it sends frame after frame, never retransmits, and never sets or reads the retry field (motore.py:516-550). So the desk accepts more than one host frame in flight.
• Batching: up to 48 commands or 314 bytes per frame (control24d.py:298-299, :333-341). C24-Engine packs whole display batches into one frame, up to 51 commands and 461 bytes when it initialises the scribble strips (motore.py:962-984) and 100 LED commands when it blanks the desk (:1036-1067), and paces display batches about 2 ms apart, "so the desk's controller renders cleanly (no datamoshing)" (motore.py:531-550).

Keepalive (a real bug in the reference):

• ReaControl sends a keepalive frame (body 00, ncmds 1) when nothing has been sent for 10 s (control24d.py:46, :285-293, :507-511). But every ACK counts as "sent" (pcap_last_sent, :484), so a busy surface never sends one.
• procontrol-linux measured a 48 s gap between keepalives with 225 ACKs in between, and the desk fell back to e0 (offline). Their fix is a keepalive every 10 s regardless of ACKs (docs/online-2026-09-13.md:136-160). After the fix the longest gap was 10.048 s and the desk stayed online.
• C24-Engine pings every 1 s with an empty 16-byte data frame (count 0, no body), and declares the desk offline after 4 s with no traffic (motore.py:404, :951-960, :1023-1034). Its calculator pings every 2.5 s (Calculator24/Calculator24.py:78-81). The desk accepts both keepalive forms, the empty frame and the body 00.
• The desk-side timeout is not measured; "about 45 s" is an upper bound on the ProControl.

One socket, every interface (libdiginet's own, #35):

Nothing in the protocol ties a desk to an interface: it broadcasts its announce on whatever link it is cabled to, and a host answers from that link's MAC. So one AF_PACKET socket bound to EtherType 0x885F on no interface (diginet_packet_open_any()) hears every desk on every interface, interfaces that come up later included (a USB adapter plugged in afterwards). Each frame comes with the index of the interface it arrived on (diginet_packet_recvfrom()), and a frame goes out of one named interface (diginet_packet_sendto()); a host MAC is the MAC of the desk's interface (diginet_if_mac()).

• The desk mux (diginet_mux.h) runs one session per desk over that socket. A desk is keyed by its MAC. Its first valid announce, from a Digidesign MAC, makes it present on the interface it came in on (DIGINET_MUX_N_APPEARED); from then on its frames come from that interface only, and the same MAC on another interface while it is present (a bridge and its port both show a frame) is set aside. An attached desk's session sends out of the desk's interface, from that interface's MAC.
• A desk that moved between interfaces of one host (#40): it keeps announcing e1 naming the first interface's MAC until its own timeout, about 30 s (step 4 of the handshake). Each attached session carries this host's other interface MACs (other_host_macs, from the io's host_macs, diginet_host_macs() on the packet socket), so that e1 is this host's own session, not DIGINET_N_FOREIGN, and auto_wake takes it at once from the new interface. Only an e1 naming the session's own interface MAC is the online proof. A MAC of no interface of this host is still another host's session. Two daemons on two interfaces of one host are one host to the desk mux: R13's one daemon per desk holds there too.
• Gone: nothing from the desk for gone_ms (30 s), or its session ended on silence (DIGINET_R_SILENCE, nothing for offline_ms, 25 s): DIGINET_MUX_N_GONE. 30 s is more than three announce periods (6.0-9.4 s, #29) and more than offline_ms, so an attached session gives up first. A Control|24 in an e0 session loses it sooner, on its first unACKed keepalive (DIGINET_R_ACK_LOST), and is then gone at gone_ms.
• The capability: cap_net_raw is checked when the socket is opened, never after. diginet-packet-helper holds it, opens the socket, passes it over a Unix socket (SCM_RIGHTS) and exits; diginet_packet_open_by_helper() starts it and takes the socket, and diginet_packet_receive_fd() takes only an AF_PACKET socket. The program that drives the desks holds no capability.
• What the socket also hears. It hears 0x885F on every interface, a REAC trunk included, and the mux would answer a desk there. The mux reports each desk's interface; whether a host should refuse a desk on an interface that carries REAC is the host's to rule, from that interface.

The command set (body)

The body is a byte stream of MIDI-shaped messages. Running status occurs: C24-Engine expands it before parsing (motore.py:1100-1137, :1209), and says a desk fader move arrives as B0 tt MSB (20+tt) LSB with the second B0 left out. ReaControl instead splits on known status bytes and F7 (control24osc.py:1175-1200), which mis-parses running status. The desk uses the same encoding in both directions for faders, buttons and LEDs.

Faders (24 motor faders) — decoded:

• Desk→host and host→desk: B0 tt MSB (20+tt) LSB, a 14-bit MIDI CC pair carrying a 10-bit position: MSB = v>>3, LSB = (v&7)<<4 (control24osc.py:166-176, :916-920, :986-1001).
  • Example: v = 512 gives B0 tt 40 (20+tt) 00.
  • C24-Engine writes and reads plain 14-bit values, MSB = v>>7, LSB = v&0x7F (motore.py:585-590, :1345-1372). These are the same bytes with the low 4 bits used.
• procontrol-linux confirmed raw travel of 0–1023 on fader 1 (docs/protocol.md, register row "Fader 1 et contact").
• Touch: a strip button 90 09 (40|tt) on touch, 90 09 tt on release (control24map.py:942-946).
• The motor holds a set-point. ReaControl echoes the hand's position back to the desk at most every 100 ms during a move (control24osc.py:974-976, TIMING_FADER_ECHO :50), and re-sends the last position on release (:978-983).
  • procontrol-linux filmed the consequence of a late echo: on release the motor drove back to the old set-point, then to the new one (docs/fader-echo-2026-09-14.md).
  • Their fix: echo the exact physical value immediately on release, and refuse any other host value while the cap is touched.
  • Status: encoding decoded. Whether the motor pushes against a touched cap is unknown on the C24.

V-Pots (24) and jog wheel — decoded:

• Turn: B0 (40|tt) dd with delta = dd − 64 (control24map.py:20-36; control24osc.py:890-906).
• ReaControl reads a 4th "velocity" byte (control24osc.py:893). The ProControl logs show that byte is stale buffer content (pro_control_map.csv, rows 5/15/25: arbitrary values), so treat V-Pot input as 3 bytes.
• The jog wheel is "virtual track 28": B0 5C dd, delta = dd − 64 (control24osc.py:369-373, :746-775; procontrol-linux docs/protocol.md, "Le jog b0 5c valeur"). C24-Engine reads V-Pots and jog the same way, three bytes each (motore.py:1374-1391), and hands the jog on with its sign inverted relative to the V-Pots. Which way of turning gives dd > 64 on each control is unknown.
• Scrub and Shuttle are buttons in zone 0x1C, ids 0x12/0x13 (control24map.py:746-756).

V-Pot LED rings (15 LEDs) — decoded:

• F0 13 01 00 (tt | 0x40·LED1) b1 b2 F7: bit 6 of the address byte lights LED 1, b1 bits 6..0 are LEDs 2..8, b2 bits 6..0 are LEDs 9..15.
• ReaControl ships dot and fill tables (control24osc.py:783-816, :864-882). C24-Engine computes the same, LED 1 in the address byte and LED 2 at bit 6 of b1 (motore.py:633-643).

Buttons and LEDs — decoded, about 200 controls mapped:

• Strip buttons: 90 bb (40·pressed | tt), where bb is the button: 00 RecArm, 01 Pan/Send, 02 EQ, 03 Dynamics, 04 Switch/Active, 05 auto-mode, 06 Select, 07 Solo, 08 Mute, 09 fader Touch, 0A Inserts, 0B Peak, 0C SourceToggle, 0D RollOff (control24map.py:886-962).
• Section buttons: 90 bb (40·pressed | zone), zone 0x18..0x1D (control24map.py:37-48, ChildByteMatch 0x18):

• LEDs use the same 3-byte message: 90 bb (40·on | zone-or-track). ReaControl builds its LED table by walking the input map (control24osc.py:178-208, :1005-1062). C24-Engine: send_native_button_led (motore.py:552-556) and a separately discovered LED dictionary (Control24-LED-Finder/c24_led_dictionary.json, 1149 lines, facts only).
• Per-strip automation LEDs: F0 13 01 20 tt bits F7 with write 0x40, touch 0x20, latch 0x10, trim 0x08, read 0x04 (control24osc.py:1082-1098). C24-Engine uses the same values (motore.py:777-779), noting that its first version had touch and trim swapped; its docstring at :438-440 still shows the swapped pair.
• Counter-mode LEDs: F0 13 01 20 19 xx F7 (control24osc.py:429-456), with timecode 0x20, feet+frames 0x10, bars|beats 0x08, min:sec 0x40, all off 0x00 (motore.py:339-343, :449-470).
• Status: the map covers what a mixing console needs. Some zone assignments are ReaControl's names and are unverified on a C24.

Scribble strips — decoded, with one open point:

• F0 13 01 40 aa 00 c1 c2 c3 c4 F7: 4 characters, plain ASCII, padded with spaces (control24osc.py:609-673).
• Special glyphs: a "dot plus small digit" glyph for .1...9 is chr(ord(d) − 26), i.e. 0x17..0x1F (control24osc.py:662-671).
• Addresses:
  • ReaControl writes strip n at aa = n (0x00..0x17), plus virtual 24..31 (control24osc.py:375-376, :631).
  • C24-Engine writes names at aa = 0x20+n (motore.py:962-975) and the two centre "channel bar" displays at 0x1D/0x1E (motore.py:558-565).
  • On the ProControl, 00..07 is the top row and 20..27 the bottom row, 8 characters each (issue #12; procontrol-linux docs/displays.md).
  • What 0x00+n versus 0x20+n means on a Control|24 (two layers, two rows, or aliases) is unknown.
• long_scribble spreads a 96-character message over all strips (control24osc.py:338-345).

Meters — encoding decoded, physical segment count unknown:

• F0 13 01 10 ch hi lo F7, with ch 0..23 left and 0x20+ch right; bus meters start at 24/56 (control24osc.py:540-606).
• The value is a thermometer bitmask over 14 bits (two 7-bit bytes): n segments lit is the n lowest bits, hi = mask>>7, lo = mask&0x7F. ReaControl's 15-step table is at :552-568; C24-Engine builds the mask the same way, at most 14 bits, and refreshes at 25 Hz (motore.py:913-928; Camilla24/camilla_engine.py:92, "the C24 bitmask holds up to 14").
• Whether the desk decays a lit meter on its own (as the X-Touch does) is unknown.

Counter / timecode — decoded:

• F0 13 01 30 19 dots d8 … d1 F7: 8 seven-segment digits, the rightmost first (d8 … d1 with d1 the leftmost), then F7 (control24osc.py:382-425, :459-520; motore.py:616-631; HUI-OS/HUI_OS.py:612-626; Calculator24/Calculator24.py:83-112).
• A segment byte has bit 6 = a, 5 = b, 4 = c, 3 = d, 2 = e, 1 = f, 0 = g: C24-Engine draws 0 as 0x7E, 1 as 0x30, - as 0x01, E as 0x4F and r as 0x05 (motore.py:616-619; Calculator24/Calculator24.py:27-31). The library's table covers 0–9 and A b C d E F H h J L o P r S U Y Z -.
• The dots byte: bit k lights the dot after the k-th digit from the left (bit 0 the leftmost). The rightmost digit has no dot bit. C24-Engine's calculator shows "12.5" with dots = 0x40, and its clock puts the minutes dot at bit 5 (Calculator24/Calculator24.py:83-93; HUI-OS/HUI_OS.py:612-621; motore.py:621-626).
• The ProControl uses address 0x09 and device byte 00 instead of 0x19 and 01 (procontrol-linux docs/displays.md).

System and diagnostic family F0 13 xx 70 … — dangerous:

• Device-name write to the desk's memory: F0 13 01 70 00 6E <8 chars> F7 (C24-Engine motore.py:566-574).
• On the ProControl the same family reads firmware memory (70 00 comm processor, 70 01 faders) and produced spurious touch events (procontrol-linux docs/protocol.md, top section; docs/fader-touch-recovery-2026-09-21.md).
• The desk sends this family itself: in r15b.pcap a Control|24 1.08 sent F0 13 01 70 01 4F 4B F7 and F0 13 01 70 01 0A 0D F7 (packets 735 and 737). What they mean is not known.
• A host must never send this family; the library refuses to encode it.

The device byte after F0 13 is 01 for the Control|24 and 00 for the ProControl main unit (issue #22 trace f0 13 00 40 …; procontrol-linux docs/protocol.md). This is a per-device personality, not a constant.

Sources and licences

ReaControl24 and procontrol-linux are GPL-3.0-or-later, like this library. C24-Engine-Renewed carries no licence, so only facts come from it (byte layouts, bit orders, timings), never code or tables. libdiginet is a new implementation written from this description, not a port: the byte grammar lives in diginet.ksy, each field cited to the sources above.

Checked against C24-Engine-Renewed

C24-Engine-Renewed drives a real Control|24 from a working host, so each point it touches is compared here with what this library does. Citations are to its files at commit 94d7a3b.

Assumptions

Each point below is a choice libdiginet makes in one constant or one function, so a capture that contradicts it is a one-line change. Where C24-Engine-Renewed decides the point, the library follows it; a capture on our own unit is still the last word.

Open questions and how to settle them on a unit