README.md

 Starmoon - An affordable, empathic, and conversational AI companion

Starmoon is an affordable, compact AI-enabled device, you can take anywhere and converse with. It can understand your emotions and respond with empathy, offering supportive conversations and personalized learning assistance.

Check our Roadmap

   

Demo Highlights 🎥

Demo.mp4

If you can't see the video, you can watch it here

Key features 🎯

• Cost-effective: Assemble the device yourself with affordable off-the-shelf components.
• Voice-enabled emotional intelligence: Understand and analyze insights in your emotions through your conversations in real time.
• Open-source: Fully open-source, you can deploy Starmoon locally and self-host to ensure the privacy of your data.
• Compact device: Only slightly larger than an Apple Watch, you can carry the device anywhere.
• Reduced screen time: A myriad of AI companions are screen-based, and our intention is to give your eyes a rest.

Getting Started 🚀

Prerequisites 📋

1. API keys and services:

   • Docker
   • Supabase CLI: Follow the instructions here to install if you haven't installed
   • Vscode and PlatformIO plugin: For firmware burning
   • OpenAI API key: For AI language models
   • Deepgram API key: For speech-to-text
   • Azure speech API keys: For text-to-speech
   • Huggingface API key: For emotion intelligence

2. Hardware list (Tax and shipping rates may vary by region)

   • Seeed Studio Xiao ESP32S3
   • Microphone (INMP441)
   • Amplifier (MAX98357A)
   • Speaker (3525)
   • LED light
   • Button
   • PCB prototype board or custom PCB
   • 3D printed case
   • Tools: 28AWG wires + soldering toolset + flux

Software setup 🖥️

• Step 0: Clone the repository:

  git clone https://github.com/StarmoonAI/Starmoon.git && cd starmoon

• Step 1: Set up Supabase:

  supabase start

  supabase db reset

• Step 2: Copy the .env.example files

  cp .env.example .env

• Step 3: Update tokens in the .env file

  • For local set up, you only need to update OPENAI_API_KEY, MS_SPEECH_ENDPOINTY, SPEECH_KEY, SPEECH_REGION, DG_API_KEY, HF_ACCESS_TOKEN

• Step 4: Launch the project

  • If you have a Mac, go to Docker Desktop > Settings > General and check that the "file sharing implementation" is set to VirtioFS.

    docker compose pull
    docker compose up

    If you are a developer, you can run the project in development mode with the following command: docker compose -f docker-compose.yml up --build

• Step 5: Login to the app

  • You can now sign in to the app with [email protected] & admin. You can access the Starmoon webapp at http://localhost:3000/login and sign up an account

  • You can access Starmoon backend API at http://localhost:8000/docs

  • You can access Supabase dashboard at http://localhost:54323

  • You can access Celery Flower background task dashboard at http://localhost:5555 (admin & admin)

Hardware setup 🧰

• Step 0 (Optional): Build the device yourself (alternatively, the Starmoon DIY Dev Kit comes pre-assembled so you can focus on working with your own frontend + backend)

  • Follow the instructions here in Pin Configuration section for more details on assembly

• Step 1: Click PlatformIO Icon in VScode left sidebar

  • Click "Pick a folder"
  • Select the location of the firmware folder in the current project.

• Step 2: Update and WebSocket server details in src/main.cpp

  • Find your WiFi ip adress (websocket_server_host) by command ipconfig (under Default Gateway) in Windows or ifconfig (under inet xxx.x.x.x netmask 0xff000000) in Linux/MacOS, or you can also follow the instructions here

    // WebSocket setup
    const char *websocket_server_host = "<your-server-host-ip>"; // Wifi settings -> Your Wifi I.P.
    const uint16_t websocket_server_port = 8000;
    const char *websocket_server_path = "/starmoon";
    const char *auth_token = "<your-STARMOON_API_KEY-here>"; // generate your STARMOON_API_KEY in your starmoon account settings page

• Step 3: Build the firmware

  • Click Build button in the PlatformIO toolbar or run the build task.

• Step 4: Upload the firmware to the device

  • Connect your ESP32-S3 to your computer using usb.
  • Click the Upload button to run the upload task, or Upload and Monitor button to run the upload task and monitor the device.

• Step 5: Hardware usage

  • Power the device -> Use your phone/tablet/pc to connect "Starmoon device" WiFi and follow the instructions to set up internet connection (only support 2.4Ghz WiFi).

  • Once the software and firmware are set up, you can push the button to power on the ESP32 device and start talking to the device.

Updating Starmoon App 🚀

• Step 1: Pull the latest changes

  git pull

• Step 2: Update the migration

  supabase migration up

License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details