14. Interface and Application Programming

Header and Serial Protocol

The first comment documents the hardware and the communication rules. It lists the exact messages used by both sides, including SET_ALARM, PILL_TAKEN, TIME, ALARM_TRIGGERED, and PILL_CONFIRMED.

/*
  Pill Dispenser MJ — XIAO ESP32-C6 Firmware
  Week: Interface and Application Programming

  Hardware:
    - OLED SH1106 I2C: SDA=D0 (GPIO0), SCL=D1 (GPIO1)
    - RTC DS3231 mismo bus I2C
    - Servo D10
    - Buzzer pasivo D9
    - Botón D2 (confirmar pastilla tomada)

  Protocolo Serial (115200 baud):
    PC to XIAO ESP32-C6:  "SET_ALARM,HH:MM,SMTWRFS\n"   (días: 1=activo, posición = Dom,Lun,Mar,Mier,Jue,Vie,Sab)
    PC to XIAO ESP32-C6:  "PILL_TAKEN\n"
    XIAO ESP32-C6 to PC:  "TIME,HH:MM:SS\n"              (cada segundo)
    XIAO ESP32-C6 to PC:  "ALARM_TRIGGERED\n"            (cuando suena)
    XIAO ESP32-C6 to PC:  "PILL_CONFIRMED\n"             (cuando se presiona botón o llega PILL_TAKEN)
*/

Libraries, Pins, and State

This section imports the hardware libraries, defines the pins, creates the OLED, RTC, and servo objects, and stores the alarm information inside a struct with hour, minute, active days, and state flags.

#include <Wire.h>
#include <RTClib.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SH110X.h>
#include <XIAO ESP32-C6Servo.h>

// Pines 
#define PIN_SERVO   D10
#define PIN_BUZZER  D9
#define PIN_BOTON   D2

// OLED SH1106 
#define I2C_ADDR_OLED 0x3C
#define SCREEN_WIDTH  128
#define SCREEN_HEIGHT 64
Adafruit_SH1106G display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, -1);

// RTC 
RTC_DS3231 rtc;

// Servo 
Servo servo;

// Estado de la alarma
struct Alarma {
  int hora   = -1;
  int minuto = -1;
  bool dias[7] = {false}; // [Dom, Lun, Mar, Mier, Jue, Vie, Sab]
  bool activa = false;
} alarma;

bool alarmaDisparada  = false;  // está sonando ahora?
bool esperandoPastilla = false; // esperando confirmación?
unsigned long tiempoAlarma = 0; // cuándo empezó
unsigned long ultimaHora   = 0; // para enviar TIME cada segundo

Alarm, Servo, and Confirmation

The alarm functions play buzzer tones, move the servo to dispense, mark the system as waiting for confirmation, and send status messages back to Python. Confirmation stops the alarm and replies with PILL_CONFIRMED.

// Melodía de alarma 
                      
                      void tocarAlarma() {
  // Tres pitidos ascendentes
  tone(PIN_BUZZER, 523, 200); delay(250);
  tone(PIN_BUZZER, 659, 200); delay(250);
  tone(PIN_BUZZER, 784, 400); delay(500);
}

void detenerAlarma() {
  noTone(PIN_BUZZER);
  servo.write(0);
}

void activarDispensador() {
  servo.write(90);          // gira para dispensar
  tocarAlarma();
  alarmaDisparada    = true;
  esperandoPastilla  = true;
  tiempoAlarma       = millis();
  Serial.println("ALARM_TRIGGERED");
}

// Confirmar pastilla tomada
void confirmarPastilla() {
  detenerAlarma();
  alarmaDisparada   = false;
  esperandoPastilla = false;
  tone(PIN_BUZZER, 1047, 200); // pitido de confirmación (Do alto)
  delay(250);
  Serial.println("PILL_CONFIRMED");
}

// OLED

OLED Display

actualizarOLED() redraws the display with the current RTC time, the configured alarm, and either the date or the warning text telling the user to take the pill.

void actualizarOLED(DateTime& ahora) {
  display.clearDisplay();

  // Título
  display.setTextSize(1);
  display.setCursor(20, 0);
  display.println("CURRENT TIME");
  display.drawFastHLine(0, 10, 128, SH110X_WHITE);

  // Hora grande
  display.setTextSize(2);
  display.setCursor(15, 20);
  if (ahora.hour()   < 10) display.print('0');
  display.print(ahora.hour()); display.print(':');
  if (ahora.minute() < 10) display.print('0');
  display.print(ahora.minute()); display.print(':');
  if (ahora.second() < 10) display.print('0');
  display.print(ahora.second());

  // Alarma configurada
  display.setTextSize(1);
  display.setCursor(0, 44);
  if (alarma.hora >= 0) {
    display.print("Alarm: ");
    if (alarma.hora   < 10) display.print('0');
    display.print(alarma.hora); display.print(':');
    if (alarma.minuto < 10) display.print('0');
    display.print(alarma.minuto);
  } else {
    display.print("No alarm set");
  }

  // Estado
  display.setCursor(0, 54);
  if (esperandoPastilla) {
    display.print(">> TAKE PILL! <<");
  } else {
    // Fecha
    display.print(ahora.day()); display.print('/');
    display.print(ahora.month()); display.print('/');
    display.print(ahora.year());
  }

  display.display();
}

// Parsear comando SET_ALARM 
// Formato: "SET_ALARM,08:30,1011010"
//           días = Dom Lun Mar Mier Jue Vie Sab  (7 chars, '1'=activo)

Parsing SET_ALARM

parsearAlarma() receives a command like SET_ALARM,08:30,1011010. It extracts the hour, minute, and seven day bits, saves them in the alarm struct, activates the alarm, and sends ALARM_SET_OK.

void parsearAlarma(String cmd) {
  // Extraer hora
  int c1 = cmd.indexOf(',');
  int c2 = cmd.indexOf(',', c1 + 1);
  if (c1 < 0 || c2 < 0) return;

  String horaStr = cmd.substring(c1 + 1, c2);  // "08:30"
  String diasStr = cmd.substring(c2 + 1);       // "1011010"
  diasStr.trim();

  int col = horaStr.indexOf(':');
  if (col < 0) return;
  alarma.hora   = horaStr.substring(0, col).toInt();
  alarma.minuto = horaStr.substring(col + 1).toInt();

  for (int i = 0; i < 7 && i < (int)diasStr.length(); i++) {
    alarma.dias[i] = (diasStr[i] == '1');
  }
  alarma.activa = true;
  Serial.println("ALARM_SET_OK");
}

// Verificar si toca la alarma
// dayOfWeek(): 0=Dom, 1=Lun … 6=Sab  (igual que el array)

Checking Time and Serial Commands

verificarAlarma() compares the RTC time with the stored alarm and only triggers at second zero. leerSerial() receives commands from Python and routes them to either alarm parsing or pill confirmation.

void verificarAlarma(DateTime& ahora) {
  if (!alarma.activa || alarmaDisparada) return;
  if (ahora.hour() != alarma.hora || ahora.minute() != alarma.minuto) return;
  if (ahora.second() != 0) return;  // solo dispara al segundo 0

  int dow = ahora.dayOfTheWeek(); // 0=Dom … 6=Sab
  if (alarma.dias[dow]) {
    activarDispensador();
  }
}

// Leer Serial de la PC 
void leerSerial() {
  if (!Serial.available()) return;
  String cmd = Serial.readStringUntil('\n');
  cmd.trim();

  if (cmd.startsWith("SET_ALARM")) {
    parsearAlarma(cmd);
  } else if (cmd == "PILL_TAKEN") {
    if (esperandoPastilla) confirmarPastilla();
  }
}

Setup

setup() starts Serial, initializes I2C on GPIO0 and GPIO1, starts the OLED and RTC, adjusts the RTC if it lost power, attaches the servo, configures the buzzer and button, and prints READY when the board is prepared.

void setup() {
  Serial.begin(115200);

  // I2C
  Wire.begin(0, 1);  // SDA=GPIO0, SCL=GPIO1
  Wire.setClock(100000);

  // OLED
  display.begin(I2C_ADDR_OLED, true);
  display.clearDisplay();
  display.setTextColor(SH110X_WHITE);
  display.display();

  // RTC
  if (!rtc.begin()) {
    display.setCursor(0, 0);
    display.println("RTC ERROR");
    display.display();
    while (1);
  }
  if (rtc.lostPower()) {
    rtc.adjust(DateTime(F(__DATE__), F(__TIME__)));
  }

  // Servo
  servo.attach(PIN_SERVO);
  servo.write(0);

  // Buzzer y Botón
  pinMode(PIN_BUZZER, OUTPUT);
  pinMode(PIN_BOTON, INPUT_PULLUP);

  Serial.println("READY");
}

// 

Main Loop

loop() reads Serial, checks the physical button, updates the OLED once per second, sends the current time to Python, checks the alarm, stops it after 60 seconds if nobody confirms, and repeats the reminder tone every five seconds.

void loop() {
  leerSerial();

  // Botón físico: confirmar pastilla
  if (digitalRead(PIN_BOTON) == LOW) {
    delay(50);
    if (digitalRead(PIN_BOTON) == LOW && esperandoPastilla) {
      confirmarPastilla();
      delay(500);
    }
  }

  // Actualizar OLED y verificar alarma cada segundo
  if (millis() - ultimaHora >= 1000) {
    ultimaHora = millis();
    DateTime ahora = rtc.now();
    actualizarOLED(ahora);
    verificarAlarma(ahora);

    // Enviar hora a la PC
    char buf[20];
    snprintf(buf, sizeof(buf), "TIME,%02d:%02d:%02d",
             ahora.hour(), ahora.minute(), ahora.second());
    Serial.println(buf);
  }

  // Si lleva más de 60 segundos sonando y nadie confirmó se apaga solo
  if (alarmaDisparada && millis() - tiempoAlarma > 60000) {
    confirmarPastilla();
  }

  // Repetir pitido cada 5s mientras espera confirmación
  if (esperandoPastilla && millis() - tiempoAlarma > 5000) {
    tiempoAlarma = millis();
    tocarAlarma();
  }
}

Arduino IDE Setup

Select the XIAO ESP32-C6 board, choose the correct COM port, and install the libraries used in the firmware: RTClib, Adafruit SH110X, Adafruit GFX, and XIAO ESP32-C6Servo.

COM Port Rule

The COM port can only be used by one program at a time. Before uploading from Arduino IDE, I close the Python app or disconnect it so the uploader can access the board.

Step 1: Upload Firmware

Upload pastillero_XIAO ESP32-C6.ino to the XIAO ESP32-C6. The firmware starts Serial at 115200 baud and prints READY when setup finishes.

Step 2: Run Python

Run the backend file. The app loads the generated UI, scans available ports, and waits for the user to connect.

python backend.py

Step 3: Send Alarm

Select a port, connect, choose the alarm time and days, then press the Set Alarm button. Python sends SET_ALARM,HH:MM,DDDDDDD to the XIAO ESP32-C6.

Step 4: Confirm Pill

When the alarm triggers, the XIAO ESP32-C6 sends ALARM_TRIGGERED. The user can confirm with the app button, which sends PILL_TAKEN, or with the physical button on D2.

Final Result

Here is a video of the final system in action: setting an alarm, waiting for it to trigger, and confirming the pill taken. The OLED shows the current time, the alarm time, and the warning message when the alarm is active.

Screen recording result

Here is a screen recording of the Python app showing the Serial messages received from the XIAO ESP32-C6, including the time updates, alarm trigger, and pill confirmation.