296 lines
5.5 KiB
Markdown
296 lines
5.5 KiB
Markdown
# 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* |