aggiornamento di alcuni file e revisione directory repository 202608012135
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user