147 lines
4.7 KiB
Markdown
147 lines
4.7 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```json
|
|
{
|
|
"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. |