An ESP32-S3 desk assistant with AI, Telegram bot, Web-UI, habit tracking and more.
Built with passion, too much coffee and Claude Pro.
AssistantHub Pro turns an ESP32-S3 microcontroller into a smart desk assistant. It runs 24/7, automatically prioritizes your tasks, answers questions via AI and can be controlled via Telegram as well as a browser-based Web-UI — all running locally on the chip, no server required.(Disclaimer: The whole Code is commented in german and the commands are on german too, if it bothers you: feel free to change it to whatever language you like!)
┌─────────────────────────────────────────────────────────────┐
│ AssistantHub Pro │
│ │
│ 📱 Telegram 🌐 Web-UI (Browser) │
│ ↓ ↓ │
│ ┌────────────────────────────────┐ │
│ │ ESP32-S3 Chip │ │
│ │ Core 0: Network & Telegram │ │
│ │ Core 1: AI & Display & Logic │ │
│ └────────────────────────────────┘ │
│ ↓ ↓ ↓ │
│ 📺 OLED 💾 SPIFFS 🤖 Groq API │
└─────────────────────────────────────────────────────────────┘
| Feature | Description | |
|---|---|---|
| 📋 | Task Manager | Automatic prioritization via a custom scoring algorithm |
| 🤖 | AI Chat | Groq API – Quick Mode (Llama 3.1 8b) & Deep Mode (Llama 3.3 70b) |
| 📱 | Telegram Bot | Full control via Telegram – commands, inline keyboards, daily reminders |
| 🌐 | Web-UI | Responsive PWA via WebSocket – real-time updates without page reload |
| 🏆 | Habit Tracking | 6 habits with streak counter, persisted via SPIFFS flash |
| ⏱️ | Pomodoro Timer | 1–4 phases, OLED display + Telegram notification on phase change |
| 📺 | OLED Display | Top-3 tasks, time, WiFi RSSI bar, AI spinner, screensaver |
| 💾 | Persistence | Habits survive power cuts thanks to SPIFFS flash storage |
| 🔄 | Dual-Core | FreeRTOS – Core 0: networking, Core 1: UI and AI logic |
| 🛡️ | Heap Management | 3-tier system + persistent TLS connection (saves ~40KB RAM per request) |
| Component | Notes |
|---|---|
| Heltec ESP32-S3 WiFi Kit V3 | OLED already built in ✅ |
| Dupont Jumper Wires | Male-to-Male |
| Breadboard | Standard 830-point |
| USB-C Data Cable |
💡 Lite Edition: This version does not include LED control. For the full version with RGB LEDs (breathing/blink) → branch
full-version
1. Groq API Key (free)
- Create an account at groq.com
- Generate an API key:
Console → API Keys → Create API Key - Two keys recommended – one for Web-UI, one for Telegram (separate rate-limit tracking)
- Free daily limit: ~14,400 requests (8b model)
2. Telegram Bot
- Open Telegram → search for
@BotFather - Send
/newbotand follow the instructions - Note your Bot Token (format:
123456789:AAF...) - Find your Chat ID:
- Start your bot once with
/start - Open in browser:
https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates - The
"id"value under"chat"is your Chat ID
- Start your bot once with
3. WiFi Credentials
- SSID + password of your home network
- Optional: SSID + password of a mobile hotspot as automatic fallback
Install via Sketch → Include Library → Manage Libraries:
| Library | Min. Version | Library Manager Name |
|---|---|---|
| Adafruit SSD1306 | ≥ 2.5 | Adafruit SSD1306 |
| Adafruit GFX | ≥ 1.11 | Adafruit GFX Library |
| ArduinoJson | ≥ 6.21 | ArduinoJson |
| UniversalTelegramBot | ≥ 1.3 | Universal Arduino Telegram Bot |
| WebSockets | ≥ 2.3 | WebSockets (by Markus Sattler) |
Heltec Board Manager URL – paste under File → Preferences → Additional Board Manager URLs:
https://github.com/Heltec-Aaron-Lee/WiFi_Kit_series/releases/download/0.0.9/package_heltec_esp32_index.json
Open AssistantHubPro.ino and replace all YOUR_* placeholders (around line 73–81):
// ─── REQUIRED: Fill in before uploading ─────────────────────
#define BOTtoken "YOUR_TELEGRAM_BOT_TOKEN" // From @BotFather
#define CHAT_ID "YOUR_TELEGRAM_CHAT_ID" // Your Telegram Chat ID
#define GROQ_API_KEY_WEB "YOUR_GROQ_API_KEY_WEB" // Groq key for Web-UI
#define GROQ_API_KEY_TG "YOUR_GROQ_API_KEY_TG" // Groq key for Telegram
const char* ssid = "YOUR_WIFI_SSID";
const char* password = "YOUR_WIFI_PASSWORD";
const char* SSIDhot = "YOUR_HOTSPOT_SSID"; // Optional fallback
const char* Passworthot = "YOUR_HOTSPOT_PASSWORD";Also enter your name (around line ~2529 and ~2676):
display.println("YOUR_NAME"); // Welcome text on OLED
"My name is YOUR_NAME. ..." // AI prompt personalizationBoard: Heltec WiFi Kit 32 V3
Partition Scheme: Default 4MB with spiffs
Upload Speed: 921600
Port: COM port of your ESP32
1. Connect ESP32 via USB-C data cable
2. Sketch → Upload
3. Tools → Serial Monitor (Baud: 115200)
4. After boot: find the IP address in the log
5. Open in browser: http://[ESP32-IP]/
| Command | Description |
|---|---|
/start |
Welcome menu with quick-access buttons |
/testbot |
System status: RAM, IP, tasks, WiFi |
/aufgaben |
All tasks with priority score |
/new |
Create new task – guided 3-step flow |
/finish |
Mark task as done (inline keyboard) |
/ask <question> |
Quick AI question – Llama 3.1 8b |
/deep <topic> |
In-depth research – Llama 3.3 70b |
/pomodoro |
Start a Pomodoro session |
/checkout |
Lock Web-UI (Telegram-only mode) |
/heap |
RAM diagnostics for debugging |
/uptime |
Show system uptime |
/restart |
Safe restart (RTOS-safe, flag-based) |
┌─────────────────────────────────────────────────────────────┐
│ Core 0 – Network Task Core 1 – AI & Main Loop │
│ ├── WiFi Auto-Reconnect ├── OLED Display Rendering │
│ ├── Telegram Polling (400ms) ├── Pomodoro Tick │
│ ├── HTTP Server (Port 80) ├── Screensaver (10s) │
│ ├── WebSocket Loop (Port 81) ├── AI Execution (Groq TLS) │
│ └── AI Response Delivery └── Heap Management │
├─────────────────────────────────────────────────────────────┤
│ SPIFFS Flash │
│ └── /habits.json → Habit streaks (persistent) │
├─────────────────────────────────────────────────────────────┤
│ Heap Management – 3-Tier System │
│ Tier 1: Free AI buffer + yield loops │
│ Tier 2: Pause services (Critical TLS Mode) │
│ Tier 3: Diagnostics + Degraded Mode (8b instead of 70b) │
└─────────────────────────────────────────────────────────────┘
Board not recognized
- Use a USB-C data cable – charging-only cables have no data lines
- Install CP210x VCP driver: Silicon Labs
- Windows: check Device Manager to see if ESP32 appears as a COM port
AI requests failing (HTTP -1)
- Double-check your Groq API keys in the
#definelines - Open Serial Monitor → watch for
[AI]log lines - Restart the ESP32 via
/restartin Telegram - If the issue persists: unplug and replug the chip
WiFi not connecting
- Check SSID and password for typos and capitalization
- Configure the hotspot fallback as a backup network
- ESP32 only supports 2.4 GHz networks, not 5 GHz
SPIFFS errors
- Set
Tools → Partition Scheme → Default 4MB with spiffs - Erase flash:
Tools → Erase Flash → All Flash Contents - Then re-upload the sketch
MIT License – free to use, modify and redistribute with attribution to the original author.
