Practical case: relay timer on Arduino UNO

/*
  workshop_countdown_relay_timer.ino

  Device model:
  Arduino UNO R3 (ATmega328P) + pushbuttons + 1-channel relay module + piezo buzzer

  Project goal:
  workshop-countdown-relay-timer

  Behavior:
  - ADD button: increase preset time by 1 minute (1..60, wrap around)
  - START/PAUSE button:
      * if idle -> start countdown
      * if running -> pause
      * if paused -> resume
  - CANCEL/RESET button:
      * stop countdown
      * relay off
      * restore remaining time to preset
  - Relay is active while countdown is running
  - Buzzer gives short feedback on actions and a completion pattern at the end

  Notes:
  - Buttons use INPUT_PULLUP, so pressed = LOW
  - Relay modules are often active-low; set RELAY_ACTIVE_LOW accordingly
*/

const byte PIN_BTN_ADD = 2;
const byte PIN_BTN_START = 3;
const byte PIN_BTN_CANCEL = 4;
const byte PIN_RELAY = 8;
const byte PIN_BUZZER = 9;

const bool RELAY_ACTIVE_LOW = true;

const unsigned long DEBOUNCE_MS = 35;
const unsigned long STATUS_PRINT_MS = 1000;
const unsigned long MINUTES_MAX = 60;
const unsigned long DEFAULT_PRESET_MIN = 5;

enum TimerState {
  IDLE,
  RUNNING,
  PAUSED,
  FINISHED
};

TimerState timerState = IDLE;

unsigned long presetMinutes = DEFAULT_PRESET_MIN;
unsigned long remainingMs = DEFAULT_PRESET_MIN * 60UL * 1000UL;
unsigned long lastTickMs = 0;
unsigned long lastStatusPrintMs = 0;

struct Button {
  byte pin;
  bool stableState;
  bool lastReading;
  unsigned long lastChangeMs;
};

Button btnAdd    = {PIN_BTN_ADD, HIGH, HIGH, 0};
Button btnStart  = {PIN_BTN_START, HIGH, HIGH, 0};
Button btnCancel = {PIN_BTN_CANCEL, HIGH, HIGH, 0};

void setRelay(bool on) {
  if (RELAY_ACTIVE_LOW) {
    digitalWrite(PIN_RELAY, on ? LOW : HIGH);
  } else {
    digitalWrite(PIN_RELAY, on ? HIGH : LOW);
  }
}

void beep(unsigned int frequency, unsigned long durationMs) {
  tone(PIN_BUZZER, frequency, durationMs);
}

void shortBeep() {
  beep(2200, 70);
}

void doubleBeep() {
  beep(2000, 60);
  delay(100);
  beep(2600, 80);
}

void finishBeepPattern() {
  for (int i = 0; i < 3; i++) {
    beep(1800, 120);
    delay(180);
  }
  beep(2600, 350);
  delay(400);
}

bool buttonPressedEvent(Button &button) {
  bool reading = digitalRead(button.pin);

  if (reading != button.lastReading) {
    button.lastChangeMs = millis();
    button.lastReading = reading;
  }

  if ((millis() - button.lastChangeMs) > DEBOUNCE_MS) {
    if (reading != button.stableState) {
      button.stableState = reading;

      // Because INPUT_PULLUP is used, LOW means pressed
      if (button.stableState == LOW) {
        return true;
      }
    }
  }

  return false;
}

void printHelp() {
  Serial.println(F("Workshop Countdown Relay Timer"));
  Serial.println(F("Buttons:"));
  Serial.println(F("  ADD         -> +1 minute preset (1..60)"));
  Serial.println(F("  START/PAUSE -> start, pause, resume"));
  Serial.println(F("  CANCEL      -> stop and reset to preset"));
  Serial.println();
}

void printStateLine() {
  unsigned long totalSeconds = remainingMs / 1000UL;
  unsigned int minutesPart = totalSeconds / 60UL;
  unsigned int secondsPart = totalSeconds % 60UL;

  Serial.print(F("Preset="));
  Serial.print(presetMinutes);
  Serial.print(F(" min, Remaining="));
  if (minutesPart < 10) Serial.print('0');
  Serial.print(minutesPart);
  Serial.print(':');
  if (secondsPart < 10) Serial.print('0');
  Serial.print(secondsPart);
  Serial.print(F(", State="));

  switch (timerState) {
    case IDLE: Serial.print(F("IDLE")); break;
    case RUNNING: Serial.print(F("RUNNING")); break;
    case PAUSED: Serial.print(F("PAUSED")); break;
    case FINISHED: Serial.print(F("FINISHED")); break;
  }

  Serial.print(F(", Relay="));
  Serial.println((timerState == RUNNING) ? F("ON") : F("OFF"));
}

void resetToPreset() {
  remainingMs = presetMinutes * 60UL * 1000UL;
  lastTickMs = millis();
}

void handleAddButton() {
  // For simplicity in a basic project, allow preset changes only when not running
  if (timerState == RUNNING) {
    doubleBeep();
    Serial.println(F("ADD ignored while running. Pause or cancel first."));
    return;
  }

  presetMinutes++;
  if (presetMinutes > MINUTES_MAX) {
    presetMinutes = 1;
  }

  resetToPreset();

  if (timerState == FINISHED) {
    timerState = IDLE;
  }

  shortBeep();
  Serial.print(F("Preset changed to "));
  Serial.print(presetMinutes);
  Serial.println(F(" minute(s)."));
  printStateLine();
}

void handleStartButton() {
  if (timerState == IDLE || timerState == FINISHED) {
    resetToPreset();
    timerState = RUNNING;
    setRelay(true);
    lastTickMs = millis();
    shortBeep();
    Serial.println(F("Countdown started."));
    printStateLine();
    return;
  }

  if (timerState == RUNNING) {
    timerState = PAUSED;
    setRelay(false);
    shortBeep();
    Serial.println(F("Countdown paused."));
    printStateLine();
    return;
  }

  if (timerState == PAUSED) {
    timerState = RUNNING;
    setRelay(true);
    lastTickMs = millis();
    shortBeep();
    Serial.println(F("Countdown resumed."));
    printStateLine();
    return;
  }
}

void handleCancelButton() {
  timerState = IDLE;
  setRelay(false);
  resetToPreset();
  doubleBeep();
  Serial.println(F("Countdown canceled and reset to preset."));
  printStateLine();
}

void updateTimer() {
  if (timerState != RUNNING) {
    return;
  }

  unsigned long now = millis();
  unsigned long elapsed = now - lastTickMs;
  lastTickMs = now;

  if (elapsed >= remainingMs) {
    remainingMs = 0;
    timerState = FINISHED;
    setRelay(false);
    Serial.println(F("Countdown complete. Relay turned OFF."));
    printStateLine();
    finishBeepPattern();
    return;
  }

  remainingMs -= elapsed;
}

void setup() {
  pinMode(PIN_BTN_ADD, INPUT_PULLUP);
  pinMode(PIN_BTN_START, INPUT_PULLUP);
  pinMode(PIN_BTN_CANCEL, INPUT_PULLUP);

  pinMode(PIN_RELAY, OUTPUT);
  pinMode(PIN_BUZZER, OUTPUT);

  setRelay(false);

  Serial.begin(9600);
  delay(300);

  printHelp();
  resetToPreset();
  printStateLine();
}

void loop() {
  if (buttonPressedEvent(btnAdd)) {
    handleAddButton();
  }

  if (buttonPressedEvent(btnStart)) {
    handleStartButton();
  }

  if (buttonPressedEvent(btnCancel)) {
    handleCancelButton();
  }

  updateTimer();

  unsigned long now = millis();
  if (now - lastStatusPrintMs >= STATUS_PRINT_MS) {
    lastStatusPrintMs = now;
    printStateLine();
  }
}