Starmoon: An Open-Source ESP32 AI Companion Device, Now Deprecated in Favour of ElatoAI

What Starmoon was and why it is deprecated

Starmoon was a framework for building a small, wearable AI device that could hold real-time conversations, detect emotions in speech, and run custom AI character personas. The hardware was designed to be assembled from off-the-shelf parts costing under the price of most commercial AI devices, running on a Seeed Studio XIAO ESP32S3 or a compatible ESP32-S3 board.

The README now carries a prominent deprecation notice: the project is no longer actively maintained. The last push to the repository was on 2026-03-27. The README redirects users to ElatoAI, a successor project by the same original developer, which the README describes as having improved WiFi and two-way voice AI audio reliability, global availability, and a production-ready architecture.

For anyone evaluating this repository, the deprecation is the most important fact. The architecture and code patterns remain readable and instructive, but using Starmoon as the foundation for a new device project means accepting an unmaintained dependency stack. The .env.example shows dependency on GPT-4o, Deepgram STT, and Azure TTS, all of which are commercial services with APIs that change over time.

Hardware design: ESP32 with microphone, amplifier, and speaker

The hardware design centres on an ESP32-S3 microcontroller paired with an I2S microphone and a speaker driven through an I2S amplifier. The component list from the README includes: a Seeed Studio XIAO ESP32S3, an INMP441 I2S microphone, a MAX98357A I2S amplifier, a small speaker, an RGB LED, and a pushbutton. The case is a 3D-printed shell available as case_model.stl in the repository.

The pin configuration is defined in the firmware. For the XIAO ESP32S3, the microphone uses pins D0 (SD), D1 (WS), and D2 (SCK). The speaker amplifier uses pins D5 (WS), D6 (BCK), and D4 (DATA). The LED pins are D7 (red), D8 (green), and D9 (blue), with the button on D10.

Wireless connectivity uses 2.4 GHz WiFi only. The README notes the ESP32 captive portal handles initial WiFi setup: after flashing firmware, the device broadcasts its own WiFi network for configuration, then connects to the home network once credentials are entered. The firmware does not support 5 GHz WiFi.

To clone the repository before starting hardware setup:

git clone https://github.com/StarmoonAI/Starmoon.git

Firmware configuration: board selection and PlatformIO build

The firmware uses PlatformIO (a VS Code extension) rather than the Arduino IDE directly. Before building, you must select the correct board in `firmware/src/Config.h`. For a standard ESP32-S3 devkit (not the XIAO variant), uncomment the matching define:

// ----------------- Pin Definitions -----------------
// Define which board you are using (uncomment one)
#define USE_NORMAL_ESP32_S3
// #define USE_XIAO_ESP32_DEVKIT
// #define USE_XIAO_ESP32
// #define USE_NORMAL_ESP32
// #define USE_ESP32_S3_WHITE_CASE

Then update the PlatformIO environment in `firmware/platformio.ini` to match:

; [env:seeed_xiao_esp32s3]
; platform = espressif32
; board = seeed_xiao_esp32s3
; framework = arduino
; monitor_speed = 115200

[env:esp32-s3-devkitm-1]
platform = espressif32
board = esp32-s3-devkitm-1
framework = arduino
monitor_speed = 115200

With the configuration set, open the firmware/ folder in VS Code with PlatformIO, click Build, then Upload. Connect the ESP32 via USB before uploading. The README notes you can also use the Upload and Monitor button to see serial output during the upload.

Software stack: Next.js frontend and Python backend via Docker

The software side of Starmoon consists of a Next.js frontend and a Python backend, both orchestrated through Docker Compose. The backend runs a FastAPI server with Uvicorn, listening on port 8000 with extended WebSocket ping intervals (600 seconds) to keep voice connections open. The frontend runs on port 3000.

The .env.example file documents all required credentials. The AI services needed are: an OpenAI API key for GPT-4o, a Deepgram key for speech-to-text (DG_API_KEY), and either Microsoft Azure TTS credentials (MS_SPEECH_ENDPOINTY, SPEECH_KEY, SPEECH_REGION) or Fish TTS as an alternative. Database configuration uses Supabase; the example file provides a local Supabase URL and anon key for development.

The backend uses Celery with Redis for task queuing (CELERY_BROKER_URL=redis://redis:6379/0). Redis runs as a third container in the docker-compose stack. This means a working local deployment requires four services running: frontend, backend-core, redis, and Supabase (running separately as a local instance or using a cloud project).

The emotional intelligence feature uses a Hugging Face inference endpoint for emotion classification (SamLowe/roberta-base-go_emotions), documented in the HF_EMOTION_API_URL variable.

Key limitations of the Starmoon architecture

The most significant limitation is that Starmoon is deprecated. The README is unambiguous about this status. The project is no longer actively maintained, and the last commit arrived on 2026-03-27. Anyone building on this codebase assumes responsibility for keeping the GPT-4o, Deepgram, Azure TTS, and Supabase integrations working as those APIs evolve.

Beyond deprecation, the hardware design has several constraints. Only 2.4 GHz WiFi is supported. The original README notes that the WiFi configuration portal needs improvement, which was one of the stated motivations for ElatoAI. The device is designed to hold conversations, not to send SMS, make calls, or function as a general-purpose IoT controller.

The ESP32-S3 platform also imposes memory constraints that limit the complexity of on-device processing. All language model inference and speech processing happen on remote APIs, meaning the device requires a live internet connection at all times. There is no offline fallback mode.

The software stack requires four services running simultaneously for local development, which adds friction for contributors. The README does not document how to run the frontend and backend without Docker, making the Docker setup the only documented path.

ElatoAI as the recommended successor project

The README directs users to ElatoAI at https://github.com/akdeb/ElatoAI as the actively developed continuation of the Starmoon approach. According to the Starmoon README, ElatoAI builds on the same ideas with improved WiFi reliability, better two-way voice AI audio, global availability, and a production-ready architecture.

Starmoon's value today is primarily as an architectural reference. The combination of an ESP32-S3 with I2S audio, a Python WebSocket backend, GPT-4o for conversation, Deepgram for real-time transcription, and Azure TTS for voice synthesis is a complete working pattern that can be studied from this codebase. The custom AI character system, where different persona prompts change how the device responds, is implemented in the backend and can be examined independently of the hardware.

For teams building IoT voice AI projects and wanting to understand the WebSocket message flow between the ESP32 firmware and a cloud backend, the firmware/ directory combined with the Python backend source in backend/ provides a complete reference implementation even in its deprecated state.

Licence and maintenance status

Starmoon is available under the GPL-3.0 licence. GPL-3.0 requires that derivative works using GPL-licensed code be distributed under the same licence when distributed to others. Teams building commercial products on top of Starmoon should review the licence terms carefully, as GPL-3.0 has stricter copyleft requirements than MIT or Apache-2.0.

The last push to the repository was on 2026-03-27. The project is not marked as archived on GitHub but the README explicitly states it is no longer actively maintained. There are no GitHub releases.

Editorial conclusion

Developers wanting to build a conversational AI device on ESP32 hardware should start with ElatoAI rather than Starmoon. The README explicitly redirects users there, citing improved WiFi reliability and production-ready architecture. Starmoon remains a useful reference for understanding how GPT-4o, Deepgram STT, and Azure TTS can be wired together over WebSockets to an ESP32 microcontroller. Teams wanting to study the architecture should clone the repository and read the .env.example and docker-compose.yml files alongside the README hardware setup guide.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. Project website
4. README
5. StarmoonAI/Starmoon on GitHub