📘 Class Design Rationale for FluxSand

This document explains the rationale behind the class architecture in the FluxSand embedded system project. Our objective is to create a modular, testable, and extensible design that adheres to solid software engineering principles while efficiently interfacing with real-time hardware.

🧱 Hardware Abstraction Layer (HAL)

Gpio, I2cDevice, SpiDevice, PWM

These foundational classes abstract hardware-level operations such as GPIO configuration, I2C/SPI communication, and PWM control on the Raspberry Pi platform.

  • Single Responsibility Principle (SRP): Each class manages exactly one type of hardware peripheral.
  • Open/Closed Principle (OCP): They are designed to be extended (e.g., injected into drivers like Mpu9250 or Ads1115) without requiring modification.
  • Dependency Inversion Principle (DIP): Upper layers (like SensorManager or InputHandler) depend only on the abstraction of hardware, not specific implementations.

Example usage:

Gpio button1("gpiochip0", 23, false);
SpiDevice spiDisplay("/dev/spidev1.0", 1000000, SPI_MODE_0);

🎛 Device Drivers

Mpu9250, Aht20, Bmp280, Ads1115, Max7219

Each device driver class encapsulates the full lifecycle and protocol logic of a specific sensor or actuator.

  • SRP: Encapsulates initialization, register handling, data decoding, and calibration.
  • OCP: Easy to add new sensor types with separate drivers.
  • LSP: Interchangeable with alternative implementations without affecting client code (e.g., another IMU class).

These drivers decouple sensor-specific details from application logic.

🔄 Computational Components

AHRS, InferenceEngine, SandGrid

These logic-only modules handle signal processing, orientation estimation, machine learning inference, and visual simulations.

  • SRP: Each component focuses on a single computation domain.
  • OCP/LSP: Swappable models, configurable inference strategies, and reusable logic.
  • InferenceEngine supports consensus voting and confidence filtering for robust gesture recognition.

🧠 Control and Coordination Modules

CompGuiX, ModeManager, SensorManager, InputHandler, InferenceHandler, FluxSand

These higher-level modules act as coordinators between inputs, logic, and output rendering.

Class Responsibility
CompGuiX GUI rendering, time display, sand simulation
ModeManager Mode switching, stopwatch and timer logic
SensorManager Aggregates and filters sensor data
InputHandler Manages GPIO interrupt handling and input logic
InferenceHandler Maps model output to application actions
FluxSand Top-level orchestrator of all system components

Each class has a focused role and collaborates via callbacks and shared interfaces.

  • DIP: Each handler uses only references to high-level abstractions.
  • ISP: Modules expose minimal interfaces (e.g., time rendering or orientation control only).

🧪 Testability and Extensibility

  • All hardware classes can be mocked for unit testing.
  • Modules expose unit test functions (e.g., RunUnitTest()).
  • Logic and IO are decoupled to support simulation, CI, or deployment to other boards.

✅ Summary: Class Design at a Glance

Principle Applied Through
SRP Clear responsibility boundaries for each class
OCP Easy to add features or sensors without code changes
LSP Subclassing works transparently with clients
ISP Interfaces expose only what is needed
DIP Logic depends on abstractions, not hardware specifics

This design allows FluxSand to scale from a classroom prototype to a fully featured embedded platform with minimal refactoring.

For detailed API usage and hardware schematics, refer to the accompanying documentation pages.