PillPal: Smart Offline Medicine Reminder

PillPal is a microcontroller-based medicine reminder system built using ESP32, designed to explore real-time scheduling, embedded state management, and persistent data logging. While functionally similar to a basic phone alarm, this project focuses on implementing time-critical logic from scratch using an RTC module, handling concurrent events (display updates, alarms, user input), and maintaining logs via SD storage. It serves as a hands-on demonstration of building a fully offline, self-contained reminder system with hardware-level control.

---

🚀 Features

• Fully Offline Operation — no Wi-Fi or cloud dependency
• RTC-Based Accurate Scheduling using DS3231 (handles real-world time reliably)
• Configurable Medicine Times via SD Card — update schedules without reflashing firmware
• Persistent Logging — periodic logs stored on SD card for tracking usage/history
• Non-Blocking Alarm System — buzzer runs alongside display + input without freezing the system
• Auto Alarm Timeout — stops automatically after inactivity to prevent continuous buzzing
• Scalable Medicine Entries — supports large lists (limited by memory and UI constraints)
• Simple Embedded UI — real-time display of current time and upcoming medicine

⚠️ Limitations

• No Snooze Functionality — alarms must be acknowledged or will auto-timeout
• Static Allocation (lenMeds) — number of medicines is fixed at compile time
• Limited Display Real Estate — small OLED restricts how many entries are visible at once
• Basic Input System — single touch/button limits interaction complexity
• String-Based Time Parsing — relies on strict formatting (e.g., HH:MM:SSAM/PM)
• Some parts are AI generated — String parsing portion is generated by AI

---

⚙️ How It Works

• The DS3231 RTC provides accurate real-time data to the ESP32
• Medicine schedules are loaded from times.txt on the SD card at startup
• Each loop cycle:
  • Current time is compared against scheduled medicine times
  • Matching entries trigger an alarm (buzzer + UI highlight)
• User input (button/touch) marks a medicine as taken
• System state (taken, alarms) is periodically logged to logs.txt

---

Circuit Diagram

Note: DS3231 RTC module is not included in the image due to platform limitations, but is used in the actual hardware implementation.

Component	ESP32 Pin
OLED (SDA)	GPIO 21
OLED (SCL)	GPIO 22
DS3231 (SDA)	GPIO 21
DS3231 (SCL)	GPIO 22
SD Card (MOSI/DI)	GPIO 23
SD Card (MISO/DO)	GPIO 19
SD Card (SCK)	GPIO 18
SD Card (CS)	GPIO 5
Touch Sensor / Button	GPIO 34
Buzzer	GPIO 13
VCC	3.3V
GND	GND

---

BoM (Bill of Materials)

Part Name	Part Image
ESP32 Microcontroller
DS3231 RTC Module
SSD1306 0.96" OLED Display Module
Micro SD Card Module + SD Card
Push Button
Buzzer

---

📦 Dependencies / Libraries

This project uses the following libraries:

• Adafruit GFX
• Adafruit SSD1306
• Bonezegei DS3231
• SD (built-in ESP32 library)
• SPI (built-in)
• Wire (I2C, built-in)

Install via Arduino Library Manager or clone into your libraries/ folder.

---

🛠️ Setup

1. Preparing the ESP32

1. Gather all required components (refer to the BoM)
2. Assemble the circuit according to the wiring diagram
3. Install required libraries (see Dependencies section)
4. Set the current time:
   • Temporarily uncomment the RTC setTime() function in the code
   • Upload once to sync time, then comment it back
5. Make required adjustments to `meds` object and update `lenMeds` with the total number of medicines
6. Upload pillpal.ino to your ESP32 (this time with synced time)

2. Preparing the SD Card

1. Format the SD card to FAT32
2. Create two files in the root directory:
   • times.txt
   • logs.txt
3. Add medicine times in times.txt using the format:
   HH:MM:SSAM/PM (one entry per line)
4. Example times.txt:
   
5. Leave logs.txt empty — it will be populated automatically
6. SD Card structure:
   / (SD card root)
├── logs.txt
└── times.txt