aggiornamento di alcuni file e revisione directory repository 202608012135

docs/adr/ADR-000-Engineering-Principles.md

@@ -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

docs/adr/ADR-001-ADAU1467-Audio-Domain-Master.md

@@ -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.

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

@@ -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.

docs/adr/ADR-004-Power-Domain-Architecture.md

@@ -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

docs/adr/ADR-005–Audio-Power-Isolation.md

@@ -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

docs/adr/ADR-006–Power-Switching-Strategy.md

@@ -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

docs/adr/ADR-007–PCB-Power-Distribution-Strategy.md

@@ -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.

docs/architecture/PCB_Stackup.md

@@ -0,0 +1,96 @@
+# docs/architecture/PCB_Stackup.md
+
+# PCB Stack-up
+
+## Layer Structure
+
+HubAudio utilizza un PCB a quattro layer.
+
+```
+Layer 1
+Top
+Components + Signals
+
+Layer 2
+Continuous Ground Plane
+
+Layer 3
+Power Distribution
+
+Layer 4
+Bottom Signals
+```
+
+---
+
+## Ground Plane
+
+Il secondo layer è un piano GND continuo.
+
+Non vengono create interruzioni.
+
+Il piano di massa costituisce il riferimento comune per:
+
+- segnali
+- alimentazioni
+- ritorni di corrente
+- impedenza controllata
+
+---
+
+## Power Layer
+
+Il layer di alimentazione non è costituito da un unico piano.
+
+Sono presenti:
+
+- un poligono dedicato al dominio digitale;
+- piste dedicate ai domini audio.
+
+```
+Inner2
+
++-------------------------------+
+
+ 3V3_DIGITAL
+ ███████████████████████████
+
+        │
+
+        ├─────────────► 3V3_ADAU
+
+        ├─────────────► 3V3_SI4684
+
+        ├─────────────► 3V3_BT
+
+        ├─────────────► 1V8_ADAU
+
+        └─────────────► 1V2_ADAU
+```
+
+---
+
+## Routing Philosophy
+
+Il dominio digitale utilizza un poligono dedicato.
+
+Le alimentazioni audio vengono distribuite tramite piste dedicate.
+
+Questa scelta:
+
+- riduce il rumore condiviso;
+- limita le correnti impulsive;
+- semplifica il controllo EMI;
+- migliora la leggibilità del layout.
+
+---
+
+## Local Decoupling
+
+Ogni IC dispone di:
+
+- condensatori di bypass locali;
+- ferrite dedicata;
+- power switch dedicato.
+
+La distribuzione dell'alimentazione è quindi gerarchica e non condivisa.

docs/architecture/Power_Architecture.md

@@ -0,0 +1,79 @@
+# docs/architecture/Power_Architecture.md
+
+# Power Architecture
+
+## Overview
+
+HubAudio adotta un'architettura di alimentazione basata su **Power Domains** indipendenti anziché su una semplice distribuzione delle tensioni.
+
+L'obiettivo è ottenere:
+
+- isolamento tra domini digitali e audio;
+- riduzione delle interferenze EMI;
+- possibilità di power sequencing;
+- monitoraggio energetico;
+- elevata modularità.
+
+L'intera distribuzione dell'alimentazione è organizzata come una gerarchia di domini funzionali.
+
+```
+                VIN
+                 │
+          Primary Buck 3.3V
+                 │
+        ┌────────┴────────┐
+        │                 │
+   3V3_DIGITAL      3V3_AUDIO_RAW
+                          │
+                     π Filter
+                          │
+                      INA226
+                          │
+                     3V3_AUDIO
+```
+
+---
+
+## Digital Power Domain
+
+Il dominio digitale alimenta esclusivamente i componenti di controllo.
+
+Comprende:
+
+- ESP32-S3
+- EEPROM
+- GPIO Expander
+- Display
+- Bus I²C
+- Logica digitale
+
+Questo dominio è distribuito tramite un poligono dedicato sul layer di alimentazione.
+
+---
+
+## Audio Power Domain
+
+Il dominio audio deriva direttamente dal convertitore principale ma viene completamente isolato tramite:
+
+- filtro π
+- monitor INA226
+- distribuzione dedicata
+
+Il dominio audio alimenta esclusivamente i dispositivi audio.
+
+Ogni IC riceve successivamente un'alimentazione dedicata mediante un proprio Power Switch.
+
+---
+
+## Design Philosophy
+
+HubAudio considera ogni sottosistema come un dominio energetico indipendente.
+
+Ogni dominio deve poter essere:
+
+- acceso
+- spento
+- monitorato
+- riavviato
+
+senza influenzare gli altri.

docs/architecture/Power_Domains.md

@@ -0,0 +1,106 @@
+# docs/architecture/Power_Domains.md
+
+# Power Domains
+
+## Overview
+
+Ogni Integrated Circuit appartenente al dominio audio possiede un'alimentazione dedicata.
+
+La distribuzione segue sempre la stessa topologia.
+
+```
+3V3_AUDIO
+     │
+ TPS22918
+     │
+ Ferrite
+     │
+10µF
+1µF
+100nF
+     │
+Audio IC
+```
+
+Questa architettura permette:
+
+- isolamento elettrico
+- riduzione del rumore
+- power sequencing
+- diagnostica
+
+---
+
+# ADAU1467 Domain
+
+```
+3V3_AUDIO
+      │
+ TPS22918
+      │
+ Ferrite
+      │
+ AVDD / PVDD
+```
+
+Le tensioni locali vengono generate mediante LDO dedicati.
+
+```
+3V3_ADAU
+      │
+ TPS7A2018
+      │
+ 1V8_ADAU
+```
+
+```
+3V3_ADAU
+      │
+ TPS7A2012
+      │
+ 1V2_ADAU
+```
+
+---
+
+# Si4684 Domain
+
+```
+3V3_AUDIO
+      │
+ TPS22918
+      │
+ Ferrite
+      │
+ Si4684
+```
+
+---
+
+# Bluetooth Domain
+
+```
+3V3_AUDIO
+      │
+ TPS22918
+      │
+ Ferrite
+      │
+ Bluetooth Module
+```
+
+---
+
+# Future Domains
+
+L'architettura permette di aggiungere ulteriori domini senza modificare quelli esistenti.
+
+Esempi:
+
+- DAC
+- ADC
+- SPDIF
+- HDMI Audio
+- DSP aggiuntivi
+
+Ogni nuovo dominio segue la medesima struttura.

docs/engineering/Engineering_Principles.md

@@ -0,0 +1,296 @@
+# HubAudio Engineering Principles
+
+**Document:** Engineering Principles
+
+**Version:** 0.1 (Draft)
+
+**Status:** Draft
+
+**Applies to:** Entire HubAudio Project
+
+---
+
+# 1. Purpose
+
+This document defines the engineering principles that govern the design,
+development, documentation and maintenance of the HubAudio platform.
+
+These principles apply equally to:
+
+- Hardware
+- Firmware
+- Documentation
+- Architecture
+- Development tools
+
+Every engineering decision shall be consistent with these principles.
+
+Whenever a principle cannot be respected, the reason shall be documented
+through an Architecture Decision Record (ADR).
+
+---
+
+# 2. Vision
+
+HubAudio is not simply an electronic board.
+
+HubAudio is an embedded digital audio platform designed to evolve over
+many years while remaining understandable, maintainable and reliable.
+
+The project values engineering quality over feature quantity.
+
+Every design decision should reduce complexity rather than increase it.
+
+---
+
+# 3. Core Values
+
+The project follows these values, listed in order of importance.
+
+1. Understandability
+2. Maintainability
+3. Reliability
+4. Modularity
+5. Extensibility
+6. Performance
+
+Performance is important.
+
+Understanding the system is more important.
+
+---
+
+# 4. Fundamental Principle
+
+## EP-001 — Code That Fits in Your Head
+
+This is the fundamental engineering principle of HubAudio.
+
+The concept applies to every engineering artifact.
+
+An engineering artifact includes:
+
+- Source code
+- Electrical schematics
+- PCB layout
+- Documentation
+- Architecture diagrams
+- Firmware modules
+- Test procedures
+- Design notes
+
+Every engineering artifact should remain understandable by a single
+engineer during a normal working session.
+
+When understanding an artifact requires reading many unrelated parts of
+the project, the design should be reconsidered.
+
+Complexity shall never be removed by hiding it elsewhere.
+
+Complexity shall instead be isolated inside the component responsible
+for it.
+
+---
+
+### EP-001.a — One Sheet, One Story
+
+Each schematic sheet shall describe one subsystem.
+
+Examples:
+
+- ESP32 System Controller
+- Power Management
+- DSP Engine
+- Radio Engine
+- Bluetooth Engine
+- USB Interface
+
+A schematic shall never mix unrelated functions simply to reduce the
+number of pages.
+
+Readability is always preferred over compactness.
+
+---
+
+### EP-001.b — One Document, One Topic
+
+Each document shall describe one subject.
+
+If a document becomes too large, it should be divided into multiple
+documents.
+
+Documentation shall remain easy to navigate.
+
+---
+
+### EP-001.c — One Module, One Responsibility
+
+Each firmware module shall implement one responsibility only.
+
+Modules communicate through interfaces.
+
+Implementation details remain internal.
+
+---
+
+### EP-001.d — One PCB Area, One Function
+
+PCB placement should reflect the logical architecture.
+
+Subsystems should remain visually identifiable.
+
+Power, DSP, Radio, Bluetooth and Controller sections should remain
+clearly separated whenever practical.
+
+---
+
+# 5. Engineering Principles
+
+## EP-002 — Single Responsibility
+
+Every hardware and software component shall have one clearly defined
+responsibility.
+
+Responsibilities shall never overlap.
+
+---
+
+## EP-003 — Architecture Before Implementation
+
+The design process always follows this order:
+
+Architecture
+
+↓
+
+Documentation
+
+↓
+
+Implementation
+
+↓
+
+Verification
+
+Implementation shall never drive architecture.
+
+---
+
+## EP-004 — Hardware Independence
+
+Firmware shall communicate with logical devices.
+
+Hardware details shall remain confined inside the Hardware Abstraction
+Layer whenever practical.
+
+---
+
+## EP-005 — Modular Hardware
+
+Each subsystem should, whenever technically possible, provide:
+
+- Independent power control
+- Independent reset
+- Diagnostic capability
+- Firmware update capability
+
+---
+
+## EP-006 — Digital First
+
+Audio shall remain digital until analog conversion is explicitly
+required.
+
+---
+
+## EP-007 — Observable System
+
+Every subsystem shall expose sufficient diagnostic information.
+
+A system that cannot be observed cannot be maintained efficiently.
+
+---
+
+## EP-008 — Serviceability
+
+Maintenance shall be considered from the beginning of the project.
+
+Firmware update, diagnostics and hardware verification are part of the
+system architecture.
+
+They are not optional features.
+
+---
+
+## EP-009 — Documentation is Part of the Product
+
+Documentation is part of the engineering deliverable.
+
+Every important design decision shall be documented.
+
+Outdated documentation shall be considered a defect.
+
+---
+
+## EP-010 — Continuous Improvement
+
+Engineering decisions are based on evidence.
+
+Whenever a better solution becomes available, it shall be evaluated
+using objective engineering criteria.
+
+Previous decisions are never protected by pride.
+
+---
+
+# 6. Engineering Rules
+
+The following practical rules derive directly from these principles.
+
+- Small classes
+- Small functions
+- Explicit interfaces
+- No hidden side effects
+- Clear ownership
+- Minimal coupling
+- Meaningful names
+- Predictable behaviour
+
+---
+
+# 7. Definition of Done
+
+A development activity is complete only when:
+
+✓ Implementation completed
+
+✓ Documentation updated
+
+✓ Review completed
+
+✓ Tests completed
+
+✓ Future maintenance considered
+
+---
+
+# 8. Scope
+
+These principles apply to every future revision of HubAudio unless
+explicitly superseded by a newer approved version.
+
+---
+
+# 9. References
+
+- ADR-000 — Engineering Principles
+
+- Mark Seemann
+  *Code That Fits in Your Head*
+
+- Robert C. Martin
+  *Clean Architecture*
+
+- John Ousterhout
+  *A Philosophy of Software Design*

docs/knowledge/Engineering_Journal.md

@@ -0,0 +1,48 @@
+# HubAudio Engineering Journal
+
+Version: 1.0
+
+Status: Living Document
+
+---
+
+# Purpose
+
+This journal records the engineering journey behind HubAudio.
+
+It is not a development log.
+
+It is not a changelog.
+
+It is a collection of engineering decisions, lessons learned,
+mistakes avoided and design rationale.
+
+The purpose is to preserve knowledge rather than events.
+
+---
+
+# Philosophy
+
+The objective of HubAudio is not only to build an embedded audio platform.
+
+The primary objective is to become a better engineer while building it.
+
+Every challenge is considered an opportunity to understand a technology
+rather than simply making it work.
+
+The final PCB is one result.
+
+The acquired engineering knowledge is the most valuable result.
+
+---
+
+# First Entry
+
+Today we established that engineering methodology is part of the project.
+
+Architecture, documentation, firmware and hardware shall evolve together.
+
+Every future decision should increase the knowledge contained in this
+repository.
+
+HubAudio is not only an embedded platform.

docs/legacy/HUBAudio_Bus_and_Pin_Assignment.md

@@ -0,0 +1,588 @@
+# HubAudio
+# Bus Architecture and Preliminary Pin Assignment
+
+**Document:** Hardware Interface Definition  
+**Revision:** 0.1  
+**Status:** Preliminary Design  
+**Controller:** ESP32-S3
+
+
+---
+
+# 1. Purpose
+
+This document defines the preliminary hardware interfaces between the ESP32-S3 system controller and all HubAudio modules.
+
+The purpose is to establish:
+
+- bus ownership
+- GPIO allocation
+- peripheral assignment
+- boot-safe pins
+- expansion possibilities
+
+
+This document must be reviewed before PCB routing.
+
+
+---
+
+# 2. Design Rules
+
+
+The following rules apply:
+
+
+## Rule 1
+
+The ESP32-S3 controls configuration only.
+
+
+Audio data does not pass through the MCU.
+
+
+---
+
+## Rule 2
+
+All audio sources connect directly to ADAU1467.
+
+
+
+SOURCE
+
+|
+
+I2S
+
+|
+
+ADAU1467
+
+
+
+---
+
+## Rule 3
+
+Every external module must be identifiable.
+
+
+Identification:
+
+
+24AA025E48T-I/OT
+
+
+
+---
+
+# 3. ESP32-S3 Peripheral Allocation
+
+
+## 3.1 Overview
+
+
+| Function | Interface |
+|-|-|
+| Radio control | SPI |
+| DSP control | I2C |
+| Module EEPROM | I2C |
+| Bluetooth control | UART |
+| Debug | USB/JTAG |
+| Expansion | Reserved GPIO |
+
+
+---
+
+# 4. Proposed GPIO Map
+
+
+## 4.1 I2C Bus
+
+
+Shared bus:
+
+
+| Signal | ESP32-S3 GPIO | Devices |
+|-|-|-|
+| SDA | GPIO8 | EEPROM, ADAU1467 |
+| SCL | GPIO9 | EEPROM, ADAU1467 |
+
+
+Notes:
+
+- keep traces short
+- external pull-ups required
+- address conflicts must be checked
+
+
+---
+
+# 4.2 SPI Bus
+
+
+Used for radio and memories.
+
+
+| Signal | ESP32-S3 GPIO | Function |
+|-|-|-|
+| SCLK | GPIO12 | SPI Clock |
+| MOSI | GPIO11 | SPI Data |
+| MISO | GPIO13 | SPI Data |
+| CS_RADIO | GPIO10 | Si4684 |
+| CS_FLASH | GPIO14 | External memories |
+
+
+---
+
+# 4.3 UART Bus
+
+
+Bluetooth modules:
+
+
+## BT RX
+
+
+| Signal | GPIO |
+|-|-|
+| TX ESP32 | GPIO17 |
+| RX ESP32 | GPIO18 |
+
+
+## BT1035 TX
+
+
+Second UART:
+
+
+| Signal | GPIO |
+|-|-|
+| TX ESP32 | GPIO43 |
+| RX ESP32 | GPIO44 |
+
+
+Notes:
+
+ESP32-S3 provides multiple UART peripherals.
+
+
+---
+
+# 4.4 Module Control GPIO
+
+
+| Signal | GPIO | Function |
+|-|-|-|
+| RADIO_RESET | GPIO4 | Si4684 reset |
+| DSP_RESET | GPIO5 | ADAU1467 reset |
+| BT_RX_RESET | GPIO6 | BT receiver reset |
+| BT_TX_RESET | GPIO7 | BT1035 reset |
+
+
+---
+
+# 5. Si4684 Interface
+
+
+## Control
+
+
+SPI:
+
+
+
+ESP32-S3
+
+SCLK
+|
+Si4684 CLK
+
+MOSI
+|
+Si4684 SDIO
+
+CS
+|
+Si4684 CS
+
+
+
+Control:
+
+
+
+GPIO4
+
+|
+
+RESET
+
+
+
+Interrupt:
+
+
+
+Si4684 IRQ
+
+|
+
+ESP32 GPIO
+
+
+
+---
+
+# 6. ADAU1467 Interface
+
+
+## Control Interface
+
+
+Preferred:
+
+
+I2C
+
+
+
+ESP32-S3
+
+SDA
+
+SCL
+
+|
+
+ADAU1467
+
+
+
+Used for:
+
+
+- volume
+- routing
+- DSP parameters
+
+
+---
+
+# 7. Bluetooth TX Interface
+
+
+Device:
+
+FSC-BT1035
+
+
+## Control
+
+
+UART:
+
+
+
+ESP32-S3
+
+TX
+
+|
+
+BT1035 RX
+
+ESP32-S3
+
+RX
+
+|
+
+BT1035 TX
+
+
+
+---
+
+## Audio
+
+
+I2S:
+
+
+
+ADAU1467
+
+  |
+
+  |
+
+BT1035
+
+BCLK
+
+LRCLK
+
+DATA
+
+
+
+The clock direction must be verified.
+
+
+Preferred:
+
+
+ADAU1467 master.
+
+
+---
+
+# 8. Bluetooth RX Interface
+
+
+Device:
+
+FSC-BT1026 or equivalent.
+
+
+## Control
+
+
+UART:
+
+
+
+ESP32-S3
+
+|
+
+BT RX Module
+
+
+
+---
+
+## Audio
+
+
+
+BT RX
+
+|
+
+I2S OUT
+
+|
+
+ADAU1467 INPUT
+
+
+
+---
+
+# 9. I2S Architecture
+
+
+## Important Design Decision
+
+
+Multiple I2S sources are not connected together.
+
+
+Wrong:
+
+
+
+Si4684
+|
+|
+BT RX
+|
++------ I2S ------ ADAU1467
+
+
+
+Correct:
+
+
+
+Si4684
+
+I2S Port 0
+
+    |
+
+    |
+
+ADAU1467
+
+BT RX
+
+I2S Port 1
+
+    |
+
+    |
+
+ADAU1467
+
+
+
+The ADAU1467 internal serial ports perform routing.
+
+
+---
+
+# 10. Proposed ADAU1467 Serial Port Allocation
+
+
+| DSP Port | Device | Direction |
+|-|-|-|
+| Serial Input 0 | Si4684 | RX |
+| Serial Input 1 | BT RX | RX |
+| Serial Output 0 | DAC | TX |
+| Serial Output 1 | BT1035 | TX |
+
+
+---
+
+# 11. EEPROM Bus
+
+
+All modules include:
+
+
+
+24AA025E48T
+
+
+
+Example:
+
+
+| Module | Address |
+|-|-|
+| Main Board | 0x50 |
+| Radio | 0x51 |
+| Bluetooth | 0x52 |
+| DSP | 0x53 |
+
+
+Address selection must be verified.
+
+
+---
+
+# 12. Reserved Expansion Interface
+
+
+Future modules:
+
+
+Possible:
+
+- external DAC
+- amplifier module
+- display
+- sensors
+- remote control
+
+
+Reserved:
+
+
+SPI
+
+I2C
+
+UART
+
+I2S
+
+GPIO
+
+Power
+
+
+
+---
+
+# 13. Boot Safety Review
+
+
+ESP32-S3 boot pins must be checked.
+
+
+Before PCB release:
+
+
+Verify:
+
+- GPIO assignment
+- strapping pins
+- pull-up/pull-down resistors
+
+
+No external device must force an incorrect boot state.
+
+
+---
+
+# 14. Recommended Connector Between Modules
+
+
+For removable modules:
+
+
+Example:
+
+
+
+MODULE HEADER
+
+1 3.3V
+2 GND
+3 SDA
+4 SCL
+5 UART TX
+6 UART RX
+7 RESET
+8 IRQ
+9 I2S BCLK
+10 I2S LRCLK
+11 I2S DATA
+12 RESERVED
+
+
+
+---
+
+# 15. Final Review Before Schematic
+
+
+Before drawing schematic:
+
+
+Check:
+
+
+[ ] ESP32-S3 GPIO availability
+
+[ ] Boot strap conflicts
+
+[ ] I2S clock ownership
+
+[ ] Module power consumption
+
+[ ] RF placement
+
+[ ] EEPROM addressing
+
+[ ] Firmware update paths
+
+
+---
+
+# END

docs/legacy/HUBAudio_Power_Management_Architecture.md

@@ -0,0 +1,519 @@
+# HubAudio
+# Power Management Architecture
+
+**Document:** Power Management Design Specification  
+**Revision:** 0.1  
+**Status:** Design Phase  
+
+---
+
+# 1. Overview
+
+The HubAudio platform requires a sophisticated power management architecture.
+
+The system combines:
+
+- ESP32-S3 high performance MCU with WiFi
+- ADAU1467 professional audio DSP
+- Si4684 FM/DAB receiver
+- Bluetooth audio transmitter
+- Bluetooth audio receiver
+- battery operation
+- remote monitoring capability
+
+
+The power system is therefore not considered a simple voltage regulator stage, but a complete energy management subsystem.
+
+---
+
+# 2. Design Philosophy
+
+The selected architecture follows these principles:
+
+- single intelligent PMIC
+- integrated battery management
+- multiple independent power rails
+- I2C monitoring
+- controlled power sequencing
+- ability to disable unused subsystems
+- separated digital and audio power domains
+
+
+---
+
+# 3. Selected Main PMIC
+
+## Texas Instruments TPS65217CRSLR
+
+
+The TPS65217 is selected as the main power management IC.
+
+
+Reasons for selection:
+
+
+- integrated Li-Ion battery charger
+- power path management
+- multiple switching regulators
+- LDO outputs
+- I2C configuration
+- programmable sequencing
+- fault monitoring
+
+
+Although originally designed for embedded processor systems, its architecture is suitable for HubAudio due to the need for multiple controlled power domains.
+
+
+---
+
+# 4. Power Tree
+
+
+Proposed architecture:
+
+
+             USB-C / External Power
+
+                     |
+
+                     |
+
+             TPS65217CRSLR
+
+                     |
+
+    +----------------+----------------+
+
+    |                |                |
+
+ DCDC1             DCDC2            DCDC3
+
+    |                |                |
+
+3.3V_DIGITAL 3.3V_AUDIO 5V
+
+    |                |
+
+    |                |
+
+ESP32-S3 Audio/RF domain
+
+                |
+
+          Ferrite filtering
+
+
+                |
+
+    +-----------+-----------+
+
+    |           |           |
+
+ADAU1467    Si4684      Bluetooth
+
+
+---
+
+# 5. Power Domains
+
+
+## 5.1 Digital Domain
+
+
+Voltage:
+
+3.3V_DIGITAL
+
+
+Consumers:
+
+
+- ESP32-S3
+- EEPROM
+- logic peripherals
+- communication interfaces
+
+
+Requirements:
+
+
+- high transient capability
+- low impedance supply
+
+
+Main concern:
+
+ESP32-S3 WiFi current peaks.
+
+
+---
+
+# 5.2 Audio / RF Domain
+
+
+Voltage:
+
+3.3V_AUDIO
+
+
+Consumers:
+
+
+- ADAU1467
+- Si4684
+- BT1035
+- Bluetooth RX module
+
+
+This rail must be isolated from digital noise.
+
+
+Recommended:
+
+
+
+3.3V_AUDIO
+
+  |
+
+ferrite bead
+
+  |
+
+audio devices
+
+
+
+---
+
+# 5.3 5V Domain
+
+
+Possible consumers:
+
+
+- DAC
+- amplifier
+- future peripherals
+
+
+This rail is kept independent from sensitive audio electronics.
+
+
+---
+
+# 6. Battery Management
+
+
+The TPS65217 provides:
+
+
+- Li-Ion charging
+- battery monitoring
+- power path control
+- protection mechanisms
+
+
+Battery:
+
+
+
+Single cell Li-Ion
+
+3.7V nominal
+
+4.2V charged
+
+
+
+---
+
+# 7. Power Monitoring
+
+
+## 7.1 Decision
+
+
+The TPS65217 already provides battery management.
+
+An additional current monitor is not required for system operation.
+
+
+However, HubAudio benefits from detailed subsystem monitoring.
+
+
+A dedicated I2C power monitor is therefore added for the audio domain.
+
+
+---
+
+# 8. Selected Current Monitor
+
+
+## Texas Instruments INA226
+
+
+The INA226 is selected as the default power monitoring device.
+
+
+Purpose:
+
+
+Measure the audio subsystem consumption.
+
+
+Monitored rail:
+
+
+
+TPS65217
+
+|
+
+3.3V_AUDIO
+
+|
+
+INA226
+
+|
+
+ADAU1467
+Si4684
+Bluetooth
+
+
+
+---
+
+# 9. INA226 Functions
+
+
+The INA226 provides:
+
+
+- bus voltage measurement
+- shunt voltage measurement
+- current measurement
+- power calculation
+- I2C communication
+
+
+The ESP32-S3 can periodically read:
+
+
+
+Voltage
+
+Current
+
+Power
+
+
+
+Example:
+
+
+```json
+{
+ "audio_voltage":3.30,
+ "audio_current":180,
+ "audio_power":0.59
+}
+
+10. INA228 Evaluation
+
+The INA228 has been evaluated as an alternative.
+
+Advantages:
+
+higher resolution ADC
+higher precision
+energy accumulation
+advanced power analysis
+
+Typical application:
+
+laboratory measurements
+industrial systems
+precision battery analysis
+
+For HubAudio:
+
+Not selected as default.
+
+Reason:
+
+The additional precision is not necessary because:
+
+battery management is already handled by TPS65217
+audio subsystem consumption does not require laboratory accuracy
+11. Future Compatibility
+
+The PCB should allow optional replacement:
+
+INA226 footprint compatible with INA228 evaluation.
+
+Possible versions:
+
+Standard
+TPS65217
++
+INA226
+
+Engineering / Pro Version
+TPS65217
++
+INA228
+
+12. I2C Monitoring Bus
+
+The power monitoring devices share the system I2C bus.
+
+Example:
+
+ESP32-S3
+
+
+ |
+
+I2C
+
+
+ +---- EEPROM
+
+ |
+
+ +---- ADAU1467
+
+ |
+
+ +---- INA226
+
+ |
+
+ +---- TPS65217
+
+
+13. Power Sequencing
+
+Startup sequence:
+
+Battery connected
+
+
+ |
+
+TPS65217 initialization
+
+
+ |
+
+3.3V_DIGITAL enabled
+
+
+ |
+
+ESP32-S3 boot
+
+
+ |
+
+Module detection
+
+
+ |
+
+Enable audio domain
+
+
+ |
+
+Initialize DSP
+
+
+ |
+
+Enable RF modules
+
+
+14. Controlled Shutdown
+
+The ESP32-S3 can disable:
+
+Bluetooth TX
+Bluetooth RX
+Si4684
+ADAU1467
+
+Example:
+
+Standby:
+
+
+ESP32-S3 ON
+
+WiFi ON
+
+Audio OFF
+
+Radio OFF
+
+Bluetooth OFF
+
+
+15. PCB Layout Requirements
+
+Critical:
+
+Switching regulators
+
+Keep away from:
+
+ADAU1467
+DAC
+RF sections
+Audio supply
+
+Use:
+
+short traces
+filtering
+dedicated return paths
+Decoupling
+
+Every IC requires local decoupling.
+
+Additional filtering is required for:
+
+DSP supply
+RF supply
+16. Final Decision
+
+The HubAudio power architecture is:
+
+TPS65217CRSLR
+
++
+
+Separate audio power domain
+
++
+
+INA226 monitoring
+
++
+
+Optional INA228 upgrade
+
+
+
+This provides:
+
+professional power management
+battery operation
+remote diagnostics
+future scalability
+END DOCUMENT
+
+---