Arduino Beat Detection LED Controller

Guidance for working with an Arduino Nano project that detects audio beats in real-time and creates synchronized LED visualizations using the AvrFHT (Fast Hartley Transform) library.

Project Architecture

This is an embedded AVR system that:

1. Samples audio from a MAX9814 AGC microphone at analog pin A0

2. Performs Fast Hartley Transform (FHT) analysis on 128-sample frames

3. Detects beats by analyzing bass (2-8 Hz bins) and mid-range (8-16 Hz bins) frequencies

4. Drives LED string lights on PWM pin 9 with intensity-scaled responses

5. Provides manual controls via two buttons and one potentiometer

Hardware Configuration

Dependencies

The project requires the **AvrFHT** library with these headers:

Install via Arduino IDE Library Manager or manually.

Development Workflow

Building and Uploading

```bash

Compile the sketch

arduino-cli compile --fqbn arduino:avr:nano glitch_v2_beats_avr

Upload to Arduino Nano (adjust port as needed)

arduino-cli upload -p /dev/ttyUSB0 --fqbn arduino:avr:nano glitch_v2_beats_avr

Monitor serial output (115200 baud)

arduino-cli monitor -p /dev/ttyUSB0 -c baudrate=115200

```

Using Arduino IDE

Open `glitch_v2_beats_avr.ino` directly in Arduino IDE. Ensure AvrFHT library is installed first.

System Operation

The main loop performs these steps sequentially:

1. **Audio Sampling** (`readAudioSamples()`)

- Reads 128 samples from MAX9814 AGC microphone

- Dynamically centers signal to compensate for AGC output

- Scales samples for FHT processing

2. **FHT Processing** (`performFHT()`)

- Applies windowing function to reduce spectral leakage

- Reorders data for transform

- Executes Fast Hartley Transform

- Extracts linear magnitude output

3. **Frequency Analysis** (`processFrequencyData()`)

- Analyzes bass frequencies (bins 2-8)

- Analyzes mid-range frequencies (bins 8-16)

- Maintains rolling averages for stability

4. **Beat Detection** (`updateBeatProbability()`)

- Calculates beat probability using multiple factors:

- Signal change magnitude

- Magnitude change rate

- Frequency variance

- Recency weighting

- Measures beat intensity relative to threshold

- Enforces maximum BPM limit (200 BPM)

5. **Visual Effects**

- Scales LED brightness (120-255) based on beat intensity

- Adjusts flash duration (100-300ms) based on intensity

- Manages glitch patterns in both modes

Key Constants

User Controls Reference

Button 1 (Pin 6)

Button 2 (Pin 2)

- Press to cycle: 100% → 66% → 33% → 0% → 100%

- LED flashes indicate level:

- 3 flashes = 100% sensitivity

- 2 flashes = 66% sensitivity

- 1 flash = 33% sensitivity

- 0 flashes = 0% (beat response disabled)

- System pauses 1.5 seconds after change

Dual Button Hold (Button 1 + Button 2)

Potentiometer (Pin A7)

Feature Details

Dynamic Beat Response

Negative Glitches (Full Power Mode)

MAX9814 AGC Microphone Optimization

Debugging and Testing

- Raw microphone value

- Signal strength

- Frequency magnitudes (bass, mid-range)

- Frequency variances

- Beat probability score

- Current detection threshold

- Beat intensity, duration, brightness (on beat events)

Code Modification Guidelines

When modifying this code:

1. **Always read the main `.ino` file first** to understand current implementation

2. **Preserve the FHT pipeline**: sampling → windowing → reordering → transform → magnitude extraction

3. **Maintain timing constraints**: Audio sampling requires precise ADC configuration; changes may affect beat detection accuracy

4. **Test with serial monitor**: Enable debug output to verify changes don't break beat detection logic

5. **Respect AVR memory limits**: Arduino Nano has only 2KB RAM; avoid large allocations

6. **Keep button debouncing**: Current implementation uses simple delay-based debouncing; preserve this for reliable input

7. **Preserve AGC adaptation**: MAX9814 dynamic centering is critical for consistent operation

Common Tasks

Adjusting Beat Sensitivity Globally

Modify `beatProbabilityThreshold` constant (default 0.85). Lower values = more sensitive.

Changing LED Response Range

Adjust `map()` calls in beat detection code that scale intensity to brightness (120-255) and duration (100-300ms).

Adding New Modes

Follow existing mode pattern: check mode flags, implement mode-specific behavior in main loop, add mode toggle logic to dual-button handler.

Tuning Frequency Analysis

Modify bin ranges in `processFrequencyData()`. Current ranges: bass (2-8), mid (8-16). Bins represent ~38 Hz per bin at default ADC rate.