soundshot/CLAUDE.md

CLAUDE.md

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

Project Overview

SoundShot is an ESP32-based embedded system that appears to be an IMU-based angle measurement device with Bluetooth connectivity and GUI interface. The project uses ESP-IDF (Espressif IoT Development Framework) and can be developed using either Docker containers or native tooling.

Build System & Development Environment

Docker Development (Recommended)

• Setup: Run setup-env.bat to create Python virtual environment and install dependencies
• Container: Uses ESP-IDF Docker containers with VS Code Dev Containers extension
• Build: idf.py build (inside container)

Native Development

• Build: idf.py build (requires ESP-IDF setup)
• Configuration: Uses settings.json for project parameters
• CMake: Project uses ESP-IDF CMake build system with custom configuration generator

Essential Commands

# Environment setup (Windows only)
setup-env.bat

# Build firmware
idf.py build

# Flash device (using custom Python tool)
flash.bat
python flash_tool/flash.py

# Monitor serial output
monitor.bat
python flash_tool/monitor.py

# Combined flash and monitor
flashmon.bat

# Clean build
idf.py fullclean

Project Architecture

Core Components

Main Application (main/)

• main.c - Entry point, IMU processing, task coordination
• system.c/h - System state management, event handling, calibration
• gui.c/h - LVGL-based user interface (3 modes: main, menu, bubble)
• bt_app.c/h - Bluetooth connectivity and communication
• lsm6dsv.c/h - LSM6DSV IMU sensor driver
• keypad.c/h - Physical button input handling
• bubble.c/h - Bubble level visualization

Key Features

• Real-time angle measurement with configurable filtering
• Bluetooth connectivity for data transmission
• LVGL-based GUI with multiple display modes
• Zero-angle calibration system
• Low-pass filtering with adaptive alpha coefficients

Hardware Configuration

GPIO Pins (gpio.h)

• LEDs, LCD backlight, power control
• I2C for IMU communication (SCL=22, SDA=21)
• Serial communication and button inputs

IMU Processing

• LSM6DSV 6-axis IMU sensor
• Angle computation from accelerometer data (XZ, YZ, XY planes)
• Configurable filtering with FILTER_COEFF and MAX_INDICATION_ANGLE
• Primary axis selection via PRIMARY_AXIS define

Configuration Management

settings.json Structure

{
  "project_name": "soundshot",
  "chip": "esp32", 
  "port": "COM3",
  "monitor_baud": 115200,
  "flash_baud": 460800,
  "flash_mode": "dio",
  "flash_freq": "40m", 
  "flash_size": "2MB"
}

Configuration Flow

1. settings.json → prepare_config.py → project_settings.cmake
2. CMake includes generated settings during build
3. Flash tools read settings.json for esptool parameters

Build Dependencies

ESP-IDF Components

• driver - GPIO, I2C, peripherals
• esp_lcd - Display drivers
• lvgl + esp_lvgl_port - GUI framework
• esp_timer - High resolution timers
• nvs_flash - Non-volatile storage
• bt - Bluetooth stack

Managed Components

• LVGL 9.x with ESP32 port integration
• Located in managed_components/

Development Guidelines

Code Organization

• Hardware abstraction in dedicated modules (lsm6dsv.c, keypad.c)
• System state centralized in system.c with event-based communication
• GUI logic separated from business logic
• Bluetooth handled as separate subsystem

Key Constants & Tuning Parameters

• MAX_INDICATION_ANGLE (5.0°) - Angle measurement limit
• FILTER_COEFF (0.4) - Low-pass filter strength
• PRIMARY_AXIS - Main measurement axis selection
• Filter alpha computed dynamically based on input magnitude

Testing & Debugging

• Serial monitoring at 115200 baud via monitor.bat
• Debug prints use ESP-IDF logging (ESP_LOGI, ESP_LOGW, etc.)
• IMU data output can be enabled via conditional compilation blocks

Flash Memory Layout

• Bootloader: 0x1000
• Partition table: 0x8000
• OTA data: 0x11000
• Application: 0x20000

Common Development Patterns

When modifying this codebase:

1. IMU changes: Update filtering parameters in main.c and constants in system.h
2. GUI changes: Modify LVGL code in gui.c, add new modes to GuiMode_t enum
3. Bluetooth changes: Update message handlers in bt_app.c
4. Hardware changes: Update pin definitions in gpio.h and initialization in main.c
5. Build changes: Modify component dependencies in main/CMakeLists.txt

Always test flashing and monitoring tools after hardware configuration changes.