docs: aggiornati ADR 002 e 003 per SPI e audio routing

docs/adr/ADR-002-SPI-Control-Architecture.md

@@ -23,18 +23,19 @@ audio transport interface.
 
 ## Decision
 
-The SPI architecture is divided into independent domains.
+The SPI architecture is divided into independent functional domains.
 
 The ESP32-S3 operates as the master of the system control SPI bus.
 
-The ADAU1467 and Si4684 expose SPI slave interfaces for external configuration.
+The ADAU1467 and Si4684 expose SPI slave interfaces for external
+configuration and control.
 
-Each device maintains its own internal SPI master domain for accessing local
+The internal management of each device remains under the responsibility of
-memories or peripherals.
+the device itself.
 
 ## Architecture
 
-System control bus:
+System control SPI domain:
 
             ESP32-S3
 
@@ -47,8 +48,10 @@ System control bus:
 
 SPI SLAVE          SPI SLAVE
 
+## ADAU1467 Configuration Domain
 
-ADAU1467 local memory:
+The ADAU1467 manages its own external configuration memory through its
+internal SPI master interface.
 
           ADAU1467
 
@@ -57,37 +60,57 @@ ADAU1467 local memory:
               |
 
           25AA1024
-      DSP Configuration Memory
 
+   DSP Program / Configuration Memory
 
-Si4684 local memory:
+The ESP32-S3 controls the ADAU1467 through the external SPI interface but
+does not directly access the DSP configuration memory during normal
+operation.
 
-           Si4684
+## Si4684 Firmware Domain
+
+The Si4684 firmware loading and configuration process is managed through
+commands exchanged on the external SPI control interface.
+
+           ESP32-S3
 
         SPI MASTER
 
               |
 
-      Firmware Memory
+           Si4684
 
+              |
+
+    Internal Firmware Loader
+
+              |
+
+         Internal RAM
+
+The ESP32-S3 controls the initialization process but does not directly access
+the internal operational memory of the Si4684.
 
 ## Consequences
 
 ### Positive
 
-- Clear ownership of every SPI bus
+- Clear ownership of every SPI interface
+- No bus contention between devices
 - Reduced electrical loading
-- Independent firmware management
+- Independent device initialization
-- Easier debugging
+- Easier debugging and validation
 
 ### Negative
 
-- Multiple SPI peripherals are required
+- Multiple control interfaces are required
-- Firmware coordination is required between domains
+- Firmware update procedures must coordinate different device domains
 
 ## Rationale
 
-The ESP32-S3 supervises the system but does not replace the internal
+The ESP32-S3 supervises the complete HubAudio system but does not replace the
-controllers of specialized devices.
+internal controllers of specialized devices.
 
-Each component remains responsible for its own functional domain.
+Each component remains responsible for its own functional domain.
+
+The control plane and the audio plane remain architecturally separated.

docs/adr/ADR-003-I2S-Audio-Routing-Architecture.md

@@ -0,0 +1,108 @@
+# ADR-003: I2S Audio Routing Architecture
+
+- Status: Accepted
+- Date: 2026-08-01
+- Decision Type: Audio Architecture
+
+## Context
+
+HubAudio integrates multiple digital audio sources and destinations:
+
+Sources:
+
+- ESP32-S3 streaming subsystem
+- Si4684 radio receiver
+- Bluetooth receiver
+- Optical digital input
+
+Destinations:
+
+- Analog audio output through CODEC/DAC
+- Bluetooth transmission
+- Optical digital output
+
+A deterministic and scalable digital audio routing architecture is required.
+
+## Decision
+
+The ADAU1467 is the central routing element of the Audio Domain.
+
+Each major audio device is assigned to a dedicated serial audio interface.
+
+The preferred architecture is:
+
+
+One audio device = One dedicated I2S interface
+
+
+The ADAU1467 operates as the audio timing reference.
+
+External audio devices operate as I2S slaves whenever supported.
+
+## Audio Input Allocation
+
+| ADAU1467 Port | Device | Function |
+|---|---|---|
+| SDATA_IN0 | ESP32-S3 | Network audio stream |
+| SDATA_IN1 | Si4684 | Radio audio |
+| SDATA_IN2 | DECODEC | Optical digital input |
+| SDATA_IN3 | Bluetooth RX | Wireless audio input |
+
+
+ESP32-S3 --------
+Si4684 ---------
+DECODEC ----------+---- ADAU1467
+BT RX ---------/
+
+
+## Audio Output Allocation
+
+| ADAU1467 Port | Device | Function |
+|---|---|---|
+| SDATA_OUT0 | CODEC/DAC | Analog audio output |
+| SDATA_OUT1 | Bluetooth TX | Wireless audio output |
+| SDATA_OUT2 | ENCODEC | Optical digital output |
+| SDATA_OUT3 | Reserved | Future expansion |
+
+             ADAU1467
+
+                 |
+    +------------+------------+
+    |            |            |
+  CODEC        BTTX       ENCODEC
+
+## Clocking
+
+The ADAU1467 provides the master audio timing reference.
+
+The audio clock domain consists of:
+
+- MCLK
+- BCLK
+- LRCLK
+
+All connected audio peripherals must operate synchronized to this clock
+domain.
+
+## Consequences
+
+### Positive
+
+- Deterministic audio timing
+- Simple routing model
+- Independent audio channels
+- Easier debugging
+- Future expansion capability
+
+### Negative
+
+- Higher pin usage
+- More PCB routing resources required
+- Peripheral selection must consider I2S slave capability
+
+## Rationale
+
+HubAudio prioritizes signal integrity, maintainability and deterministic
+audio behavior over maximum bus utilization.
+
+The ADAU1467 acts as the central audio router of the system.