aggiornamento di alcuni file e revisione directory repository 202608012135

2026-08-01 21:36:11 +02:00
parent 07b11740bf
commit 1597b4cf2a
34 changed files with 1281 additions and 0 deletions
@@ -0,0 +1,97 @@
+# ADR-000 — HubAudio Engineering Philosophy
+
+**Status:** Accepted
+
+**Date:** 2026-08-01
+
+---
+
+## Purpose
+
+HubAudio is designed as a professional embedded platform.
+
+The primary objective is **maintainability**, followed by extensibility, robustness and performance.
+
+The architecture shall minimise cognitive load for future developers.
+
+---
+
+# Core Principles
+
+## 1. Code that fits in your head
+
+Every class, function and module shall be understandable in isolation.
+
+If understanding a module requires reading large portions of the codebase, the design should be reconsidered.
+
+Complexity must never be hidden.
+
+---
+
+## 2. One Responsibility
+
+Every module has exactly one responsibility.
+
+Examples:
+
+- PowerManager
+- DSPManager
+- RadioManager
+- BluetoothManager
+- AudioRouter
+
+Responsibilities shall never overlap.
+
+---
+
+## 3. Hardware is software controlled
+
+Every subsystem should, whenever technically possible, support:
+
+- independent power control
+- independent reset
+- diagnostics
+- firmware update
+
+---
+
+## 4. Digital-first architecture
+
+Audio remains digital until external conversion is explicitly required.
+
+The DSP is the centre of the audio routing architecture.
+
+---
+
+## 5. Documentation is part of the product
+
+Documentation is considered part of the deliverable.
+
+Every architectural decision shall be documented.
+
+---
+
+## 6. Simplicity over cleverness
+
+The simplest correct solution is preferred.
+
+Elegant architecture is preferred over clever implementation.
+
+---
+
+## 7. Small incremental changes
+
+The project evolves through small, reviewable improvements.
+
+Large architectural changes shall be avoided unless justified.
+
+---
+
+# Definition of Done
+
+A feature is considered complete only when:
+
+- implemented
+- documented
+- testable
+- understandable
@@ -0,0 +1,77 @@
+# ADR-001: ADAU1467 as Audio Domain Master
+
+- Status: Accepted
+- Date: 2026-08-01
+- Decision Type: Architecture
+
+## Context
+
+HubAudio is designed as a modular digital audio platform integrating several
+audio sources and destinations:
+
+- ESP32-S3 streaming subsystem
+- Si4684 radio receiver
+- Bluetooth RX/TX modules
+- Digital audio converters
+- Analog CODEC/DAC stages
+
+The system requires a central component responsible for:
+
+- digital audio routing
+- DSP processing
+- timing synchronization
+- audio stream management
+
+The ADAU1467 has been selected as the central audio processor.
+
+## Decision
+
+The ADAU1467 is the master component of the HubAudio Audio Domain.
+
+The ADAU1467 is responsible for:
+
+- DSP processing
+- audio routing
+- digital mixing
+- signal processing
+- audio clock generation
+- synchronization of external audio peripherals
+
+The ADAU1467 is considered the audio domain master.
+
+The ESP32-S3 participates in the Audio Domain as a digital audio source. It does not act as the audio timing master or routing controller. Its role inside the audio domain is equivalent to other digital audio sources.
+The ESP32-S3 has a dual role:
+
+- audio source inside the Audio Domain
+system supervisor inside the Control Domain
+
+It operates as system supervisor and is responsible for:
+
+- network connectivity
+- user interface
+- configuration management
+- firmware update management
+- system control
+
+## Consequences
+
+### Positive
+
+- Single audio timing reference
+- Deterministic audio routing
+- Reduced clock synchronization complexity
+- Easier debugging and expansion
+- Clear separation between control domain and audio domain
+
+### Negative
+
+- External audio devices must support slave clock operation
+- Clock distribution becomes a critical design element
+- Peripheral selection must consider I2S synchronization requirements
+
+## Rationale
+
+The ADAU1467 is selected not only as a DSP processor but as the central
+controller of the digital audio domain.
+
+This decision defines the HubAudio architecture.
@@ -0,0 +1,93 @@
+# ADR-002: SPI Control Architecture
+
+- Status: Accepted
+- Date: 2026-08-01
+- Decision Type: Hardware Architecture
+
+## Context
+
+HubAudio integrates multiple programmable devices requiring configuration,
+control and firmware management.
+
+The main devices involved are:
+
+- ESP32-S3 system controller
+- ADAU1467 audio processor
+- Si4684 radio receiver
+
+A clear separation between system control and internal device management is
+required.
+
+The SPI interface is used exclusively as a control interface and not as an
+audio transport interface.
+
+## Decision
+
+The SPI architecture is divided into independent 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.
+
+Each device maintains its own internal SPI master domain for accessing local
+memories or peripherals.
+
+## Architecture
+
+System control bus:
+
+            ESP32-S3
+
+          SPI MASTER
+
+              |
+    +---------+---------+
+    |                   |
+ ADAU1467            Si4684
+
+SPI SLAVE          SPI SLAVE
+
+
+ADAU1467 local memory:
+
+          ADAU1467
+
+        SPI MASTER
+
+              |
+
+          25AA1024
+      DSP Configuration Memory
+
+
+Si4684 local memory:
+
+           Si4684
+
+        SPI MASTER
+
+              |
+
+      Firmware Memory
+
+
+## Consequences
+
+### Positive
+
+- Clear ownership of every SPI bus
+- Reduced electrical loading
+- Independent firmware management
+- Easier debugging
+
+### Negative
+
+- Multiple SPI peripherals are required
+- Firmware coordination is required between domains
+
+## Rationale
+
+The ESP32-S3 supervises the system but does not replace the internal
+controllers of specialized devices.
+
+Each component remains responsible for its own functional domain.
@@ -0,0 +1,51 @@
+# ADR-004 – Power Domain Architecture
+
+- **Status:** Accepted
+- **Date:** YYYY-MM-DD
+
+# Context
+
+HubAudio integra sottosistemi con caratteristiche elettriche molto differenti:
+
+- elaborazione digitale (ESP32-S3)
+- DSP audio
+- ricevitore radio
+- Bluetooth
+- codec audio
+- periferiche di controllo
+
+Una distribuzione tradizionale mediante un unico rail a 3.3 V comporterebbe la condivisione delle correnti impulsive tra dispositivi con requisiti completamente differenti, aumentando il rumore di alimentazione e rendendo più complesso il debug del sistema.
+
+# Decision
+
+L'architettura di alimentazione viene organizzata mediante **Power Domains**.
+
+La distribuzione primaria genera due domini principali:
+
+- **3V3_DIGITAL**
+- **3V3_AUDIO**
+
+Il dominio digitale alimenta esclusivamente la logica di controllo.
+
+Il dominio audio alimenta esclusivamente i dispositivi appartenenti alla catena audio.
+
+Ogni nuovo sottosistema dovrà appartenere ad un dominio chiaramente identificato.
+
+La separazione dei domini rappresenta una scelta architetturale e non un dettaglio implementativo.
+
+# Consequences
+
+## Advantages
+
+- riduzione del rumore tra domini
+- migliore immunità EMI
+- maggiore modularità
+- possibilità di monitoraggio energetico
+- semplificazione del power sequencing
+- migliore manutenibilità
+
+## Trade-offs
+
+- incremento del numero di rail
+- maggiore complessità dello schema
+- maggiore attenzione richiesta durante il layout PCB
@@ -0,0 +1,54 @@
+# ADR-005 – Audio Power Isolation
+
+- **Status:** Accepted
+- **Date:** YYYY-MM-DD
+
+# Context
+
+Il dominio audio comprende dispositivi con elevata sensibilità ai disturbi di alimentazione.
+
+Condividere la medesima alimentazione tra DSP, ricevitore radio, codec e modulo Bluetooth aumenterebbe la probabilità di accoppiamenti indesiderati.
+
+# Decision
+
+Ogni Integrated Circuit appartenente al dominio audio dispone di un proprio ramo di alimentazione indipendente.
+
+Ogni ramo segue la seguente topologia:
+
+3V3_AUDIO
+↓
+
+TPS22918
+
+↓
+
+Ferrite Bead
+
+↓
+
+Condensatori locali
+
+↓
+
+Integrated Circuit
+
+Il Power Switch permette il controllo indipendente del dominio.
+
+La ferrite realizza l'isolamento ad alta frequenza.
+
+I condensatori locali garantiscono il corretto bypass del dispositivo.
+
+# Consequences
+
+## Advantages
+
+- isolamento reciproco dei dispositivi
+- riduzione delle interferenze
+- possibilità di riavvio del singolo componente
+- power sequencing
+- minore propagazione del rumore
+
+## Trade-offs
+
+- aumento del numero di componenti
+- incremento dell'area PCB
@@ -0,0 +1,42 @@
+# ADR-006 – Power Switching Strategy
+
+- **Status:** Accepted
+- **Date:** YYYY-MM-DD
+
+# Context
+
+HubAudio è progettato come piattaforma modulare.
+
+I sottosistemi possono essere utilizzati singolarmente oppure contemporaneamente.
+
+La possibilità di controllare dinamicamente l'alimentazione costituisce un requisito fondamentale.
+
+# Decision
+
+Ogni dominio audio viene alimentato attraverso un Load Switch dedicato.
+
+Il firmware controlla direttamente i Load Switch mediante GPIO.
+
+I domini possono essere:
+
+- abilitati
+- disabilitati
+- riavviati
+- sequenziati
+
+Il firmware implementa la sequenza di accensione e spegnimento del sistema.
+
+# Consequences
+
+## Advantages
+
+- riduzione dei consumi
+- riavvio selettivo dei dispositivi
+- migliore gestione degli errori
+- possibilità di future modalità operative
+- migliore diagnostica
+
+## Trade-offs
+
+- firmware leggermente più complesso
+- gestione delle temporizzazioni di accensione
@@ -0,0 +1,41 @@
+# ADR-007 – PCB Power Distribution Strategy
+
+- Status: Accepted
+
+# Context
+
+La distribuzione dell'alimentazione su un PCB multistrato influenza direttamente:
+
+- rumore
+- EMI
+- stabilità
+- integrità del segnale
+
+# Decision
+
+Il PCB utilizza uno stack-up a quattro layer.
+
+Il layer di alimentazione non è costituito da un unico piano.
+
+Viene realizzato:
+
+- un poligono dedicato al dominio 3V3_DIGITAL;
+
+- piste dedicate per tutti i domini audio.
+
+Ogni dominio audio viene distribuito individualmente fino al rispettivo dispositivo.
+
+Non vengono creati piani condivisi per il dominio audio.
+
+# Rationale
+
+Questa soluzione:
+
+- riduce le correnti condivise;
+- migliora l'isolamento;
+- facilita il debug;
+- semplifica l'espansione futura della piattaforma.
+
+# Consequences
+
+Il layout richiede una pianificazione accurata della distribuzione delle alimentazioni ma garantisce una maggiore robustezza dell'intero sistema.