Login

Ben / moon

Overview Code Talk Settings
1 branch 0 tags
Ben (Desktop/Arch) Some UI tweaks 0653505 1 month ago 44 Commits
moon / firmware / CLAUDE.md
Raw Source
text/markdown • 2.42 KB • 61 lines

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build Commands

Desktop (SDL2 simulator)

make              # Build desktop simulator
make run          # Build and run
make sanitize     # Build with AddressSanitizer
make clean        # Clean build artifacts
make format       # Format source files with clang-format

ESP32 (requires ESP-IDF environment)

make esp32        # Build ESP32 firmware
make esp32-flash  # Flash via /dev/ttyACM0
make esp32-monitor # Serial monitor
make esp32-clean  # Full clean of ESP32 build

Architecture

This is a dual-target firmware project for a handheld device with a 160x128 ST7735 display, 4 buttons, and I2S audio output.

Target Platforms

  • ESP32-S3: Production hardware target using ESP-IDF/FreeRTOS
  • SDL2 Desktop: Development simulator for rapid iteration

Directory Structure

  • src/ - Shared cross-platform application code
  • sdl_src/ - SDL2-specific drivers (display, main loop)
  • esp32/main/ - ESP32-specific drivers (ST7735, buttons, I2S audio)
  • vendor/lvgl/ - LVGL v9.2 graphics library

Platform Abstraction

The codebase uses a clean abstraction layer allowing shared UI code to run on both platforms:

  • Application entry: src/main.c exports setup() and loop() functions called by platform-specific main files
  • Display driver: src/lvgl_port.h defines the interface; implementations in sdl_src/lvgl_port_sdl.c and esp32/main/lvgl_port_esp32.c
  • Input driver: src/lvgl_indev.c is shared; reads button_state global set by platform code
  • Blit functions: blit_buf() and blit_buf_rect() declared in src/moon.h, implemented per-platform

Hardware Configuration (ESP32-S3)

  • Display: SPI (MOSI=7, SCK=8, CS=4, DC=6, RST=5)
  • Buttons: UP=40, DOWN=39, OK=41, BACK=42 (active-low)
  • Audio: I2S (BCK=13, WS=14, DOUT=21), 44.1kHz stereo

Key Constants

  • Screen: 160x128 pixels, ARGB8888 internal format
  • Audio: 44100Hz sample rate, 1024 sample buffer
  • LVGL: 32KB memory pool, ~30fps refresh

Development Notes

  • Desktop build requires SDL2 development libraries (pkg-config --cflags --libs sdl2)
  • ESP32 build requires ESP-IDF toolchain with idf.py in PATH
  • LVGL configuration is in src/lv_conf.h (shared) and esp32/sdkconfig.defaults (ESP32-specific)
  • Vendor code uses relaxed warning flags; project code uses strict -Wall -Werror -Wextra