Readme Update

.gitignore

@@ -0,0 +1,5 @@
+.claude/
+research/
+
+CLAUDE.md
+desktop.ini

README.md

@@ -0,0 +1,184 @@
+# ModulosDSP — ESP32-S3 WiFi Bridge for ADAU14xx DSP
+
+An Arduino sketch for the **Waveshare ESP32-S3 Zero** that provides a WiFi interface to Analog Devices ADAU1401/1701 DSP chips:
+
+- **SigmaTCP bridge** (port 8086) — lets SigmaStudio connect wirelessly to a physical DSP over I²C
+- **HTTP EEPROM uploader** (port 80) — flash DSP firmware binaries to a 24C256 EEPROM from a browser
+
+This sketch runs on the companion **MSD ADAU14-1701 Adapter** PCB.
+
+---
+
+## Hardware
+
+| Component | Part | Notes |
+|-----------|------|-------|
+| Microcontroller | Waveshare ESP32-S3 Zero | Onboard WS2812 NeoPixel on GPIO 21 |
+| DSP | ADAU1401 / ADAU1701 | I²C address 0x68 (7-bit: 0x34) |
+| EEPROM | 24C256 (32 KB) | I²C address 0xA0 (7-bit: 0x50) |
+| Display | 20×4 hd44780 I²C LCD | Boot status and IP address |
+
+### Pin Assignments
+
+| Signal | GPIO |
+|--------|------|
+| I²C SDA | 13 |
+| I²C SCL | 12 |
+| Status LED (NeoPixel) | 21 (built-in) |
+
+The DSP, EEPROM, and LCD all share the same I²C bus at 400 kHz.
+
+---
+
+## Arduino Libraries Required
+
+Install via **Sketch → Include Library → Manage Libraries**:
+
+| Library | Purpose |
+|---------|---------|
+| `WiFi` | ESP32 WiFi (built-in with ESP32 core) |
+| `WebServer` | HTTP server (built-in) |
+| `Wire` | I²C master (built-in) |
+| `LittleFS` | Embedded filesystem for web assets (built-in) |
+| `Adafruit NeoPixel` | WS2812 status LED |
+| `hd44780` | I²C LCD driver |
+
+**Board:** select **ESP32S3 Dev Module** (or Waveshare ESP32-S3 Zero if your board package includes it) via the ESP32 Arduino core.
+
+---
+
+## Configuration
+
+Before flashing, edit `ModulosDSP_101.ino` and update the WiFi credentials:
+
+```cpp
+const char* ssid     = "your_network_ssid";
+const char* password = "your_network_password";
+```
+
+There is no runtime configuration — credentials are compiled in.
+
+---
+
+## Status LED
+
+The onboard NeoPixel (GPIO 21) shows current activity at a glance:
+
+| Color | Meaning |
+|-------|---------|
+| Off | Idle — no TCP client connected |
+| Green | DSP write in progress (SigmaTCP) |
+| Blue | DSP read in progress (SigmaTCP) |
+| Yellow | EEPROM write via SigmaTCP |
+| Magenta | EEPROM upload via HTTP |
+| Red flash | Error (I²C failure, buffer overflow, bad packet) |
+
+---
+
+## Using with SigmaStudio
+
+1. Power on the board. The LCD displays the assigned IP address; Serial (115200 baud) also prints it.
+2. In SigmaStudio, open **Settings → Hardware Configuration**.
+3. Add a **USBi** interface and switch the connection type to **SigmaTCP**.
+4. Enter the ESP32's IP address and port **8086**.
+5. Click **Link → Compile Download** — SigmaStudio pushes firmware to the DSP wirelessly.
+
+The bridge handles both **direct writes** and **safeload writes** (glitch-free atomic parameter updates on a live DSP).
+
+---
+
+## EEPROM Uploader (Web UI)
+
+Navigate to `http://<ESP32-IP>/` in any browser:
+
+1. Click **Choose File** and select a SigmaStudio-exported binary.
+2. Optionally tick **Verify (CRC32)** to read back and confirm the write.
+3. Click **Upload** — the Magenta LED pulses during the write.
+
+The 24C256 holds **32 KB**. The DSP reads this EEPROM at power-up via its SELFBOOT pin, allowing standalone operation without the ESP32 actively present.
+
+---
+
+## How It Works
+
+### SigmaTCP Bridge
+
+SigmaTCP is the protocol used by Analog Devices' SigmaStudio to talk to hardware like the USBi programmer. This sketch implements the server side over TCP/WiFi and forwards all register traffic to the DSP or EEPROM via I²C.
+
+**WRITE (opcode 0x09):**
+- 10-byte header: command, safeload flag, placement, totalLen, chipAddr, dataLen, startAddress
+- Payload forwarded to DSP or EEPROM via I²C
+- 4-byte ACK sent back: `{0x09, 0x00, 0x04, status}`
+
+**READ (opcode 0x0A):**
+- 8-byte header: command, totalLen, chipAddr, dataLen, startAddress
+- I²C data read in 32-byte chunks
+- 6-byte response header (`0x0B, totalLen_hi, totalLen_lo, status, dataLen_hi, dataLen_lo`) + payload sent back
+- On I²C failure, zeros are sent rather than dropping the connection (allows SigmaStudio to probe an unresponsive DSP)
+
+**Safeload:**  
+When the safeload flag is set, parameters are queued into the DSP's 5 hardware safeload slots and committed atomically by writing `0x003C` to the Core Register. This avoids audio clicks when updating parameters on a running DSP.
+
+The TCP receive loop drains all available bytes into a 50 KB buffer every iteration (keeping the TCP receive window open), then processes complete packets from the buffer. This correctly handles large program downloads that span multiple TCP segments.
+
+### EEPROM Writes
+
+Writes are chunked to ≤28 bytes, aligned to 64-byte page boundaries. After each chunk, the firmware polls the EEPROM for ACK (up to 120 ms) to wait for its internal write cycle before continuing.
+
+### Fixed-Point Format
+
+The ADAU1401 uses **5.23 fixed-point** for parameter RAM (4 bytes per word). Safeload registers add a leading `0x00` padding byte, making them 5 bytes. The `DataConversion` class handles conversion from `float`, `int32_t`, and other C types.
+
+---
+
+## File Structure
+
+```
+ModulosDSP_101/
+├── ModulosDSP_101.ino   Main sketch: WiFi, TCP/HTTP servers, I²C bridge
+├── DSPWriter.h          DSP register write interface and address map
+├── DSPWriter.cpp        I²C write and safeload implementations
+├── DataConversion.h     5.23 fixed-point conversion declarations
+├── DataConversion.cpp   Fixed-point conversion implementations
+└── index_html.h         Embedded HTML for the EEPROM upload web UI
+```
+
+---
+
+## ADAU1401 Address Map
+
+| Region | Address Range | I²C bytes per register |
+|--------|--------------|------------------------|
+| Parameter RAM | 0x0000–0x03FF | 4 |
+| Program RAM | 0x0400–0x07FF | 5 |
+| Interface Registers 0–7 | 0x0800–0x0807 | 1 |
+| GPIO Register | 0x0808 | 1 |
+| ADC 0–3 (read-only) | 0x0809–0x080C | 1 |
+| Safeload Data 0–4 | 0x0810–0x0814 | 5 |
+| Safeload Address 0–4 | 0x0815–0x0819 | 2 |
+| Core Register | 0x081C | 2 (R0 reset) |
+| MpCfg 0–1 | 0x0820–0x0821 | 1 |
+| Analog Power Down | 0x0822 | 1 |
+| Analog Interface 0 | 0x0824 | 1 |
+
+---
+
+## Version History
+
+| Version | Notes |
+|---------|-------|
+| 1.3.1 | Current stable. `chipAddr 0x01` fix on clean v1.3.0 base |
+| 1.3.0 | Fixed 6-byte SigmaTCP read response header; added write ACK; I²C read failure returns zeros |
+| 1.2.0 | Added WS2812 NeoPixel status LED |
+| 1.1.0 | Buffer overflow checks, explicit `chipAddr` lookup, safeload dataLen validation |
+| 1.4.0 | (Changelog entry) Block-read TCP receive with per-packet timeout for large program downloads |
+
+---
+
+## References
+
+- [SigmaStudio TCP interface for ESP32 — Analog Devices forum](https://ez.analog.com/dsp/sigmadsp/f/q-a/164008/sharing-tcpi-interface-for-sigma-studio-using-esp8266-or-esp32)
+- [roTDSP — ADAU1401 carrier board](https://github.com/roTbear/roTDSP)
+- [SigmaDSP Arduino library (MCUdude)](https://github.com/MCUdude/SigmaDSP)
+- [Elektor AudioDSP — ESP32 + ADAU1701](https://github.com/ClemensAtElektor/Elektor_AudioDSP)
+- [How to program an Analog Devices DSP](https://daumemo.com/how-to-program-an-analog-devices-dsp/)