barnum/ai.recreate.md

# AI Recreation Instructions

This document contains instructions for an AI assistant to recreate the Barnum project from scratch.

## Project Overview

Create a network-controllable WS2812 LED system using the Waveshare RP2040-ETH board. The system should accept TCP commands over ethernet to control LED colors with visual feedback indicators.

## Hardware Requirements

- Waveshare RP2040-ETH board (contains RP2040 + CH9120 ethernet chip)
- WS2812/NeoPixel LED strip or individual LED
- Ethernet cable and network connection
- USB-C cable for programming

## Core Requirements

### 1. LED Control System
- Use PIO (Programmable I/O) for WS2812 timing control
- Connect WS2812 data line to GPIO 25
- Implement smooth color transitions between commands
- Support RGB color mixing

### 2. Network Communication  
- Use CH9120 ethernet chip via UART communication
- Configure as TCP server on port 1000
- IP address: 192.168.1.201 (or adapt to local network)
- Subnet mask: 255.255.0.0 (adapt to local network)
- Gateway: 192.168.1.1 (adapt to local network)

### 3. Visual Feedback System
- Green flash every 1 second: firmware alive indicator
- Amber flash on network activity: traffic indicator  
- Blue flashes on startup: initialization complete
- Maintain commanded color between status flashes

### 4. Command Protocol
Support these TCP commands:
- `RED`, `GREEN`, `BLUE`, `WHITE`, `OFF`
- `RGB:r,g,b` format for custom colors (e.g., `RGB:255,128,0`)
- Send acknowledgment responses back to client

## Implementation Details

### CH9120 Configuration
```c
// Pin assignments
#define UART_TX_PIN1 20  // To CH9120
#define UART_RX_PIN1 21  // From CH9120  
#define CFG_PIN 18       // Configuration mode
#define RES_PIN 19       // Reset pin

// Network settings
TCP_SERVER mode
IP: 192.168.1.201
Subnet: 255.255.0.0
Gateway: 192.168.1.1
Port: 1000
```

### Key Technical Points

1. **CH9120 Initialization Sequence**:
   - Hard reset (RES pin low->high)
   - Enter config mode (CFG pin low)
   - Send configuration commands via UART at 9600 baud
   - Exit config mode and switch to 115200 baud for data

2. **WS2812 Control**:
   - Use ws2812.pio program for timing
   - GRB color format (not RGB)
   - 800kHz timing requirement

3. **Timing Management**:
   - Use `to_ms_since_boot(get_absolute_time())` for timing
   - Non-blocking network checks
   - Smooth color transitions (increment/decrement by 1 per step)

4. **Visual Indicators**:
   - Override any color during status flashes
   - Green flash: `put_rgb(0, 128, 0)` for 100ms every 1000ms
   - Amber flash: `put_rgb(255, 191, 0)` for 50ms on network activity

## File Structure to Create

1. **barnum.c** - Main application combining LED and network control
2. **ch9120.c/.h** - Ethernet chip driver with initialization and data functions
3. **CMakeLists.txt** - Build configuration for Pico SDK
4. **test_client.py** - Python client for testing commands
5. **test_ethernet.py** - Network diagnostics tool
6. **ws2812.pio** - PIO program for LED timing (copy from Pico examples)

## Critical Implementation Notes

### CH9120 Driver Functions Needed:
```c
void CH9120_init(void);                    // Initialize and configure
void CH9120_send_data(const char *data, size_t len);  // Send TCP data
int CH9120_receive_data(char *buffer, size_t max_len); // Receive TCP data
```

### Color Command Parser:
```c
void parse_color_command(const char *cmd, uint8_t *r, uint8_t *g, uint8_t *b);
```

### LED Control Functions:
```c
void put_rgb(uint8_t red, uint8_t green, uint8_t blue);
void put_pixel(uint32_t pixel_grb);
```

## Build System Setup

Use Pico SDK with these key settings:
- Board type: `waveshare_rp2040_eth`
- Enable USB stdio: Yes
- Enable UART stdio: Yes  
- Link libraries: `pico_stdlib`, `hardware_pio`, `hardware_uart`

## Testing Approach

1. **Hardware Test**: Look for green heartbeat flash
2. **Network Test**: `ping 192.168.1.201`
3. **TCP Test**: `nc 192.168.1.201 1000` then send color commands
4. **Integration Test**: Use Python client to send various color commands

## Common Issues and Solutions

1. **No ping response**: Check subnet mask matches local network
2. **LED not working**: Verify GPIO 25 connection and power supply
3. **No network data**: Ensure TCP_SERVER mode, not TCP_CLIENT
4. **Color wrong**: Remember WS2812 uses GRB format, not RGB

## Reference Code Location

The project includes reference code in `Refernce Code/RP2040_ETH_CODE/C/` that demonstrates basic CH9120 usage patterns. Study this for command structure and timing requirements.

## Success Criteria

- LED flashes green every second (alive indicator)
- Responds to ping at 192.168.1.201
- Accepts TCP connections on port 1000
- Changes LED color based on received commands
- Shows amber flash during network activity
- Sends acknowledgment messages back to client
- Smooth color transitions between commands

This should provide a complete foundation for recreating the network-controlled LED system.