Harmona

Harmona is a lightweight PlatformIO library for generating buzzer tones and simple melodies on the ESP32 using the hardware LEDC (PWM) peripheral.

The name Harmona is derived from harmony, reflecting its role as a small, structured sound helper. The library provides a minimal and expressive API for sound feedback patterns such as beeps, success tones, and error signals.

Overview

Harmona is designed to simplify common buzzer use cases on ESP32 projects by providing:

• A clean abstraction over ESP32’s LEDC tone generation
• Reusable sound patterns for UI and game feedback
• A predictable, blocking execution model suitable for small systems

The library intentionally remains minimal and does not attempt to be a full audio or music framework.

Features

• ESP32 LEDC-based tone generation
• Simple frequency control
• Blocking beep helper with optional off-delay
• Built-in sound patterns:
  • Start
  • Success
  • Failure
  • Victory
• Minimal API surface
• Designed for ESP32 + Arduino framework

Platform Support

• ESP32 only

This library relies on ESP32-specific LEDC functions and is not portable to AVR or other MCUs without modification.

Dependencies

• Arduino framework for ESP32

No external libraries are required.

Installation

PlatformIO (GitHub source)

Add the following to your platformio.ini:

lib_deps =
  https://github.com/tabah-mly/harmona.git

Local Library

Alternatively, place the library in your project’s lib directory:

lib/
└── harmona/
    ├── include/
    │   └── Oculun.h
    ├── src/
    │   └── Oculun.cpp

Basic Usage

Include and Initialize

#include <Harmona.h>

Harmona buzzer(19); // GPIO pin connected to buzzer

void setup() {
  buzzer.begin();
}

The constructor accepts the GPIO pin used for tone output. Internally, Harmona configures an LEDC channel with fixed frequency and resolution.

API Reference

tone

Plays a continuous tone at the specified frequency.

buzzer.tone(523);

Parameters

Name	Type	Description
freq	uint16_t	Frequency in Hz

off

Stops any currently playing tone.

buzzer.off();

beep

Plays a tone for a fixed duration, then optionally pauses.

buzzer.beep(784, 200, 50);

Parameters

Name	Type	Description
freq	uint16_t	Frequency in Hz
duration_on	uint16_t	Tone duration in ms (default: 200)
duration_off	uint16_t	Silent delay in ms (default: 0)

start

Plays a short ascending tone sequence intended for startup feedback.

buzzer.start();

success

Plays an ascending confirmation melody.

buzzer.success();

failed

Plays a descending error tone sequence.

buzzer.failed();

victory

Plays a longer celebratory tone sequence.

buzzer.victory();

Design Considerations

• Uses a fixed LEDC channel and resolution internally
• Sound patterns are intentionally short and simple
• Execution is blocking (uses delay)
• Frequency values are specified directly in Hertz
• Designed for UI feedback, not music playback

Project Status

Harmona is currently in beta. The API is stable for its current feature set, with planned extensions focused on flexibility rather than complexity.

Roadmap

Planned enhancements include:

• Configurable LEDC channel and resolution
• User-defined melody sequences
• Optional non-blocking playback
• Tempo-based note playback helpers
• Pattern customization hooks

License

This project is licensed under the MIT License.

Author

Tabah Mulya

GitHub: https://github.com/tabah-mly