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

// 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:

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:

void parse_color_command(const char *cmd, uint8_t *r, uint8_t *g, uint8_t *b);

LED Control Functions:

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.