README.md

A tiny ESP32-C3 AI companion. It listens, thinks, and chats using your AI key —
then pulls goofy faces when you leave it alone. Flash it from your browser. No IDE. No drivers.

⚡  Flash your Mochi  ·  🔌 Wiring  ·  🧠 How it works  ·  🚀 Start

---

🍡 Meet Mochi

Mochi is a palm-sized robot built around a Waveshare ESP32-C3-Zero. Hold the touch button, ask it anything — the time, the weather, the news, a random question — and it answers out loud through a little speaker. The OLED is its face: it watches you while listening, gets a thoughtful look while it thinks, and its mouth moves while it talks.

Leave it alone and it just... blinks, glances around, and cycles through silly expressions to keep you company. There's even a pure face-toy mode if you just want the cuteness without the chatter.

The face above is the real animation logic from the firmware — idle → listening → thinking → talking.

😊 idle	👀 listening	💭 thinking	🗣️ talking
blinks & looks around	wide eyes, alert	eyes up, dots	mouth lip-syncs audio

---

✨ Features

🗣️ Talk & listen Push-to-talk to ask anything. Speech in, speech out — a real little voice assistant.	🔑 Your key, your model Bring OpenAI, Groq, OpenRouter, Together, or Gemini. Paste your key, switch any time.	😜 Silly idle faces Blinks, gazes, and goofy moods when idle. Toggle a pure face-toy mode.
📡 App-free setup The bot hosts its own WiFi page to enter credentials — like setting up a smart bulb.	🔋 Truly portable LiPo + TP4056 charger + slide switch. A pocket companion that runs off a battery.	🛠️ Hackable One clean Arduino sketch, parameterised faces, swappable pins. Fork it, make it yours.

---

🧠 How it works

flowchart LR
    A([🎙️ You speak]) --> B[INMP441 mic<br/>I2S]
    B --> C{{ESP32-C3}}
    C -->|stream audio| D[Speech-to-Text]
    D --> E[Your AI provider<br/>LLM reply]
    E --> F[Text-to-Speech]
    F -->|stream audio| C
    C --> G[MAX98357A amp<br/>I2S]
    G --> H([🔊 Mochi talks])
    C -.drives.-> I[(😊 OLED face<br/>listen-think-talk)]

    style C fill:#3a3f4b,color:#fff
    style E fill:#e89a8b,color:#fff
    style I fill:#f3c9a8,color:#2b2622

Loading

Because the ESP32-C3 is a small single-core chip, the heavy lifting — speech-to-text, the language model, and text-to-speech — runs on your chosen provider's servers. The C3 captures your voice, streams it up, plays the reply back, and animates the face locally. Setup happens over a captive-portal WiFi page the bot serves itself, so there's no app to install.

---

🧩 Hardware

Part	Role	Interface
Waveshare ESP32-C3-Zero	brain + WiFi	—
SSD1306 0.96" OLED	the face & status	I2C
INMP441 mic	hears you	I2S in
MAX98357A + 2W speaker	talks back	I2S out
3× TTP223 touch buttons	talk / next-face / mode	digital
LiPo + TP4056	portable power	3.7V
slide switch	on / off	—

---

🔌 Wiring

Everything runs at 3.3V. Default pins live in config.h — easy to change.

OLED (I2C) signal GPIO SDA 4 SCL 5 Mic — INMP441 (I2S) signal GPIO SCK 0 WS 1 SD 2 L/R GND

Speaker — MAX98357A (I2S) signal GPIO BCLK 6 LRC 7 DIN 8 SD 3V3 Touch buttons (TTP223) button GPIO job TALK 3 push-to-talk NEXT 18 next face MODE 19 mode toggle

⚠️ Reserved on the C3-Zero — don't use: GPIO9 (BOOT), GPIO10 (onboard RGB LED), GPIO12–17 (onboard flash). The pins above already avoid all of them. 👉 Interactive pin diagram on the project site →

Full step-by-step: hardware/WIRING.md

---

🚀 Getting started

🙂 For users — no coding Open the flash page in Chrome / Edge / Opera. Hold BOOT while plugging in USB-C (flash mode). Click Connect & Flash, pick the port, confirm. The bot makes a WiFi network: DasaiMochi-Setup. Join it → a setup page opens → enter WiFi + your AI key. 🍡

🧑‍💻 For developers git clone https://github.com/YOUR-USERNAME/dasai-mochi-bot cd dasai-mochi-bot # PlatformIO pio run # compile pio run -t upload # flash over USB …or open the sketch in Arduino IDE (board: ESP32C3 Dev Module).

---

🔑 Getting an API key

Provider	Get a key	Notes
Groq ⭐	console.groq.com/keys	fast, generous free tier, Llama 3.x — best default
OpenAI	platform.openai.com/api-keys	GPT models, paid
OpenRouter	openrouter.ai/keys	one key, many models
Together	api.together.xyz	open models, free tier
Gemini	aistudio.google.com/apikey	Google, free tier

🔐 Your key is entered on the device's own setup page and stored only in the ESP32's flash. It's sent only to the provider you chose, over HTTPS. It never touches this repo.

---

📁 Project layout

dasai-mochi-bot/
├─ firmware/dasai_mochi_bot/    🔧 the Arduino sketch
│  ├─ dasai_mochi_bot.ino       main loop · provisioning · conversation
│  ├─ config.h                  pins & tunables  (edit to rewire)
│  ├─ providers.h               multi-provider LLM table
│  ├─ faces.{h,cpp}             😊 the silly-face engine
│  ├─ llm_client.{h,cpp}        chat + speech-to-text over HTTPS
│  ├─ audio_io.{h,cpp}          I2S mic capture + speaker playback
│  └─ portal_page.h             on-device WiFi/key setup page
├─ docs/                        🌐 GitHub Pages site (flasher + diagram)
│  ├─ index.html                landing · browser flasher · pin diagram
│  ├─ assets/mochi-face.svg     the animated face (also used above)
│  └─ firmware/manifest.json    ESP Web Tools manifest
├─ hardware/WIRING.md           🔌 full wiring guide
├─ platformio.ini
└─ README.md

---

🗺️ Roadmap

• Commit the prebuilt merged.bin so the web flasher goes live
• Wake-word ("Hey Mochi") instead of push-to-talk
• More face moods + per-mood sound effects
• Battery level shown on the RGB LED
• 3D-printable shell in /hardware

---

🙏 Credits

Browser flashing by ESP Web Tools (ESPHome / Nabu Casa) · animated banner by readme-typing-svg · inspired by the open-source XiaoZhi AI ESP32 chatbot community.

📄 License

MIT — see LICENSE. Build one, fork it, make it weirder.

_{Built with 🍡 for makers.}