esp32-common

Reusable ESP32 utility library for PlatformIO and Arduino.

esp32-common is intended to be the low-level shared base for other projects. It now depends only on libraries provided by the Arduino ESP32 core and ESP-IDF integration used by PlatformIO.

Tested with:

• esp32dev
• esp32-s3-devkitc-1

What It Includes

• Common Logging macros, fast GPIO helpers, pin setup helpers, time helpers, and small parse/string helpers.
• Task Minimal wrapper for FreeRTOS tasks pinned to a chosen core or tskNO_AFFINITY.
• PWM Thin wrapper around the official Arduino-ESP32 LEDC API.
• Beeper Small beeper helper built on PWM.
• Alerter Simple alert task for blinking an LED and/or toggling a beeper pin.
• EEPROMKV Lightweight key/value storage on top of EEPROM, without external JSON dependency.
• Utils Small utility helpers such as get_cpu_mhz().

Install

From Git:

lib_deps =
  https://github.com/gr82morozr/esp32-common.git

From a local checkout:

lib_deps =
  file://../esp32-common

Include

Use the umbrella header:

#include <esp32-common.h>

Or include only the modules you need:

#include <Common/Common.h>
#include <Task/Task.h>
#include <PWM/ESP32PWM.h>
#include <Beeper/Beeper.h>
#include <Alerter/Alerter.h>
#include <Utils/eepromkv.h>
#include <Utils/utils.h>

Defaults You Can Override

Set these in your app build_flags if your board uses different pins or serial speed:

build_flags =
  -DESP32_COMMON_DEFAULT_LED_PIN=5
  -DESP32_COMMON_DEFAULT_BEEPER_PIN=17
  -DESP32_COMMON_ALERT_DEFAULT_LED_PIN=16
  -DESP32_COMMON_ALERT_DEFAULT_BEEPER_PIN=17
  -DESP32_COMMON_SERIAL_BAUD=921600

You can also override PWM defaults:

build_flags =
  -DESP32_COMMON_PWM_DEFAULT_FREQUENCY=5000
  -DESP32_COMMON_PWM_DEFAULT_RESOLUTION_BITS=8
  -DESP32_COMMON_PWM_DEFAULT_DUTY_CYCLE=0.25f
  -DESP32_COMMON_BEEPER_TONE_DUTY_CYCLE=0.5f

Basic Usage

Common

#include <esp32-common.h>

unsigned long last_log_ms = 0;

void setup() {
  common_init();
  setPinOutput(ESP32_COMMON_DEFAULT_LED_PIN, false);
  LOG_INFO("cpu_mhz=%d", get_cpu_mhz());
}

void loop() {
  toggleGPIO(ESP32_COMMON_DEFAULT_LED_PIN);
  if (every_ms(last_log_ms, 2000)) {
    LOG_INFO("still alive");
  }
  delay(500);
}

For the fastest GPIO hot path, configure once and then use the GPIO helpers directly:

void setup() {
  prepareGPIOOutput(ESP32_COMMON_DEFAULT_LED_PIN);
}

void loop() {
  toggleGPIO(ESP32_COMMON_DEFAULT_LED_PIN);
}

Task

class BlinkTask : public Task {
public:
  BlinkTask() : Task("BlinkTask", 4096, 1) {}

  void run(void* data) override {
    while (true) {
      toggleGPIO(ESP32_COMMON_DEFAULT_LED_PIN);
      Task::delay(250);
    }
  }
};

PWM

ESP32PWM pwm(ESP32_COMMON_DEFAULT_LED_PIN, 5000, 8, 0.5f);

void setup() {
  pwm.init();
  pwm.setDutyPercent(50.0f);
}

Beeper

Beeper beeper(ESP32_COMMON_DEFAULT_BEEPER_PIN);

void setup() {
  beeper.init();
  beeper.toneReady();
  beeper.beep(1200, 0.05f);
}

Alerter

Alerter alerter(ESP32_COMMON_ALERT_DEFAULT_LED_PIN, -1, ALERT_TYPE_LED);

void setup() {
  alerter.setPattern(100, 400);
  alerter.start();
}

EEPROMKV

void setup() {
  common_init();
  const int count = EEPROMKV.readInt("boot_count", 0) + 1;
  EEPROMKV.writeInt("boot_count", count);
  EEPROMKV.writeBool("configured", true);
}

Examples

Each example is a standalone PlatformIO project with esp32dev and esp32-s3-devkitc-1 environments.

• examples/common_basic Logging, CPU utility, and GPIO helper usage.
• examples/task_basic Running a simple FreeRTOS task using the Task wrapper.
• examples/pwm_basic LEDC PWM output with ESP32PWM.
• examples/beeper_basic Simple beeper patterns with Beeper.
• examples/alerter_basic Background alert blinking with Alerter.
• examples/eepromkv_basic Persistent key/value storage with EEPROMKV.

Build an example with:

cd examples/eepromkv_basic
pio run -e esp32dev

Or:

cd examples/eepromkv_basic
pio run -e esp32-s3-devkitc-1

Notes

• common_init() initializes Serial only if it has not already been started.
• Common now includes overflow-safe elapsed_ms, is_timeout, and every_ms helpers, plus simple pin setup helpers.
• Common includes prepareGPIOOutput, writeGPIO, toggleGPIO, and readGPIO as direct-register GPIO helpers. Configure output once before tight write/toggle loops.
• Task defaults to tskNO_AFFINITY.
• Task now exposes startOnce, restart, and basic getters for name/core/priority/stack.
• EEPROMKV stores escaped key=value records in EEPROM, and now includes typed read/write helpers plus exists and remove.
• ESP32PWM now includes setDutyPercent, getDutyCycle, and getFrequency.
• esp32-common no longer depends on the old custom esp32-pwm library.