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