DSP-ADAU1467/CLAUDE.md

CLAUDE.md — ModulosDSP_101

What This Is

Arduino sketch for the Waveshare ESP32-S3 Zero that bridges SigmaStudio (Analog Devices' DSP programming GUI) to a physical ADAU1401/1701 DSP over WiFi → TCP → I²C. It also hosts an HTTP UI for writing DSP firmware to a 24C256 EEPROM, and an HTTP OTA page for reflashing the ESP32 itself. The sketch runs on the companion MSD ADAU14-1701 Adapter PCB (Altium files in the parent directory).

Build Environment

• Arduino IDE 1.8.x or 2.x with the ESP32 Arduino core
• Board: ESP32S3 Dev Module (Flash mode: QIO, 4 MB, Default 4MB with spiffs partition)
• Both HTML UIs (index_html.h, ota_html.h) are PROGMEM string literals compiled into flash — no separate LittleFS image upload is required
• Baud rate for Serial monitor: 115200

Architecture

Two servers run in parallel — one TCP, one HTTP:

• tcpServer (port 8086): SigmaTCP protocol. handleTcpBridgeClient() blocks loop() for the duration of a session (single client at a time).
• httpServer (port 80): EEPROM upload (/), OTA firmware update (/ota), and status endpoints. httpServer.handleClient() is called inside the TCP client loop so HTTP stays responsive during a TCP session.

loop() only accepts a new TCP client after the previous one disconnects. There is no concurrency and no idle timeout — the connection stays open until SigmaStudio closes it.

maintainWifi() is called at the top of every loop() iteration and checks WiFi status every 5 seconds, attempting reconnect if the link has dropped.

Build / Version Scheme

The build identifier uses YYMMDD_rev format (e.g. 260304_13). It appears in two places that must always match:

1. The file header comment: // Build: 260304_13 (YYMMDD_rev)
2. The runtime constant: const char* version = "VER: 260304_13";

When cutting a new build, update both. The version constant is displayed on the LCD and printed to Serial at boot.

WiFi Credentials

Hardcoded at the top of ModulosDSP_101.ino:

const char* ssid     = "alfred";
const char* password = "alfred16";

Change before flashing to a different network. No runtime config exists. WiFi.setAutoReconnect(true) is set in setup() and maintainWifi() handles mid-session drops.

WiFi Watchdog — maintainWifi()

Runs every 5 seconds (throttled by millis()). On first detection of a drop: logs to Serial, updates LCD row 3, sets s_wifiLost = true, calls WiFi.reconnect(). On recovery: calls tcpServer.begin() to re-register the listening socket (required after the TCP/IP stack resets), then calls printWifiInfo() to update the LCD with the current IP. Does not run while handleTcpBridgeClient() is blocking — that is fine because an active TCP session implies WiFi is up.

LCD — Optional Hardware

The LCD is detected at boot via the return value of lcd.begin(20, 4) (hd44780 returns 0 on success). The result is stored in static bool s_lcdOk. All subsequent lcd.* calls throughout the sketch are gated on s_lcdOk. If the LCD is absent the sketch boots and runs normally; all status information is available on Serial (115200 baud) instead.

I²C Addresses

Device	8-bit	7-bit (Wire)
ADAU1401 DSP	0x68	0x34
24C256 EEPROM	0xA0	0x50

Both devices share the bus at 400 kHz on SDA=GPIO13, SCL=GPIO12.

SigmaTCP Protocol Details

SigmaStudio sends chipAddr as a chip index (0x01 = DSP, 0x02 = EEPROM), not a raw I²C address. chipAddrTo7bit() maps these — and also handles legacy 8-bit addresses (0x68, 0xA0) and already-shifted 7-bit addresses (0x34, 0x50).

WRITE (opcode 0x09) — 10-byte header:

[0]   0x09       command
[1]   safeload   1 = use safeload registers, 0 = direct write
[2]   placement  reserved
[3-4] totalLen   big-endian: header + payload bytes
[5]   chipAddr   chip index or I2C address
[6-7] dataLen    big-endian: payload bytes
[8-9] address    big-endian: DSP/EEPROM start address
[10+] payload

totalLen is validated against WRITE_HDR_LEN + dataLen immediately after parsing. A mismatch drops the connection — do not remove this check; it prevents dataLen from being blindly trusted to drive buffer waits or I²C writes when a packet is structurally inconsistent.

ACK response: {0x09, 0x00, 0x04, status} (4 bytes). status reflects the actual I²C result — writeRegisterBlock() returns bool and the result is threaded through to the ACK. Do not replace with a hardcoded success.

READ (opcode 0x0A) — 8-byte header:

[0]   0x0A
[1-2] totalLen
[3]   chipAddr
[4-5] dataLen
[6-7] address

Response: {0x0B, totalLen_hi, totalLen_lo, status, dataLen_hi, dataLen_lo, [payload]} (6-byte header + data). On I²C failure, zeros fill the payload rather than dropping the connection — this allows SigmaStudio to probe an unresponsive DSP without aborting.

Safeload — Critical Rules

The DSP has 5 safeload slots. Filling them and writing 0x003C to the Core Register (0x081C) commits all pending parameters atomically (no audio glitch).

• s_safeload_count is static in DSPWriter.cpp — it survives across DSPWriter instances.
• DSPWriter::resetSafeload() must be called at both the start and end of every TCP session. It is called at the top of handleTcpBridgeClient() (session start) and just before client.stop() (session end).
• resetSafeload() now flushes before resetting: if s_safeload_count > 0 it writes {0x00, 0x3C} to the Core Register to trigger IST, clearing the DSP's own internal safeload counter. A session ending with count == 0 (normal case) is a no-op.
• Safeload writes are always 5 bytes: {0x00, byte1, byte2, byte3, byte4}. The leading 0x00 is mandatory padding.
• When safeload == 1 in a WRITE packet, dataLen must be a multiple of 4 (each parameter is 4 bytes). The sketch validates this and drops the connection if violated.

writeRegisterBlock — Error Propagation

DSPWriter::writeRegisterBlock() returns bool. On any Wire.endTransmission() error it logs the failing address and error code to Serial and returns false immediately (stops writing — continuing would advance the address pointer and write misaligned data). The return value is captured at the call site and passed directly to sendWriteAck().

Register Sizes

registerSizeForAddress() derives the I²C bytes-per-register from the address:

Address range	Register size
0x0000–0x03FF (Parameter RAM)	4 bytes
0x0400–0x07FF (Program RAM)	5 bytes
0x081C (Core Register), dataLen == 2	2 bytes (R0 reset)
0x081C (Core Register), dataLen == 24	1 byte (24 x 1-byte hardware config regs)
Everything else (hardware regs)	1 byte

Do not hard-code register sizes elsewhere — always use this function or the constants from DSPWriter.h.

TCP Receive Buffer

dataBuffer is 50 KB, statically allocated. The receive loop always drains client.available() into it before processing — this keeps the TCP receive window open. If you only drain during processing, SigmaStudio hits ZeroWindow and stalls mid-transfer.

Processing is decoupled from reception: the inner loop works from buffer contents (readIndex/writeIndex) without checking client.available(). Large program blocks that span multiple TCP segments are handled correctly this way.

When the buffer is fully consumed, all three index variables reset to 0 to prevent unbounded growth.

EEPROM Write Constraints

• Page size: 64 bytes. Writes crossing a page boundary must be split.
• Max I²C bytes per transaction: 28 (Wire buffer limit minus the 2-byte address overhead).
• After each chunk, i2cAckPoll() polls for ACK up to 120 ms — this is the EEPROM's internal write cycle; do not remove this delay.

OTA Firmware Update

Routes: GET /ota → handleOtaPage(), POST /ota_do → handleOtaDone() + handleOtaStream().

Uses the ESP32 Arduino core's built-in Update library (#include <Update.h>). The upload handler calls Update.begin(UPDATE_SIZE_UNKNOWN) → Update.write() per chunk → Update.end(true). On success handleOtaDone() sends a 200 response then calls ESP.restart() after a 500 ms delay. The LED turns cyan during the flash write.

The firmware binary is produced by Arduino IDE: Sketch → Export Compiled Binary. Upload the .bin file (not .elf or .map).

Fixed-Point Format

ADAU1401 parameter RAM uses 5.23 fixed-point (4 bytes per word). DataConversion::floatToFixed() and ::intToFixed() convert native C types to the 5-byte safeload form {0x00, b3, b2, b1, b0}.

Known Stubs and Intentional Gaps

• DSPWriter::downloadProgram() is commented out. It was intended for standalone firmware loading at boot; this use case is now handled via the EEPROM (DSP reads EEPROM autonomously via SELFBOOT pin).
• WiFi credentials are compile-time constants — no captive portal or NVS storage.
• Only one TCP client is served at a time; a second SigmaStudio instance cannot connect simultaneously.

Files

File	Role
ModulosDSP_101.ino	Top-level: WiFi, TCP/HTTP servers, I²C helpers, CRC32, OTA
DSPWriter.h	I²C address constants, register enums, DSPWriter class declaration
DSPWriter.cpp	writeRegister, writeRegisterBlock (returns bool), safeload with flush
DataConversion.h / .cpp	5.23 fixed-point to C type conversions
index_html.h	Embedded HTML string for the EEPROM upload UI
ota_html.h	Embedded HTML string for the OTA firmware update UI