barnum/README.md

# Barnum - RP2040-ETH WS2812 Network Control

A network-controllable WS2812 LED system built on the Waveshare RP2040-ETH board. Control LED colors over ethernet using simple TCP commands.

## Features

- **Network Control**: TCP server accepting color commands over ethernet
- **Visual Feedback**: 
  - Green flash every 1s (firmware alive indicator)
  - Amber flash on network traffic (RX/TX activity)
  - Smooth color transitions between commands
- **Real-time Response**: Immediate color changes with network acknowledgments
- **Debug Output**: Comprehensive serial logging for troubleshooting

## Hardware

- **Board**: Waveshare RP2040-ETH
- **LED**: WS2812/NeoPixel connected to GPIO 25
- **Ethernet**: CH9120 chip with built-in TCP/IP stack
- **Power**: USB-C for programming, external power for LED strips

## Pin Configuration

| Function | GPIO | Description |
|----------|------|-------------|
| WS2812 Data | 25 | LED strip data line |
| UART TX (CH9120) | 20 | Serial to ethernet chip |
| UART RX (CH9120) | 21 | Serial from ethernet chip |
| CFG (CH9120) | 18 | Configuration mode pin |
| RES (CH9120) | 19 | Reset pin for ethernet chip |

## Network Configuration

- **IP Address**: 192.168.1.201
- **Subnet Mask**: 255.255.0.0
- **Gateway**: 192.168.1.1
- **Mode**: TCP Server
- **Port**: 1000

## Supported Commands

Send these as TCP messages to port 1000:

| Command | Effect |
|---------|--------|
| `RED` | Set LED to red |
| `GREEN` | Set LED to green |
| `BLUE` | Set LED to blue |
| `WHITE` | Set LED to white |
| `OFF` | Turn LED off |
| `RGB:r,g,b` | Custom color (e.g., `RGB:255,128,0` for orange) |

## Building

```bash
# Setup (first time)
git clone <this-repo>
cd barnum

# Build
mkdir -p build
cd build
cmake ..
make barnum

# Flash
# 1. Hold BOOTSEL button on RP2040-ETH
# 2. Connect USB-C cable
# 3. Copy barnum.uf2 to RPI-RP2 drive
# 4. Board reboots automatically
```

## Usage Examples

### Python Client
```python
import socket

sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect(('192.168.1.201', 1000))
sock.send(b'RED')
response = sock.recv(1024)
print(response.decode())  # "Setting color to R:255 G:0 B:0"
sock.close()
```

### Command Line
```bash
# Test with netcat
echo "BLUE" | nc 192.168.1.201 1000

# Test with included Python client
python3 test_client.py GREEN
python3 test_client.py "RGB:255,0,255"
```

### Network Testing
```bash
# Basic connectivity
ping 192.168.1.201

# Port scan
python3 test_ethernet.py

# Network discovery
python3 network_scan.py
```

## Visual Indicators

1. **Startup**: 3 blue flashes (ethernet initialization)
2. **Alive**: Green flash every 1 second (firmware running)
3. **Traffic**: Amber flash on network activity
4. **Commands**: Smooth color transitions to target colors

## Project Structure

```
barnum/
├── barnum.c              # Main application (network + LED control)
├── barnum-initial.c      # Original LED cycling demo
├── ch9120.c/.h           # CH9120 ethernet chip driver
├── ws2812.pio           # PIO program for WS2812 timing
├── CMakeLists.txt       # Build configuration
├── test_client.py       # Python test client
├── test_ethernet.py     # Network diagnostics
├── network_scan.py      # Network discovery tool
├── README_ETH.md        # Ethernet implementation details
└── rp-2040.md          # Hardware documentation
```

## Troubleshooting

### No Network Connectivity
1. Check ethernet cable connection
2. Verify green/amber LEDs on RJ45 connector
3. Monitor serial output for configuration errors
4. Ensure IP settings match your network

### LED Not Responding
1. Verify WS2812 connection to GPIO 25
2. Check power supply to LED strip
3. Look for "Received command" in serial output

### Build Issues
1. Ensure Pico SDK is properly installed
2. Check board type in CMakeLists.txt
3. Verify pico_sdk_import.cmake is present

## Development Notes

- Built with Pico SDK 2.1.1
- Uses PIO for precise WS2812 timing
- CH9120 handles TCP/IP stack entirely
- Dual-core RP2040 allows concurrent LED/network operations
- Serial debug output at 115200 baud

## Future Enhancements

- Multiple LED support
- Animation patterns
- Web interface
- MQTT integration
- Color persistence
- Network configuration via commands