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

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:

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)
Line state machine (tablemaker/CbTable.c) defines behavior for each scanline (263 lines NTSC, 313 lines PAL) - sync pulses, blanking, colorburst, active video
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):

/c/Windows/System32/WindowsPowerShell/v1.0/powershell.exe -ExecutionPolicy Bypass -Command "Set-Location 'C:\git\channel3\esp32_channel3'; .\build.ps1"

Flash command (COM5):

/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

3.3 KiB Raw Blame History