diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..114486f --- /dev/null +++ b/LICENSE @@ -0,0 +1,289 @@ +CERN Open Hardware Licence Version 2 - Strongly Reciprocal + + +Preamble + +CERN has developed this licence to promote collaboration among +hardware designers and to provide a legal tool which supports the +freedom to use, study, modify, share and distribute hardware designs +and products based on those designs. Version 2 of the CERN Open +Hardware Licence comes in three variants: CERN-OHL-P (permissive); and +two reciprocal licences: CERN-OHL-W (weakly reciprocal) and this +licence, CERN-OHL-S (strongly reciprocal). + +The CERN-OHL-S is copyright CERN 2020. Anyone is welcome to use it, in +unmodified form only. + +Use of this Licence does not imply any endorsement by CERN of any +Licensor or their designs nor does it imply any involvement by CERN in +their development. + + +1 Definitions + + 1.1 'Licence' means this CERN-OHL-S. + + 1.2 'Compatible Licence' means + + a) any earlier version of the CERN Open Hardware licence, or + + b) any version of the CERN-OHL-S, or + + c) any licence which permits You to treat the Source to which + it applies as licensed under CERN-OHL-S provided that on + Conveyance of any such Source, or any associated Product You + treat the Source in question as being licensed under + CERN-OHL-S. + + 1.3 'Source' means information such as design materials or digital + code which can be applied to Make or test a Product or to + prepare a Product for use, Conveyance or sale, regardless of its + medium or how it is expressed. It may include Notices. + + 1.4 'Covered Source' means Source that is explicitly made available + under this Licence. + + 1.5 'Product' means any device, component, work or physical object, + whether in finished or intermediate form, arising from the use, + application or processing of Covered Source. + + 1.6 'Make' means to create or configure something, whether by + manufacture, assembly, compiling, loading or applying Covered + Source or another Product or otherwise. + + 1.7 'Available Component' means any part, sub-assembly, library or + code which: + + a) is licensed to You as Complete Source under a Compatible + Licence; or + + b) is available, at the time a Product or the Source containing + it is first Conveyed, to You and any other prospective + licensees + + i) as a physical part with sufficient rights and + information (including any configuration and + programming files and information about its + characteristics and interfaces) to enable it either to + be Made itself, or to be sourced and used to Make the + Product; or + ii) as part of the normal distribution of a tool used to + design or Make the Product. + + 1.8 'Complete Source' means the set of all Source necessary to Make + a Product, in the preferred form for making modifications, + including necessary installation and interfacing information + both for the Product, and for any included Available Components. + If the format is proprietary, it must also be made available in + a format (if the proprietary tool can create it) which is + viewable with a tool available to potential licensees and + licensed under a licence approved by the Free Software + Foundation or the Open Source Initiative. Complete Source need + not include the Source of any Available Component, provided that + You include in the Complete Source sufficient information to + enable a recipient to Make or source and use the Available + Component to Make the Product. + + 1.9 'Source Location' means a location where a Licensor has placed + Covered Source, and which that Licensor reasonably believes will + remain easily accessible for at least three years for anyone to + obtain a digital copy. + + 1.10 'Notice' means copyright, acknowledgement and trademark notices, + Source Location references, modification notices (subsection + 3.3(b)) and all notices that refer to this Licence and to the + disclaimer of warranties that are included in the Covered + Source. + + 1.11 'Licensee' or 'You' means any person exercising rights under + this Licence. + + 1.12 'Licensor' means a natural or legal person who creates or + modifies Covered Source. A person may be a Licensee and a + Licensor at the same time. + + 1.13 'Convey' means to communicate to the public or distribute. + + +2 Applicability + + 2.1 This Licence governs the use, copying, modification, Conveying + of Covered Source and Products, and the Making of Products. By + exercising any right granted under this Licence, You irrevocably + accept these terms and conditions. + + 2.2 This Licence is granted by the Licensor directly to You, and + shall apply worldwide and without limitation in time. + + 2.3 You shall not attempt to restrict by contract or otherwise the + rights granted under this Licence to other Licensees. + + 2.4 This Licence is not intended to restrict fair use, fair dealing, + or any other similar right. + + +3 Copying, modifying and Conveying Covered Source + + 3.1 You may copy and Convey verbatim copies of Covered Source, in + any medium, provided You retain all Notices. + + 3.2 You may modify Covered Source, other than Notices, provided that + You irrevocably undertake to make that modified Covered Source + available from a Source Location should You Convey a Product in + circumstances where the recipient does not otherwise receive a + copy of the modified Covered Source. In each case subsection 3.3 + shall apply. + + You may only delete Notices if they are no longer applicable to + the corresponding Covered Source as modified by You and You may + add additional Notices applicable to Your modifications. + Including Covered Source in a larger work is modifying the + Covered Source, and the larger work becomes modified Covered + Source. + + 3.3 You may Convey modified Covered Source (with the effect that You + shall also become a Licensor) provided that You: + + a) retain Notices as required in subsection 3.2; + + b) add a Notice to the modified Covered Source stating that You + have modified it, with the date and brief description of how + You have modified it; + + c) add a Source Location Notice for the modified Covered Source + if You Convey in circumstances where the recipient does not + otherwise receive a copy of the modified Covered Source; and + + d) license the modified Covered Source under the terms and + conditions of this Licence (or, as set out in subsection + 8.3, a later version, if permitted by the licence of the + original Covered Source). Such modified Covered Source must + be licensed as a whole, but excluding Available Components + contained in it, which remain licensed under their own + applicable licences. + + +4 Making and Conveying Products + +You may Make Products, and/or Convey them, provided that You either +provide each recipient with a copy of the Complete Source or ensure +that each recipient is notified of the Source Location of the Complete +Source. That Complete Source is Covered Source, and You must +accordingly satisfy Your obligations set out in subsection 3.3. If +specified in a Notice, the Product must visibly and securely display +the Source Location on it or its packaging or documentation in the +manner specified in that Notice. + + +5 Research and Development + +You may Convey Covered Source, modified Covered Source or Products to +a legal entity carrying out development, testing or quality assurance +work on Your behalf provided that the work is performed on terms which +prevent the entity from both using the Source or Products for its own +internal purposes and Conveying the Source or Products or any +modifications to them to any person other than You. Any modifications +made by the entity shall be deemed to be made by You pursuant to +subsection 3.2. + + +6 DISCLAIMER AND LIABILITY + + 6.1 DISCLAIMER OF WARRANTY -- The Covered Source and any Products + are provided 'as is' and any express or implied warranties, + including, but not limited to, implied warranties of + merchantability, of satisfactory quality, non-infringement of + third party rights, and fitness for a particular purpose or use + are disclaimed in respect of any Source or Product to the + maximum extent permitted by law. The Licensor makes no + representation that any Source or Product does not or will not + infringe any patent, copyright, trade secret or other + proprietary right. The entire risk as to the use, quality, and + performance of any Source or Product shall be with You and not + the Licensor. This disclaimer of warranty is an essential part + of this Licence and a condition for the grant of any rights + granted under this Licence. + + 6.2 EXCLUSION AND LIMITATION OF LIABILITY -- The Licensor shall, to + the maximum extent permitted by law, have no liability for + direct, indirect, special, incidental, consequential, exemplary, + punitive or other damages of any character including, without + limitation, procurement of substitute goods or services, loss of + use, data or profits, or business interruption, however caused + and on any theory of contract, warranty, tort (including + negligence), product liability or otherwise, arising in any way + in relation to the Covered Source, modified Covered Source + and/or the Making or Conveyance of a Product, even if advised of + the possibility of such damages, and You shall hold the + Licensor(s) free and harmless from any liability, costs, + damages, fees and expenses, including claims by third parties, + in relation to such use. + + +7 Patents + + 7.1 Subject to the terms and conditions of this Licence, each + Licensor hereby grants to You a perpetual, worldwide, + non-exclusive, no-charge, royalty-free, irrevocable (except as + stated in subsections 7.2 and 8.4) patent license to Make, have + Made, use, offer to sell, sell, import, and otherwise transfer + the Covered Source and Products, where such licence applies only + to those patent claims licensable by such Licensor that are + necessarily infringed by exercising rights under the Covered + Source as Conveyed by that Licensor. + + 7.2 If You institute patent litigation against any entity (including + a cross-claim or counterclaim in a lawsuit) alleging that the + Covered Source or a Product constitutes direct or contributory + patent infringement, or You seek any declaration that a patent + licensed to You under this Licence is invalid or unenforceable + then any rights granted to You under this Licence shall + terminate as of the date such process is initiated. + + +8 General + + 8.1 If any provisions of this Licence are or subsequently become + invalid or unenforceable for any reason, the remaining + provisions shall remain effective. + + 8.2 You shall not use any of the name (including acronyms and + abbreviations), image, or logo by which the Licensor or CERN is + known, except where needed to comply with section 3, or where + the use is otherwise allowed by law. Any such permitted use + shall be factual and shall not be made so as to suggest any kind + of endorsement or implication of involvement by the Licensor or + its personnel. + + 8.3 CERN may publish updated versions and variants of this Licence + which it considers to be in the spirit of this version, but may + differ in detail to address new problems or concerns. New + versions will be published with a unique version number and a + variant identifier specifying the variant. If the Licensor has + specified that a given variant applies to the Covered Source + without specifying a version, You may treat that Covered Source + as being released under any version of the CERN-OHL with that + variant. If no variant is specified, the Covered Source shall be + treated as being released under CERN-OHL-S. The Licensor may + also specify that the Covered Source is subject to a specific + version of the CERN-OHL or any later version in which case You + may apply this or any later version of CERN-OHL with the same + variant identifier published by CERN. + + 8.4 This Licence shall terminate with immediate effect if You fail + to comply with any of its terms and conditions. + + 8.5 However, if You cease all breaches of this Licence, then Your + Licence from any Licensor is reinstated unless such Licensor has + terminated this Licence by giving You, while You remain in + breach, a notice specifying the breach and requiring You to cure + it within 30 days, and You have failed to come into compliance + in all material respects by the end of the 30 day period. Should + You repeat the breach after receipt of a cure notice and + subsequent reinstatement, this Licence will terminate + immediately and permanently. Section 6 shall continue to apply + after any termination. + + 8.6 This Licence shall not be enforceable except by a Licensor + acting as such, and third party beneficiary rights are + specifically excluded. diff --git a/NOTICE b/NOTICE new file mode 100644 index 0000000..fc08a9b --- /dev/null +++ b/NOTICE @@ -0,0 +1,9 @@ +HubAudio + +Copyright (c) 2026 Michele Bigi + +This project contains original work developed as part of the HubAudio platform. + +Third-party components remain under their respective licences. + +Datasheets are NOT covered by this licence and remain property of their respective manufacturers. diff --git a/Hardware/datasheets/ADAU1463-1467.pdf b/datasheets/ADAU1463-1467.pdf similarity index 100% rename from Hardware/datasheets/ADAU1463-1467.pdf rename to datasheets/ADAU1463-1467.pdf diff --git a/Hardware/datasheets/AK4118AEQ.pdf b/datasheets/AK4118AEQ.pdf similarity index 100% rename from Hardware/datasheets/AK4118AEQ.pdf rename to datasheets/AK4118AEQ.pdf diff --git a/Hardware/datasheets/BQ24074RGTR.pdf b/datasheets/BQ24074RGTR.pdf similarity index 100% rename from Hardware/datasheets/BQ24074RGTR.pdf rename to datasheets/BQ24074RGTR.pdf diff --git a/Hardware/datasheets/CDB8416.pdf b/datasheets/CDB8416.pdf similarity index 100% rename from Hardware/datasheets/CDB8416.pdf rename to datasheets/CDB8416.pdf diff --git a/Hardware/datasheets/EVAL-ADAU1467Z-UG-1134.pdf b/datasheets/EVAL-ADAU1467Z-UG-1134.pdf similarity index 100% rename from Hardware/datasheets/EVAL-ADAU1467Z-UG-1134.pdf rename to datasheets/EVAL-ADAU1467Z-UG-1134.pdf diff --git a/Hardware/datasheets/FSC-BT1026x_Datasheet_EN.pdf b/datasheets/FSC-BT1026x_Datasheet_EN.pdf similarity index 100% rename from Hardware/datasheets/FSC-BT1026x_Datasheet_EN.pdf rename to datasheets/FSC-BT1026x_Datasheet_EN.pdf diff --git a/Hardware/datasheets/FSC-BT1035_Datasheet_EN.pdf b/datasheets/FSC-BT1035_Datasheet_EN.pdf similarity index 100% rename from Hardware/datasheets/FSC-BT1035_Datasheet_EN.pdf rename to datasheets/FSC-BT1035_Datasheet_EN.pdf diff --git a/Hardware/datasheets/MCHP-S-A0002323707-1.pdf b/datasheets/MCHP-S-A0002323707-1.pdf similarity index 100% rename from Hardware/datasheets/MCHP-S-A0002323707-1.pdf rename to datasheets/MCHP-S-A0002323707-1.pdf diff --git a/Hardware/datasheets/bq27441.pdf b/datasheets/bq27441.pdf similarity index 100% rename from Hardware/datasheets/bq27441.pdf rename to datasheets/bq27441.pdf diff --git a/Hardware/datasheets/ina226.pdf b/datasheets/ina226.pdf similarity index 100% rename from Hardware/datasheets/ina226.pdf rename to datasheets/ina226.pdf diff --git a/Hardware/datasheets/ina228-q1.pdf b/datasheets/ina228-q1.pdf similarity index 100% rename from Hardware/datasheets/ina228-q1.pdf rename to datasheets/ina228-q1.pdf diff --git a/Hardware/datasheets/si4684.pdf b/datasheets/si4684.pdf similarity index 100% rename from Hardware/datasheets/si4684.pdf rename to datasheets/si4684.pdf diff --git a/Hardware/datasheets/tps22918.pdf b/datasheets/tps22918.pdf similarity index 100% rename from Hardware/datasheets/tps22918.pdf rename to datasheets/tps22918.pdf diff --git a/Hardware/datasheets/tps65217.pdf b/datasheets/tps65217.pdf similarity index 100% rename from Hardware/datasheets/tps65217.pdf rename to datasheets/tps65217.pdf diff --git a/documents/ADR-000 — Engineering Philosophy.md b/docs/adr/ADR-000-Engineering-Principles.md similarity index 100% rename from documents/ADR-000 — Engineering Philosophy.md rename to docs/adr/ADR-000-Engineering-Principles.md diff --git a/docs/adr/ADR-001-ADAU1467-Audio-Domain-Master.md b/docs/adr/ADR-001-ADAU1467-Audio-Domain-Master.md new file mode 100644 index 0000000..7a9fb88 --- /dev/null +++ b/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. diff --git a/docs/adr/ADR-002-SPI-Control-Architecture.md b/docs/adr/ADR-002-SPI-Control-Architecture.md new file mode 100644 index 0000000..3022ab1 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/old_docs/HUBAudio_I2C_Address_Map.md b/docs/adr/ADR-003-I2S-Audio-Routing-Architecture.md similarity index 100% rename from old_docs/HUBAudio_I2C_Address_Map.md rename to docs/adr/ADR-003-I2S-Audio-Routing-Architecture.md diff --git a/docs/adr/ADR-004-Power-Domain-Architecture.md b/docs/adr/ADR-004-Power-Domain-Architecture.md new file mode 100644 index 0000000..d8b681b --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/adr/ADR-005–Audio-Power-Isolation.md b/docs/adr/ADR-005–Audio-Power-Isolation.md new file mode 100644 index 0000000..5109bc6 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/adr/ADR-006–Power-Switching-Strategy.md b/docs/adr/ADR-006–Power-Switching-Strategy.md new file mode 100644 index 0000000..aafa57f --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/adr/ADR-007–PCB-Power-Distribution-Strategy.md b/docs/adr/ADR-007–PCB-Power-Distribution-Strategy.md new file mode 100644 index 0000000..9bfca2d --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/architecture/PCB_Stackup.md b/docs/architecture/PCB_Stackup.md new file mode 100644 index 0000000..1ad7df7 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/architecture/Power_Architecture.md b/docs/architecture/Power_Architecture.md new file mode 100644 index 0000000..fa13f68 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/architecture/Power_Domains.md b/docs/architecture/Power_Domains.md new file mode 100644 index 0000000..e617e4a --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/engineering/Engineering_Principles.md b/docs/engineering/Engineering_Principles.md new file mode 100644 index 0000000..0ce795b --- /dev/null +++ b/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* \ No newline at end of file diff --git a/docs/knowledge/ADR-005 – Audio Power Isolation b/docs/knowledge/ADR-005 – Audio Power Isolation new file mode 100644 index 0000000..e69de29 diff --git a/docs/knowledge/Engineering_Journal.md b/docs/knowledge/Engineering_Journal.md new file mode 100644 index 0000000..b746233 --- /dev/null +++ b/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. diff --git a/old_docs/HUBAudio_Bus_and_Pin_Assignment.md b/docs/legacy/HUBAudio_Bus_and_Pin_Assignment.md similarity index 100% rename from old_docs/HUBAudio_Bus_and_Pin_Assignment.md rename to docs/legacy/HUBAudio_Bus_and_Pin_Assignment.md diff --git a/old_docs/HUBAudio_HW_Design.md b/docs/legacy/HUBAudio_HW_Design.md similarity index 100% rename from old_docs/HUBAudio_HW_Design.md rename to docs/legacy/HUBAudio_HW_Design.md diff --git a/docs/legacy/HUBAudio_I2C_Address_Map.md b/docs/legacy/HUBAudio_I2C_Address_Map.md new file mode 100644 index 0000000..e69de29 diff --git a/old_docs/HUBAudio_Power_Management_Architecture.md b/docs/legacy/HUBAudio_Power_Management_Architecture.md similarity index 100% rename from old_docs/HUBAudio_Power_Management_Architecture.md rename to docs/legacy/HUBAudio_Power_Management_Architecture.md