Gumball machine on an Arduino Uno

// Gumball machine: one coin, one gumball. A microswitch under the coin slot
// counts coins, a servo swings a gate under the globe to let one gumball
// roll out, and an IR sensor in the chute watches for it to drop. If nothing
// comes out, the machine tries once more, and if the chute stays empty it
// keeps your coin as credit and calls for service instead of eating it.
//
//   coin switch   lever microswitch: NO -> pin 2, COM -> GND (INPUT_PULLUP)
//   drop sensor   FC-51 IR sensor across the chute: OUT -> pin 3, VCC, GND
//   service       pushbutton: pin 4 -> button -> GND (refills the globe)
//   piezo         pin 8 -> piezo -> GND
//   gate servo    PWM -> pin 9, VCC -> 5 V, GND -> GND
//   LCD           16x2 with an I2C backpack at 0x27: SDA A4, SCL A5
//
// HOW IT WORKS
//   The loop never waits. Each pass it reads the switches, then lets the
//   machine take one small step from the state it is in:
//
//     READY      waiting. A credit and a gumball in the globe open the gate.
//     DISPENSE   the gate is open. The drop sensor seeing a gumball means
//                success; DROP_MS without one means a miss.
//     RETRY      after a miss the gate shuts for a moment and tries again,
//                which shakes loose a gumball sitting on the gate's edge.
//     SETTLE     the gate is shut after a sale; wait a little before the
//                next one so two gumballs never roll out together.
//     FAULT      two misses in a row: jammed, or the globe is empty even
//                though the count says otherwise. The coin stays as credit
//                and the machine takes no more coins until it is serviced.
//
//   A coin only holds the switch down for a moment, and a gumball falls past
//   the sensor in a blink, but redrawing the LCD takes a good part of a
//   tenth of a second. So both quick events land on the Uno's two interrupt
//   pins, 2 and 3: the moment one happens a tiny function (an ISR) notes it,
//   and the loop deals with it when it comes round.
//
//   The coin switch also bounces: its contacts chatter for a few
//   milliseconds as they land and again as they let go. The coin ISR counts
//   the first touch and then ignores the switch until the loop has seen it
//   sit released for DEBOUNCE_MS, so one coin is always one count.
//
// HOW TO PLAY
//   Click the coin switch to drop a coin. The gate opens: drag the drop
//   sensor's slider close (a gumball falling past) and back to nothing.
//   Leave the slider alone to see the jam handling. Press SERVICE to refill.
//
// THINGS TO TRY
//   Make it cost two coins: change PRICE. Change FULL for a bigger globe.

#include <Wire.h>
#include <LiquidCrystal_I2C.h>
#include <Servo.h>

const int COIN_PIN = 2;
const int DROP_PIN = 3;
const int SERVICE_PIN = 4;
const int PIEZO_PIN = 8;
const int GATE_PIN = 9;

const int GATE_SHUT = 0;      // degrees: the gate blocks the globe
const int GATE_OPEN = 90;     // degrees: one gumball can roll through

const int FULL = 10;          // gumballs in a freshly filled globe
const int PRICE = 1;          // coins per gumball
const int MAX_TRIES = 2;      // how many times to try before calling it a jam

const unsigned long DEBOUNCE_MS = 25;
const unsigned long DROP_MS = 1500;   // how long a gumball may take to fall
const unsigned long RETRY_MS = 400;   // the gate shut between two tries
const unsigned long SETTLE_MS = 600;  // the gate shut after a sale

enum State { READY, DISPENSE, RETRY, SETTLE, FAULT };
State state = READY;
unsigned long stateAt = 0;    // when the machine entered its state

LiquidCrystal_I2C lcd(0x27, 16, 2);
Servo gate;

int stock = FULL;     // gumballs we think are in the globe
int coins = 0;        // every coin ever accepted
int paid = 0;         // coins toward the next gumball
int credits = 0;      // gumballs paid for and not yet given
int sold = 0;         // gumballs that really came out
int tries = 0;        // attempts at the gumball now being dispensed
bool screenDirty = true;

// Set by the interrupt handlers, read by the loop. `volatile` tells the
// compiler they can change behind the loop's back.
volatile uint8_t coinsWaiting = 0;   // coins the ISR caught, not yet handled
volatile bool coinArmed = true;      // false from a coin until the switch is let go
volatile unsigned long coinEdgeAt = 0;  // the last time pin 2 changed at all
volatile bool gumballSeen = false;   // the drop sensor saw something fall

void coinISR() {                     // pin 2 changed: pressed, released or bouncing
  coinEdgeAt = millis();
  if (coinArmed && digitalRead(COIN_PIN) == LOW) {
    coinArmed = false;               // ignore the bounces that follow
    coinsWaiting++;
  }
}

void dropISR() {                     // pin 3 went LOW: something broke the beam
  gumballSeen = true;
}

// The coin switch is armed again once it reads released (HIGH) and has
// not changed for DEBOUNCE_MS: the bounces are over.
void rearmCoin(unsigned long now) {
  noInterrupts();
  unsigned long quietFor = now - coinEdgeAt;
  interrupts();
  if (!coinArmed && digitalRead(COIN_PIN) == HIGH && quietFor >= DEBOUNCE_MS) {
    coinArmed = true;
  }
}

// The SERVICE button is slow and human, so plain polling with a debounce
// is enough: it returns true once, at the moment the press is believed.
bool serviceStable = false;
bool serviceRaw = false;
unsigned long serviceChangedAt = 0;
bool servicePressed(unsigned long now) {
  bool raw = digitalRead(SERVICE_PIN) == LOW;   // pulled up, so pressed reads LOW
  if (raw != serviceRaw) {
    serviceRaw = raw;
    serviceChangedAt = now;                     // it moved: start the clock again
  }
  if (raw != serviceStable && now - serviceChangedAt >= DEBOUNCE_MS) {
    serviceStable = raw;
    return raw;
  }
  return false;
}

bool chuteBlocked() {
  return digitalRead(DROP_PIN) == LOW;   // the FC-51 pulls OUT low while it sees something
}

void enter(State next, unsigned long now) {
  state = next;
  stateAt = now;
  screenDirty = true;
}

// The LCD is slow, so each line is built in memory first and only sent
// when it differs from what the screen already shows.
char shown[2][17] = {"", ""};

void putLine(int row, const char *text) {
  if (strcmp(shown[row], text) == 0) return;
  strcpy(shown[row], text);
  lcd.setCursor(0, row);
  lcd.print(text);
}

void showScreen() {
  char line[17];
  if (state == FAULT) {
    snprintf(line, sizeof line, "OUT OF ORDER    ");
  } else if (stock == 0) {
    snprintf(line, sizeof line, "SOLD OUT        ");
  } else {
    snprintf(line, sizeof line, "Gumballs: %-6d", stock);
  }
  putLine(0, line);
  snprintf(line, sizeof line, "Coins %-3d Cred %d", coins, credits);
  putLine(1, line);
  screenDirty = false;
}

void takeCoin() {
  if (state == FAULT || stock == 0) {
    // A real coin mech would drop it into the return cup.
    Serial.println("Coin returned: machine cannot sell");
    tone(PIEZO_PIN, 220, 200);
    return;
  }
  coins++;
  paid++;
  tone(PIEZO_PIN, 1320, 60);
  if (paid >= PRICE) {
    paid -= PRICE;
    credits++;
  }
  Serial.print("Coin ");
  Serial.print(coins);
  Serial.print(", credit ");
  Serial.println(credits);
  screenDirty = true;
}

void openGate(unsigned long now) {
  tries++;
  gumballSeen = false;               // only a gumball from now on counts
  gate.write(GATE_OPEN);
  Serial.print("Gate open, try ");
  Serial.println(tries);
  enter(DISPENSE, now);
}

void setup() {
  Serial.begin(9600);
  pinMode(COIN_PIN, INPUT_PULLUP);
  pinMode(SERVICE_PIN, INPUT_PULLUP);
  pinMode(DROP_PIN, INPUT);
  attachInterrupt(digitalPinToInterrupt(COIN_PIN), coinISR, CHANGE);
  attachInterrupt(digitalPinToInterrupt(DROP_PIN), dropISR, FALLING);
  gate.attach(GATE_PIN);
  gate.write(GATE_SHUT);
  lcd.init();
  lcd.backlight();
  Serial.println("Gumball machine ready: insert a coin");
  showScreen();
}

void loop() {
  unsigned long now = millis();

  // Collect the coins the interrupt caught. Interrupts are paused for the
  // two lines that read and clear the count, so a coin cannot slip between.
  noInterrupts();
  uint8_t newCoins = coinsWaiting;
  coinsWaiting = 0;
  interrupts();
  while (newCoins > 0) {
    takeCoin();
    newCoins--;
  }
  rearmCoin(now);

  if (servicePressed(now)) {
    stock = FULL;
    tries = 0;
    gate.write(GATE_SHUT);
    Serial.print("Serviced: globe refilled with ");
    Serial.println(stock);
    enter(READY, now);
  }

  switch (state) {
    case READY:
      if (credits > 0 && stock > 0) {
        tries = 0;
        openGate(now);
      }
      break;

    case DISPENSE:
      if (gumballSeen) {
        // Success: it fell past the sensor.
        gate.write(GATE_SHUT);
        credits--;
        stock--;
        sold++;
        tries = 0;
        tone(PIEZO_PIN, 1760, 120);
        Serial.print("Dispensed ");
        Serial.print(sold);
        Serial.print(", left ");
        Serial.println(stock);
        if (stock == 0) Serial.println("Sold out");
        enter(SETTLE, now);
      } else if (now - stateAt >= DROP_MS) {
        // Short dispense: the gate was open and nothing fell.
        gate.write(GATE_SHUT);
        if (tries < MAX_TRIES) {
          Serial.println("No gumball yet, trying again");
          enter(RETRY, now);
        } else {
          Serial.println("Jammed or empty: coin kept as credit, call service");
          tone(PIEZO_PIN, 180, 600);
          enter(FAULT, now);
        }
      }
      break;

    case RETRY:
      if (now - stateAt >= RETRY_MS) openGate(now);
      break;

    case SETTLE:
      // Wait for the gumball to clear the chute and the gate to shut.
      if (now - stateAt >= SETTLE_MS && !chuteBlocked()) enter(READY, now);
      break;

    case FAULT:
      // Nothing to do but wait for the service button (handled above).
      break;
  }

  if (screenDirty) showScreen();
}