The Problem

StackChan is an open-source AI desktop robot built on the M5Stack CoreS3 (ESP32-S3). The pain point it solves is the fragmentation between the robot's firmware, its mobile control app, a companion server, and a wireless remote—all of which are needed for a working product but are typically scattered across separate repositories and toolchains. This repo consolidates those four components into one place.

What This Does

The repository contains four independent projects: firmware/ (C/C++ for the ESP32-S3 robot), app/ (Flutter mobile app for iOS/Android), server/ (Go backend), and remote/ (C/C++ for a separate remote controller). The firmware handles motor control, IMU (via BMI270_SensorAPI), display, and networking. The Flutter app provides the user interface for video, avatar control, and AI agent configuration. The Go server handles device registration, AI agent orchestration, and WebSocket communication.

This is a fork of m5stack/StackChan (1,184 stars) with modifications—likely for a specific deployment or client need. The README is the official M5Stack documentation, and the codebase appears to be a recent snapshot of the upstream project.

How It Is Wired

The wiring is not fully mapped for this repository. Static analysis resolved 2 internal Go modules with 0 import edges and no circular dependencies, but the import graph for the firmware and Flutter app is not resolved. The entry points are:

  • Firmware: firmware/main/main.cpp — boots the ESP32-S3, initializes hardware, and runs the main loop
  • App: app/lib/main.dart — Flutter entry point, initializes the UI and networking
  • Server: server/main.go and server/internal/cmd/cmd.go — starts the HTTP/WebSocket server

The server is the central hub: the app connects to it via WebSocket (app/lib/network/web_socket_util.dart), and the firmware connects for OTA updates and remote control. The firmware also supports ESP-NOW for direct remote control without the server. The server/manifest/docker/Dockerfile suggests the server is deployed as a container, likely on Kubernetes given the manifest directory.

How To Use It

Setup: The repo has no CI pipeline and no root-level build orchestration. Each project builds independently:

# Server (Go)
cd server && go build ./...

# Firmware (PlatformIO or Arduino)
cd firmware && pio run  # requires PlatformIO

# App (Flutter)
cd app && flutter pub get && flutter build ios  # or android

Configuration: The server uses server/go.mod for dependencies. Environment variables are not documented in the README. The firmware likely requires M5Stack BSP (from m5stack/StackChan-BSP). The app requires a server URL configured in app/lib/network/urls.dart.

Running: The server starts with go run main.go. The app runs via flutter run. The firmware flashes via PlatformIO. No Docker build or Kubernetes deployment instructions are present in the README.

Real-World Use

A typical deployment: the Go server runs on a cloud VM or Kubernetes cluster, handling device auth and AI agent WebSocket sessions. The mobile app connects to it to control the robot remotely, view the camera feed, and configure the AI agent. The robot itself connects to the same server for OTA updates and remote commands, or works standalone with the ESP-NOW remote.

Code Health & Issues

Static analysis found 116 issues (57 high, 59 medium) across three kinds:

  • High - Deep nesting (x52): app/ios/Runner/Utils/Extension.swift, NativeBridge.swift, StackChanArView.swift have indentation depth up to 8, making control flow hard to follow.
  • High - Duplicated code (x2259): 6-line blocks repeated across 223 files, notably in StackChanArView.swift and agents_device.dart.
  • High - Oversized files (x7): firmware/main/hal/drivers/bmi270/BMI270_SensorAPI/bmi2.c is 7,808 lines.

Additional findings from the code health audit:

  • High - No LICENSE file at root; redistribution rights are undefined.
  • High - No CI workflow; 278 source files with no automated build gate.
  • High - No build gate for the server Docker image.
  • Medium - No Dependabot/Renovate configured.
  • Medium - Docker base image alpine:latest is mutable; pin by digest.
  • Medium - app/ios/Runner/3DModel/StackChanModel.scn is 8.0MB and should use Git LFS.
  • Medium - No non-root USER in the Dockerfile.
  • Medium - Test ratio is 3 test files against 373 source files (0.008).
  • Low - Missing .editorconfig, .gitattributes, formatter config.
  • Committed secrets: flagged by the audit; verify firmware/scan_secrets.py.

The Bottom Line

This is a complete, working product codebase for a niche hardware device. The firmware and app are functional but carry significant technical debt (deep nesting, duplication, oversized vendor files). The server is small and clean. It's suitable for someone who needs the full StackChan stack and is willing to add CI, a license, and test coverage. The core value is the working firmware and app integration, not the server.