🛁 Kawaii Bath Assistant

A cute, AI-powered bathroom companion for the M5Stack Core 2. It greets you every morning with an animated kawaii face, a personalized weather-based briefing, and spoken advice — all running on a tiny ESP32 device.

✨ Features

• Animated Kawaii Face — Expressive eyes with realistic blinking, emotions (happy, excited, surprised, sleepy, thinking), and rosy cheeks
• AI Morning Briefing — Tap the screen or just make noise — get a personalized German morning briefing powered by any LLM via OpenRouter
• Text-to-Speech — Briefings are spoken aloud using OpenAI TTS (voice: nova)
• Live Weather — Real-time temperature, humidity, and conditions via Open-Meteo (free, no API key)
• Smart Wake/Sleep — Falls asleep after 2 minutes of inactivity; wakes on vibration (tap the shelf!) or sound (say "Guten Morgen!")
• Auto Brightness — Adjusts display brightness based on time of day (bright during day, dim at night)
• Status Bar — Clock, date, WiFi indicator, battery level with charging state
• Sleep Mode — Dark theme with floating Z animation and dim clock

🎯 Use Case

Mount it in your bathroom (a small shelf or suction cup mount works great). Every morning:

1. Walk in → vibration or sound wakes it up
2. It fetches weather + generates a briefing via AI
3. Shows and speaks: "Guten Morgen! Heute wird es 4 Grad bei Nieselregen — nimm den Regenschirm mit und zieh dich warm an. Du schaffst das!"
4. After 30 seconds (or a touch), it goes back to showing the kawaii face with weather

🔧 Hardware

Component	Details
Device	M5Stack Core 2 (ESP32, 320×240 IPS touch, speaker, IMU, microphone)
Power	USB-C (or battery — built-in 390mAh LiPo)
Mounting	Any small shelf, suction cup mount, or 3D-printed stand

Note: This runs on the device itself (MicroPython) — no external server or Raspberry Pi needed. Just WiFi and power.

🚀 Quick Start

1. Prerequisites

• M5Stack Core 2 with MicroPython/UIFlow2 firmware
• Python 3.x on your computer (for deployment)
• mpremote (pip install mpremote) or pyserial

2. Configure

cp config_example.json config.json

Edit config.json:

{
    "wifi_ssid": "YourWiFi",
    "wifi_password": "YourPassword",
    "openrouter_api_key": "sk-or-v1-...",
    "openrouter_model": "anthropic/claude-3.5-haiku",
    "lat": 53.87,
    "lon": 10.69,
    "language": "de",
    "timezone_offset": 1,
    "openai_api_key": "sk-...",
    "tts_voice": "nova"
}

Key	Required	Description
wifi_ssid	✅	Your WiFi network name
wifi_password	✅	WiFi password
openrouter_api_key	✅	OpenRouter API key for AI briefing
openrouter_model	❌	LLM model (default: anthropic/claude-3.5-haiku)
lat / lon	❌	Your location for weather (default: Lübeck, Germany)
timezone_offset	❌	Hours offset from UTC (default: 1 = CET)
openai_api_key	❌	OpenAI key for TTS (optional — works without, just no voice)
tts_voice	❌	OpenAI TTS voice: nova, alloy, shimmer, echo, fable, onyx

3. Upload to Device

Option A: mpremote (recommended)

./upload.sh /dev/ttyUSB0    # Linux
./upload.sh /dev/cu.usbserial-*  # macOS

Option B: deploy.py (with serial console output)

python deploy.py

⚠️ Edit the PORT and PROJECT_DIR variables in deploy.py to match your setup.

4. Done!

The device will:

1. Connect to WiFi
2. Sync time via NTP
3. Show the kawaii face with weather
4. Wait for interaction (touch, vibration, or sound)

🏗️ Architecture

boot.py       → WiFi + NTP setup
main.py       → Async event loop orchestrator
├── face.py   → Kawaii face rendering + blink animation
├── ui.py     → Screen states (IDLE/LOADING/BRIEFING/SLEEPING)
├── weather.py→ Open-Meteo weather fetcher
├── briefing.py → OpenRouter LLM briefing generator
├── sense.py  → IMU vibration + microphone wake detection
└── tts.py    → OpenAI text-to-speech playback

The system runs 8 concurrent async loops:

Loop	Frequency	Purpose
face_loop	10 FPS	Animate kawaii face (blink, emotions)
ui_loop	10 FPS	UI animations (loading dots, sleep Zs, progress bar)
clock_loop	1/sec	Update clock + battery
weather_loop	1/30min	Fetch weather from Open-Meteo
wifi_loop	1/30sec	Monitor WiFi connectivity
sensor_loop	~3/sec	IMU + microphone wake detection
touch_loop	10/sec	Touch event handling
brightness_loop	1/5min	Auto-adjust display brightness

🎨 Screen States

State	Description
IDLE	Kawaii face + weather flanks + "Touch für Morning Briefing"
LOADING	Thinking face + animated dots
BRIEFING	Mini face + word-wrapped text + progress bar + TTS playback
SLEEPING	Dark theme + sleepy face + floating Zs + dim clock

🌡️ Weather Codes

Weather descriptions are in German, powered by Open-Meteo's free API (no key needed). Supports all WMO weather codes from clear sky to thunderstorms.

🔊 Sensor Wake

The assistant wakes from sleep on:

• Vibration — Tap the shelf or surface (IMU accelerometer, threshold: 0.35g deviation)
• Sound — Clap, speak, or make noise (microphone, threshold: amplitude > 20000)
• Touch — Tap the screen directly

Cooldown: 5 seconds between triggers to avoid false positives.

💡 Tips

• No TTS? Works fine without an OpenAI key — you just won't get spoken briefings
• Different LLM? Change openrouter_model in config — any OpenRouter model works
• Adjust sensitivity: Edit VIBRATION_THRESHOLD and SOUND_THRESHOLD in sense.py
• Sleep timeout: Default 2 minutes — change sleep_timeout in main.py (milliseconds)
• DST: Manually update timezone_offset (1 for CET, 2 for CEST) — no auto-DST on ESP32

📝 License

MIT — do whatever you want with it.

🙏 Acknowledgments

• M5Stack for the excellent Core 2 hardware
• Open-Meteo for free weather data
• OpenRouter for unified LLM access
• OpenAI for TTS

---

Built with 🩷 and MicroPython