aggiornamento documenti strutturali

docs/architecture/HubAudio-Clock-Architecture.md

@@ -0,0 +1,273 @@
+# HubAudio Clock Architecture
+
+- Status: Draft
+- Date: 2026-08-01
+- Document Type: Architecture Specification
+
+
+# 1. Overview
+
+The HubAudio architecture defines a centralized audio timing domain.
+
+The ADAU1467 is the master of the audio clock system.
+
+The purpose of this architecture is to provide a single timing reference for
+all digital audio devices, avoiding independent clock domains and minimizing
+sample synchronization problems.
+
+The audio clock domain is composed of:
+
+- Master oscillator
+- ADAU1467 PLL and clock generation
+- Clock distribution stage
+- Audio peripheral clock inputs
+
+
+---
+
+# 2. Audio Clock Master
+
+The ADAU1467 is responsible for generating the audio timing reference.
+
+The ADAU1467 provides:
+
+- DSP processing clock
+- Serial audio clock generation
+- I2S synchronization
+
+
+Conceptually:
+
+          Reference Clock
+
+                |
+                |
+
+           ADAU1467
+
+      DSP + Audio Clock Master
+
+                |
+
+         MCLK / BCLK / LRCLK
+
+The ADAU1467 is the timing authority of the Audio Domain.
+
+
+---
+
+# 3. Reference Frequency
+
+The preferred audio clock family is based on 48 kHz.
+
+The standard relationship is:
+
+
+48 kHz × 256 = 12.288 MHz
+
+
+The reference oscillator is therefore selected around:
+
+
+12.288 MHz
+
+
+This frequency is suitable for:
+
+- streaming audio
+- DAB/DAB+
+- Bluetooth audio
+- consumer digital audio systems
+
+
+Future support for 44.1 kHz family may require:
+
+- alternate oscillator
+- PLL reconfiguration
+- ASRC usage
+
+
+---
+
+# 4. Clock Distribution
+
+The ADAU1467 clock output is distributed through a dedicated clock buffer.
+
+The PCS2P2309NZ is used as clock distribution element.
+
+Its role is:
+
+- fan-out of the clock signal
+- reduction of clock loading
+- improved signal integrity
+
+
+It does not generate the audio clock.
+
+
+Architecture:
+
+                ADAU1467
+
+             Audio Clock Master
+
+                   |
+
+                  MCLK
+
+                   |
+
+            PCS2P2309NZ
+
+          Clock Distribution
+
+      +------------+------------+
+      |            |            |
+      |            |            |
+
+   Si4684       BT Modules    CODEC
+
+---
+
+# 5. Clock Domain Devices
+
+All digital audio peripherals belong to the same clock domain.
+
+Expected clock relationships:
+
+             ADAU1467
+
+                |
+
+    +-----------+-----------+
+    |
+ MCLK/BCLK/LRCLK
+
+    |
+
++------+------+------+------+
+| | | |
+ESP32 Si4684 BT RX CODEC
+
+
+
+Each device must support operation as:
+
+- I2S slave
+- external MCLK
+- externally provided BCLK/LRCLK
+
+
+---
+
+# 6. Clock and Audio Data Relationship
+
+The audio data flow is independent from control communication.
+
+Control:
+
+
+ESP32-S3
+
+|
+|
+
+SPI
+
+|
+
+ADAU1467 / Si4684
+
+
+
+Audio:
+
+
+Source Device
+
+  |
+  |
+ I2S
+
+  |
+  |
+
+ADAU1467
+
+
+Timing:
+
+
+ADAU1467
+
+  |
+  |
+
+Clock Signals
+
+  |
+  |
+
+Audio Peripherals
+
+
+
+---
+
+# 7. Design Rules
+
+The following rules apply to the PCB:
+
+## Clock Routing
+
+- Clock lines must be short
+- Clock return path must be continuous
+- Avoid routing near RF sections
+- Avoid unnecessary vias
+
+
+## Power Integrity
+
+The clock generator and buffer require:
+
+- clean supply rails
+- adequate decoupling
+- low noise power domains
+
+
+## Grounding
+
+Clock signals must always reference a continuous ground plane.
+
+
+---
+
+# 8. Architectural Consequences
+
+## Advantages
+
+- Single audio timing reference
+- No asynchronous sample drift
+- Simplified DSP routing
+- Professional audio architecture
+
+
+## Limitations
+
+- All peripherals must support external clocking
+- Clock tree becomes a critical design element
+- PCB layout quality directly affects audio performance
+
+
+---
+
+# 9. Design Philosophy
+
+The HubAudio clock architecture follows the same principle as a musical
+orchestra:
+
+The ADAU1467 is the conductor.
+
+The PCS2P2309NZ distributes the beat.
+
+All audio devices perform synchronized to the same timing reference.

docs/architecture/HubAudio-I2S-Architecture.md

@@ -0,0 +1,329 @@
+# HubAudio I2S Audio Architecture
+
+- Status: Draft
+- Date: 2026-08-01
+- Document Type: Architecture Specification
+
+
+# 1. Overview
+
+The HubAudio audio architecture is based on a centralized digital audio
+processing model.
+
+The ADAU1467 is the core audio processor and manages:
+
+- digital audio routing
+- DSP processing
+- mixing
+- synchronization
+- audio stream conversion
+
+All digital audio streams are connected to the ADAU1467 through serial audio
+interfaces.
+
+The audio domain is independent from the system control domain.
+
+
+CONTROL DOMAIN
+
+ESP32-S3
+|
+|
+SPI
+|
+Configuration
+
+AUDIO DOMAIN
+
+ESP32-S3
+Si4684
+BT RX
+Optical Input
+
+  |
+  |
+  v
+
+ADAU1467
+
+  |
+  |
+
+CODEC
+BT TX
+Optical Output
+
+
+---
+
+# 2. Audio Clock Master
+
+The ADAU1467 is the master of the audio timing domain.
+
+The generated audio clock consists of:
+
+- MCLK
+- BCLK
+- LRCLK
+
+
+All external audio devices should operate as synchronized slaves whenever
+supported.
+
+             ADAU1467
+
+          AUDIO CLOCK MASTER
+
+                |
+      +---------+---------+
+      |
+    MCLK/BCLK/LRCLK
+
+                |
+   +------------+------------+
+   |            |            |
+ Si4684       BT RX       CODEC
+
+---
+
+# 3. Input Audio Interfaces
+
+The ADAU1467 provides multiple serial input ports.
+
+The HubAudio input allocation is:
+
+| ADAU Port | Source | Description |
+|-----------|--------|-------------|
+| SDATA_IN0 | ESP32-S3 | Network audio stream |
+| SDATA_IN1 | Si4684 | Radio receiver audio |
+| SDATA_IN2 | DECODEC | Optical digital input |
+| SDATA_IN3 | Bluetooth RX | Wireless audio input |
+
+
+## ESP32-S3 Audio Input
+
+The ESP32-S3 acts as a digital audio source.
+
+Its role inside the Audio Domain is equivalent to any other audio source.
+
+
+ESP32-S3
+
+I2S DATA OUT
+|
+|
+v
+
+ADAU1467 SDATA_IN0
+
+
+The ESP32-S3 does not control the audio timing.
+
+The timing is provided by the ADAU1467 clock domain.
+
+
+---
+
+## Si4684 Audio Input
+
+The Si4684 provides decoded radio audio.
+
+
+Si4684
+
+I2S DATA OUT
+|
+|
+v
+
+ADAU1467 SDATA_IN1
+
+
+The Si4684 is a peripheral of the audio domain.
+
+It does not define the system audio clock.
+
+
+---
+
+## Optical Digital Input
+
+The optical input path is:
+
+
+SPDIF Optical
+
+  |
+  |
+
+DECODEC
+
+  |
+  |
+
+I2S
+
+  |
+  |
+
+ADAU1467 SDATA_IN2
+
+
+The decoder must support operation synchronized with the HubAudio clock
+architecture or provide an appropriate conversion stage.
+
+
+---
+
+## Bluetooth RX Input
+
+The Bluetooth receiver provides digital audio:
+
+
+Bluetooth RX
+
+  |
+  |
+
+I2S
+
+  |
+  |
+
+ADAU1467 SDATA_IN3
+
+
+The selected Bluetooth module must support external audio clock operation.
+
+
+---
+
+# 4. Output Audio Interfaces
+
+The ADAU1467 output allocation is:
+
+| ADAU Port | Destination | Description |
+|-----------|-------------|-------------|
+| SDATA_OUT0 | CODEC/DAC | Analog audio output |
+| SDATA_OUT1 | Bluetooth TX | Wireless transmission |
+| SDATA_OUT2 | ENCODEC | Optical digital output |
+| SDATA_OUT3 | Reserved | Future expansion |
+
+
+## Analog Audio Output
+
+
+ADAU1467
+
+SDATA_OUT0
+
+  |
+
+CODEC / DAC
+
+  |
+
+Analog Output
+
+
+
+---
+
+## Bluetooth Transmission Output
+
+
+ADAU1467
+
+SDATA_OUT1
+
+  |
+
+Bluetooth TX
+
+  |
+
+Wireless Audio
+
+
+
+---
+
+## Optical Digital Output
+
+
+ADAU1467
+
+SDATA_OUT2
+
+  |
+
+ENCODEC
+
+  |
+
+SPDIF Optical Output
+
+
+
+---
+
+# 5. I2S Versus TDM Strategy
+
+The ADAU1467 supports multiple serial audio formats including:
+
+- I2S
+- Left Justified
+- Right Justified
+- TDM
+
+
+The initial HubAudio architecture uses dedicated I2S interfaces.
+
+Advantages:
+
+- simple routing
+- easier debugging
+- independent peripherals
+- reduced firmware complexity
+
+
+TDM remains an option for future expansion where multiple channels must share
+a single physical interface.
+
+The current design prioritizes clarity and robustness.
+
+
+---
+
+# 6. Signal Integrity Requirements
+
+The following signals are considered critical:
+
+- MCLK
+- BCLK
+- LRCLK
+- SDATA
+
+
+PCB design considerations:
+
+- controlled return paths
+- continuous ground reference
+- short clock routes
+- separation from RF sections
+- controlled impedance where required
+
+
+---
+
+# 7. Future Expansion
+
+The architecture reserves:
+
+- additional serial output capability
+- additional digital inputs
+- TDM expansion possibilities
+
+
+The ADAU1467 remains the central audio routing element for future HubAudio
+versions.

docs/architecture/HubAudio-SPI-Architecture.md

@@ -0,0 +1,294 @@
+# HubAudio SPI Control Architecture
+
+- Status: Draft
+- Date: 2026-08-01
+- Document Type: Architecture Specification
+
+
+# 1. Overview
+
+The HubAudio system separates the control communication layer from the audio
+signal layer.
+
+SPI is used exclusively for:
+
+- device configuration
+- initialization
+- status monitoring
+- firmware loading procedures
+- parameter management
+
+SPI is not used for real-time audio transport.
+
+
+The control architecture is based on independent SPI domains.
+
+
+CONTROL PLANE
+
+             ESP32-S3
+
+          System Controller
+
+                |
+                |
+          SPI Control Bus
+
+    +-----------+-----------+
+    |                       |
+
+ADAU1467                Si4684
+
+Audio Processor Radio Receiver
+
+
+
+---
+
+# 2. ESP32-S3 Control Domain
+
+The ESP32-S3 is the system supervisor.
+
+Its responsibilities are:
+
+- system startup
+- peripheral initialization
+- configuration management
+- communication with external devices
+- firmware update coordination
+
+
+The ESP32-S3 owns the main control SPI interface.
+
+            ESP32-S3
+
+         SPI MASTER
+
+              |
+    +---------+---------+
+    |                   |
+
+ ADAU1467            Si4684
+
+SPI SLAVE          SPI SLAVE
+
+
+The control bus is independent from all audio data paths.
+
+
+---
+
+# 3. ADAU1467 SPI Domain
+
+The ADAU1467 contains its own SPI interface for external control.
+
+The ESP32-S3 uses this interface for:
+
+- DSP configuration
+- parameter updates
+- operational control
+- status reading
+
+
+The ADAU1467 also manages its external program memory.
+
+             ADAU1467
+
+    +----------------------+
+    |
+    | SPI MASTER
+    |
+    v
+
+          25AA1024
+
+   DSP Program Memory
+
+
+The ESP32-S3 does not directly access the EEPROM during normal operation.
+
+The ADAU1467 is responsible for loading its DSP configuration.
+
+
+---
+
+# 4. Si4684 SPI Domain
+
+The Si4684 is controlled by the ESP32-S3 through its SPI slave interface.
+
+The ESP32-S3 manages:
+
+- initialization sequence
+- command exchange
+- configuration
+- firmware loading procedure
+
+
+             ESP32-S3
+
+          SPI MASTER
+
+               |
+
+             Si4684
+
+               |
+
+    Internal Firmware Management
+
+               |
+
+          Internal RAM
+
+
+The Si4684 remains responsible for its internal operational memory.
+
+
+---
+
+# 5. SPI Bus Isolation Principle
+
+The HubAudio architecture intentionally avoids a single shared SPI bus.
+
+The design uses:
+
+          ESP32-S3
+
+      +-------------+
+
+      |             |
+
+   SPI-A          SPI-B
+
+      |             |
+
+  ADAU1467       Si4684
+
+
+Advantages:
+
+- no chip-select conflicts
+- independent timing
+- reduced electrical loading
+- easier firmware management
+- simpler debugging
+
+
+---
+
+# 6. Boot Sequence
+
+The expected startup sequence is:
+
+
+
+Power ON
+
+|
+
+ESP32-S3 boot
+
+|
+
+Initialize SPI buses
+
+|
+
+Configure ADAU1467
+
+|
++--> ADAU loads DSP program from 25AA1024
+
+|
+
+Configure Si4684
+
+|
++--> Firmware initialization
+
+|
+
+Enable Audio Domain
+
+|
+
+ADAU1467 starts audio processing
+
+
+
+---
+
+# 7. Separation Between Domains
+
+
+## Control Domain
+
+
+ESP32-S3
+
+|
+|
+
+SPI
+
+|
+
+Peripheral configuration
+
+
+
+## Audio Domain
+
+
+Audio Sources
+
+|
+|
+
+I2S
+
+|
+
+ADAU1467
+
+|
+
+Audio Outputs
+
+
+
+The two domains interact only through configuration and status information.
+
+
+---
+
+# 8. Design Rules
+
+SPI signals require:
+
+- controlled routing
+- clean reference plane
+- appropriate termination where required
+- separation from high-speed clock signals
+
+
+Critical signals:
+
+- SCLK
+- MOSI
+- MISO
+- CS
+
+
+---
+
+# 9. Design Philosophy
+
+The ESP32-S3 is the system coordinator.
+
+The ADAU1467 is the audio processor.
+
+The Si4684 is a specialized audio peripheral.
+
+Each component controls its own functional domain while remaining part of the
+complete HubAudio system.

docs/architecture/HubAudio-System-Architecture.md

@@ -0,0 +1,469 @@
+# HubAudio System Architecture
+
+- Status: Draft
+- Date: 2026-08-01
+- Document Type: System Architecture
+
+
+# 1. Overview
+
+HubAudio is a modular digital audio platform designed around a centralized
+audio processing architecture.
+
+The system separates three main functional domains:
+
+- Control Domain
+- Audio Domain
+- Time Domain
+
+Each domain has a clearly defined responsibility.
+
+The architecture is based on the principle:
+
+
+ESP32-S3 manages the system.
+
+ADAU1467 manages the audio.
+
+The clock domain synchronizes the orchestra.
+
+
+
+---
+
+# 2. High Level Architecture
+
+
+                     HUBAUDIO
+
+
+                CONTROL DOMAIN
+
+                     ESP32-S3
+
+              WiFi / Network / UI
+
+                         |
+
+                         |
+
+                       SPI
+
+                         |
+
+         +---------------+---------------+
+
+         |                               |
+
+      ADAU1467                        Si4684
+
+  Audio Processor                Radio Receiver
+
+
+         |
+         |
+         |
+    AUDIO DOMAIN
+
+
+         |
+ +-------+-------+-------+-------+
+ |       |       |       |       |
+
+ESP32 Si4684 BT RX Optical Other
+
+         |
+
+      ADAU1467
+
+    DSP / Routing / Mixing
+
+
+         |
+
+ +-------+-------+-------+
+
+ |       |       |
+
+CODEC BT TX Optical Out
+
+         |
+
+    TIME DOMAIN
+
+         |
+
+    Audio Clock Tree
+
+         |
+
+    MCLK / BCLK / LRCLK
+
+
+---
+
+# 3. Functional Domains
+
+
+# 3.1 Control Domain
+
+The Control Domain is responsible for system management.
+
+Main component:
+
+
+ESP32-S3
+
+
+Responsibilities:
+
+- network connectivity
+- streaming services
+- user interface
+- configuration management
+- firmware update coordination
+- device supervision
+
+
+Communication:
+
+
+ESP32-S3
+
+  |
+
+ SPI
+
+  |
+
+Audio peripherals
+
+
+
+The Control Domain does not transport real-time audio.
+
+
+---
+
+# 3.2 Audio Domain
+
+The Audio Domain is centered around the ADAU1467.
+
+The ADAU1467 is responsible for:
+
+- DSP processing
+- audio routing
+- mixing
+- digital effects
+- format conversion
+- audio synchronization
+
+
+Audio sources:
+
+
+ESP32-S3
+Si4684
+Bluetooth RX
+Optical Input
+
+
+
+Audio destinations:
+
+
+CODEC/DAC
+Bluetooth TX
+Optical Output
+
+
+
+The audio transport uses:
+
+
+I2S
+
+
+
+---
+
+# 3.3 Time Domain
+
+The Time Domain provides the synchronization reference.
+
+The ADAU1467 is the audio clock master.
+
+The clock distribution provides:
+
+- MCLK
+- BCLK
+- LRCLK
+
+
+Clock distribution:
+
+             ADAU1467
+
+         Audio Clock Master
+
+                |
+
+                |
+
+          Clock Buffer
+
+                |
+
+    +-----------+-----------+
+
+    |           |           |
+
+  CODEC      Si4684      BT
+
+
+---
+
+# 4. Component Roles
+
+
+## ESP32-S3
+
+Role:
+
+System Controller + Audio Source
+
+
+Functions:
+
+- network audio streaming
+- system management
+- configuration
+
+
+Inside Audio Domain:
+
+
+I2S Source
+
+
+
+---
+
+## ADAU1467
+
+Role:
+
+Audio Domain Master
+
+
+Functions:
+
+- DSP
+- routing
+- mixing
+- clock generation
+
+
+Interfaces:
+
+
+SPI -> Configuration
+I2S -> Audio
+Clock -> Synchronization
+
+
+
+---
+
+## Si4684
+
+Role:
+
+Digital Radio Audio Source
+
+
+Functions:
+
+- FM reception
+- DAB/DAB+
+- digital audio output
+
+
+Interfaces:
+
+
+SPI -> Control
+
+I2S -> Audio
+
+
+
+---
+
+## Bluetooth Modules
+
+Role:
+
+Wireless Audio Interfaces
+
+
+Bluetooth RX:
+
+
+BT Audio
+
+|
+
+I2S
+
+|
+
+ADAU1467
+
+
+
+Bluetooth TX:
+
+
+ADAU1467
+
+|
+
+I2S
+
+|
+
+BT Transmitter
+
+
+
+---
+
+## Digital Converters
+
+Optical interfaces are handled through dedicated conversion stages.
+
+
+Input:
+
+
+SPDIF
+
+|
+
+DECODEC
+
+|
+
+I2S
+
+|
+
+ADAU1467
+
+
+
+Output:
+
+
+ADAU1467
+
+|
+
+I2S
+
+|
+
+ENCODEC
+
+|
+
+SPDIF
+
+
+
+---
+
+# 5. Design Philosophy
+
+
+HubAudio follows a distributed intelligence model.
+
+The ESP32-S3 provides connectivity and supervision.
+
+The ADAU1467 provides audio intelligence.
+
+Dedicated peripherals provide specialized functions.
+
+
+The architecture avoids making the microcontroller responsible for
+time-critical audio processing.
+
+
+---
+
+# 6. Expansion Strategy
+
+
+The architecture allows future integration of:
+
+- additional audio sources
+- additional DSP processing
+- microphones
+- sensors
+- alternative wireless interfaces
+
+
+Expansion follows the same principle:
+
+Control:
+
+
+SPI
+
+
+
+Audio:
+
+
+I2S
+
+
+
+Synchronization:
+
+
+Clock Domain
+
+
+
+---
+
+# 7. Summary
+
+
+HubAudio is structured around three independent but coordinated planes:
+
+
+
+CONTROL PLANE
+
+ESP32-S3
+|
+SPI
+
+AUDIO PLANE
+
+ADAU1467
+|
+I2S
+
+TIME PLANE
+
+ADAU1467
+|
+Clock Distribution
+
+
+
+This separation defines the fundamental architecture of HubAudio.