Note: The GitHub repository is named pill-reminder for historical reasons. The project is called Nonna Pills.

Medical Disclaimer: This is NOT a medical device. Do not rely on this as the sole medication reminder system.

What It Does

1. Reminder Call - Calls at scheduled times with a voice message reminding them to take pills
2. Confirmation Call - 5 minutes later, calls to ask "Did you take your pills? Press 1 for yes, 2 for no"
3. Smart Retries - If no answer or "no", retries up to 3 times (5 min apart)
4. Family Alerts - After 3 failed attempts, calls a family member to check on them

Features

• Personal Voice Messages - Record your own voice (optional, falls back to TTS)
• Multiple Schedules - Morning, noon, evening (customizable)
• Google Sheets Logging - Track all calls, confirmations, and alerts
• Retry Logic - Persistent but not annoying
• Multi-language TTS - English, Spanish, and 20+ languages via AWS Polly

Cost Breakdown

Based on real usage data (December 2025):

Service	Monthly Cost
Twilio Voice	~$5-7/month
GCP (Cloud Functions, Scheduler, Tasks)	~$0.30/month (free tier covers most)
Total	~$5-7/month

Twilio Cost Details

• Phone number: $1.15/month
• Outbound calls (Peru): ~$0.12/min
• ~60 calls/month (2 daily x 30 days) = ~$3-5 in call charges
• Retries add ~$1-2 depending on answer rate

GCP Free Tier

• Cloud Functions: 2M invocations/month free
• Cloud Scheduler: 3 jobs free
• Cloud Tasks: 1M operations/month free
• Storage: 5GB free

Architecture

                    CLOUD SCHEDULER
                          |
                    [8:30 AM trigger]
                          |
                          v
              +-------------------+
              | make-reminder-call|  <-- Plays audio/TTS reminder
              +-------------------+
                          |
                    [5 min delay]
                          |
                          v
           +------------------------+
           | make-confirmation-call |  <-- "Press 1=yes, 2=no"
           +------------------------+
                    |         |
              [Press 1]   [Press 2 / No answer]
                    |         |
                    v         v
              +--------+  +---------------+
              | Thanks |  | CLOUD TASKS   |
              | (done) |  | schedule retry|
              +--------+  +---------------+
                                |
                          [After 3 retries]
                                |
                                v
                         +------------+
                         | call_alert |  <-- Calls family member
                         +------------+

Quick Start

Prerequisites

• Google Cloud account with billing enabled
• Twilio account ($20 minimum to buy phone number)
• Python 3.11+
• gcloud CLI installed

1. Clone and Configure

git clone https://github.com/JDRV-space/pill-reminder.git
cd pill-reminder

# Copy example env file
cp .env.example .env

# Edit with your values
nano .env

2. Set Up Twilio

1. Create account at twilio.com
2. Buy a phone number (~$1.15/month)
3. Copy Account SID and Auth Token to .env

See docs/TWILIO_SETUP.md for detailed instructions.

3. Set Up Google Cloud

1. Create new project in GCP Console
2. Enable required APIs
3. Create service account for Sheets access

See docs/GCP_SETUP.md for detailed instructions.

4. Record Audio (Optional)

Record personal voice messages for a warmer experience:

cd audios/
# Record these files:
# - reminder_morning.mp3
# - reminder_noon.mp3
# - confirmation_morning.mp3
# - thanks_morning.mp3
# etc.

See audios/README.md for recording scripts.

5. Deploy

# Load environment variables
source .env

# Make deploy script executable
chmod +x deploy.sh

# Deploy everything
./deploy.sh

6. Test

# Test reminder call to yourself
curl "https://$GCP_REGION-$GCP_PROJECT_ID.cloudfunctions.net/make-reminder-call?schedule=morning&target=test"

Customization

Change Medication Names

Edit SCHEDULES in functions/main.py:

SCHEDULES = {
    'morning': {
        'time': '8:30 AM',
        'pills': 'Aspirin, Metformin, and vitamin D',  # Your medications
        ...
    },
}

Change Schedule Times

Edit the cron expressions in deploy.sh:

# Change morning time to 9:00 AM
--schedule="0 9 * * *"

Change Language

Set TTS language in .env:

# Spanish
TTS_VOICE=Polly.Mia
TTS_LANGUAGE=es-419

# Portuguese
TTS_VOICE=Polly.Camila
TTS_LANGUAGE=pt-BR

Add More Schedules

1. Add new entry to SCHEDULES dict in main.py
2. Add new Cloud Scheduler jobs in deploy.sh

Troubleshooting

Calls Not Going Through

1. Check Twilio console for call logs
2. Verify phone numbers are in E.164 format (+1234567890)
3. Check Cloud Functions logs:

   gcloud functions logs read make-reminder-call --region=us-central1

Audio Not Playing

1. Verify bucket is public: gsutil iam ch allUsers:objectViewer gs://YOUR_BUCKET
2. Check audio URL is accessible in browser
3. Check file format (MP3 works best)

Retries Not Working

1. Verify Cloud Tasks queue exists
2. Check service account has cloudtasks.tasks.create permission
3. Check FUNCTION_BASE_URL is set correctly

Project Structure

pill-reminder/
├── functions/
│   ├── main.py           # Cloud Function handlers
│   ├── requirements.txt  # Python dependencies
│   └── setup_sheet.py    # Google Sheets setup script
├── audios/
│   ├── .gitkeep
│   └── README.md         # Recording instructions
├── docs/
│   ├── SETUP.md          # Full setup guide
│   ├── TWILIO_SETUP.md   # Twilio account setup
│   ├── GCP_SETUP.md      # GCP project setup
│   └── COST_BREAKDOWN.md # Detailed cost analysis
├── .env.example          # Environment template
├── .gitignore
├── deploy.sh             # Deployment script
├── LICENSE
└── README.md

License

MIT License - see LICENSE

Acknowledgments

Built with love for family members who need medication reminders.

---

Questions? Open an issue or reach out on Twitter @JDRV-space