# tsj-electronics/air-piano architecture

> Architecture diagram of the GitHub repository tsj-electronics/air-piano, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tsj-electronics/air-piano
- Repository: https://github.com/tsj-electronics/air-piano

## Overview

##### Project type and purpose
- This is an embedded/hardware-oriented “air piano” instrument, built around an Arduino microcontroller and a distance sensor.
- The user waves their hand over the sensor; the firmware maps distance readings to musical notes played on a speaker or buzzer.

##### File structure
Top-level files:
- Air Piano Project.sch – schematic of the hardware wiring
- Air Pinao BOM.csv – bill of materials listing parts (sensor, Arduino board, speaker, resistors, etc.)
- Air_Piano_Code/ (directory containing firmware)
– Air_Piano_Code.ino – Arduino sketch reading the distance sensor and generating tones
- How to upload Code to Arduino.docx – setup instructions for the development environment
- README.md – high-level project description

##### README
- Very brief: “Distance sensor based air piano project :)”
- Confirms it’s a sensor-to-sound embedded application without a web or server component.

##### Main components
a. Distance sensor (e.g., HC-SR04 or similar ultrasonic/IR sensor)
b. Microcontroller (Arduino UNO or equivalent)
c. Audio output (piezo buzzer or speaker)
d. Power supply (USB 5 V or battery pack)
e. Optional: USB interface for code upload and serial debugging
f. Firmware (the .ino sketch implementing distance-to-note mapping)

##### Relationships and interactions
- The sensor measures the user’s hand distance and sends a signal (trigger/echo or analog voltage) to the Arduino’s GPIO or analog input.
- The firmware reads that signal in a timed loop, converts the distance into discrete note pitches (mapping range to musical scale).
- The Arduino outputs a PWM or tone signal on a digital pin to drive the buzzer or speaker.
- Power flows from the USB or battery to both the Arduino and the sensor.
- The USB link also carries the firmware (via the Arduino IDE) and can be used for optional serial logging.

##### Architectural patterns and design principles
- Layered/flow architecture:
1. Physical layer (sensor + speaker + power rails)
2. Firmware layer (reading, mapping, output functions)
3. External interface (USB for code upload)
- Event-driven loop: sensor event → ISR or polling → note generation
- Single responsibility: separate code modules (if expanded) for sensor reading, note mapping, and output.

##### Technologies, frameworks, and libraries
- Arduino hardware platform + C++-based Arduino core libraries
- Possibly the “NewPing” or “Ultrasonic” library for easier distance measurement
- The built-in tone() function or a custom PWM routine for audio output

- Optionally, a small inset of the schematic file name and BOM reference.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Components
    subgraph "Input Devices"
        direction TB
        Sensor["HC-SR04 Sensor"]:::input
    end

    subgraph "Processing Unit"
        direction TB
        Arduino["Arduino UNO"]:::processing
        subgraph "Firmware" 
            direction TB
            Mapper["DistanceToNoteMapper()"]:::processing
            Player["TonePlayer()"]:::processing
        end
    end

    subgraph "Output Devices"
        direction TB
        Speaker["Piezo Buzzer / Speaker"]:::output
    end

    subgraph "Interfaces & Power"
        direction TB
        Power["Power Supply (5V)"]:::power
        USB["USB Interface"]:::interface
    end

    %% Connections
    Power -->|"5V"| Sensor
    Power -->|"5V"| Arduino
    Power -->|"5V"| Speaker

    Sensor -->|"echo pulse (5V TTL)"| Arduino
    Arduino -->|"PWM @2kHz"| Speaker

    USB ---|"firmware upload / serial"| Arduino

    %% Click Events
    click Sensor "https://github.com/tsj-electronics/air-piano/blob/main/Air Piano Project.sch"
    click Arduino "https://github.com/tsj-electronics/air-piano/blob/main/Air Piano Project.sch"
    click Speaker "https://github.com/tsj-electronics/air-piano/blob/main/Air Piano Project.sch"
    click Power "https://github.com/tsj-electronics/air-piano/blob/main/Air Piano Project.sch"
    click USB "https://github.com/tsj-electronics/air-piano/blob/main/How to upload Code to Arduino.docx"
    click Mapper "https://github.com/tsj-electronics/air-piano/blob/main/Air_Piano_Code/Air_Piano_Code.ino"
    click Player "https://github.com/tsj-electronics/air-piano/blob/main/Air_Piano_Code/Air_Piano_Code.ino"
    click README "https://github.com/tsj-electronics/air-piano/blob/main/README.md"

    %% Legend
    subgraph Legend
        direction TB
        I["Input (Green)"]:::input
        P["Processing (Blue)"]:::processing
        O["Output (Orange)"]:::output
        U["Interface (Gray)"]:::interface
        V["Power (Gray)"]:::power
    end

    %% Styles
    classDef input fill:#9f6,stroke:#393,stroke-width:2px;
    classDef processing fill:#6cf,stroke:#039,stroke-width:2px;
    classDef output fill:#fc6,stroke:#963,stroke-width:2px;
    classDef interface fill:#ccc,stroke:#888,stroke-width:2px;
    classDef power fill:#eee,stroke:#666,stroke-width:2px;
```
