# CLAUDE.md

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

## Project Overview

Channel3 is an ESP8266 firmware that broadcasts analog NTSC/PAL television signals. It modulates RF through GPIO3/RX at 80 MHz using the I2S bus with DMA, allowing an analog TV tuned to Channel 3 to display graphics, text, and 3D content.

## Build Commands

```bash
make              # Build firmware (outputs image.elf-0x00000.bin)
make showvars     # Debug: display all build variables
```

Git submodules auto-initialize on first build if missing.

## Configuration

Edit `user.cfg` for:
- `PORT` - Serial port for flashing (default: `/dev/ttyUSB0`)
- `OPTS += -DPAL` - Uncomment to enable PAL mode (default is NTSC)
- `FWBURNFLAGS` - Flash baud rate

## Architecture

### Video Signal Generation

The core innovation is using I2S DMA at 80 MHz to generate TV signals:

1. **Premodulation tables** (`tablemaker/broadcast_tables.c`) contain 1408-bit patterns per color, chosen as an exact harmonic of both NTSC chroma (3.579545 MHz) and Channel 3 luma (61.25 MHz)

2. **Line state machine** (`tablemaker/CbTable.c`) defines behavior for each scanline (263 lines NTSC, 313 lines PAL) - sync pulses, blanking, colorburst, active video

3. **DMA engine** (`user/video_broadcast.c`) fills buffers via interrupt on each line completion, using `CbTable` to select the appropriate line handler

### Framebuffer

- Double-buffered: 232x220 pixels (NTSC) or 232x264 (PAL)
- 4 bits per pixel (16 colors)
- Front/back buffer swapping on frame completion

### Key Source Files

- `user/video_broadcast.c` - DMA setup, interrupt handlers, modulation
- `user/3d.c` - Fixed-point 3D engine (256 = 1.0, 8-bit fractional)
- `user/user_main.c` - Demo screens, main loop, initialization
- `tablemaker/CbTable.c` - NTSC/PAL line type definitions
- `tablemaker/broadcast_tables.c` - Premodulated waveform lookup table
- `common/` - HTTP server, mDNS, WiFi, flash filesystem

### Web Interface

Connect to `http://192.168.4.1` when device is in SoftAP mode. The NTSC control panel allows:
- Screen selection and demo freeze
- Color jamming for RF testing
- Interactive JavaScript shader for custom color waveforms
- DFT visualization

## PAL vs NTSC

Controlled by `-DPAL` compile flag. PAL mode broadcasts PAL-compliant B/W timing with NTSC color encoding (NTSC50-like). The main differences are in `CbTable.c` line counts and timing.

## ESP32 Port (esp32_channel3)

The ESP32 port is located in `esp32_channel3/` directory.

### Building and Flashing

**Claude should run these commands directly** - do not ask the user to run them manually.

Build command (from bash):
```bash
/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe -ExecutionPolicy Bypass -Command "Set-Location 'C:\git\channel3\esp32_channel3'; .\build.ps1"
```

Flash command (COM5):
```bash
/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe -ExecutionPolicy Bypass -Command "Set-Location 'C:\git\channel3\esp32_channel3'; .\flash.ps1"
```

### Technical Notes

The ESP-IDF tools have MSYSTEM checks that block builds from MSYS2. These were patched in `C:\Espressif\frameworks\esp-idf-v5.5.2\tools\`:
- `idf.py` line ~914: Added `main()` call after MSYSTEM warning
- `idf_tools.py` line ~3600: Changed `fatal()` to `warn()` and removed `SystemExit`