lighting-controller/test/README.md

# SPI Master Test for ESP32-C3

This directory contains test scripts to verify SPI communication between a Raspberry Pi (SPI master) and the ESP32-C3 (SPI slave).

## Quick Start

1. **Setup:** `./setup_spi.sh`
2. **Send JSON:** `pipenv run send-json --beat --brightness 128 --pattern wave`

## Hardware Connections

### Raspberry Pi GPIO Configuration
- **SCK**: GPIO11 (Physical pin 23)
- **MISO**: GPIO9 (Physical pin 21) 
- **MOSI**: GPIO10 (Physical pin 19)
- **CS**: GPIO8 (Physical pin 24)

### ESP32-C3 GPIO Configuration
- **SCK**: GPIO20
- **MISO**: GPIO9
- **MOSI**: GPIO10
- **CS**: GPIO7

## Setup

1. **Enable SPI on Raspberry Pi:**
   ```bash
   ./setup_spi.sh
   ```

2. **Flash ESP32-C3 with SPI slave firmware:**
   ```bash
   cd ../esp32
   . $HOME/esp/esp-idf/export.sh
   idf.py -p /dev/ttyUSB0 flash monitor
   ```

3. **Connect the hardware:**
   - Connect Raspberry Pi GPIO11 to ESP32-C3 GPIO20 (SCK)
   - Connect Raspberry Pi GPIO9 to ESP32-C3 GPIO9 (MISO)
   - Connect Raspberry Pi GPIO10 to ESP32-C3 GPIO10 (MOSI)
   - Connect Raspberry Pi GPIO8 to ESP32-C3 GPIO7 (CS)
   - Connect GND between both devices

## Running Tests

### Send JSON
To send your control JSON so the ESP32-C3 can `json.loads` it on the receiving side:

```bash
# Using pipenv script
pipenv run send-json --beat --brightness 128 --pattern wave

# Or directly
pipenv run python test/send_json.py --data '{"d":{"t":"b","br":128},"bar":{"pt":"off"}}'
```

Or programmatically:
```python
from test.spi_master_test import SPIMasterTest

spi = SPIMasterTest()
payload = {
    "d": {"t": "b", "br": 128, "dl": 20},
    "bar": {"pt": "off"}
}
spi.send_json(payload)
spi.cleanup()
```

Keep payloads under ~190 bytes to fit in the ESP-NOW payload.

### Individual Test Functions
The test script includes several test functions:

1. **Basic Communication Test**
   - Single byte transmission
   - Multiple byte transmission
   - Longer message transmission

2. **Data Pattern Tests**
   - All zeros
   - All ones
   - Alternating patterns
   - Incrementing/decrementing patterns

3. **Random Data Tests**
   - Random data of varying lengths
   - Multiple random tests

4. **ESP-NOW Trigger Test**
   - Sends recognizable patterns
   - Should trigger ESP-NOW broadcast on ESP32-C3
   - Verifies response patterns

5. **Stress Test**
   - Continuous communication
   - Performance measurement
   - Transaction rate calculation

## Expected Behavior

### ESP32-C3 Response
The ESP32-C3 SPI slave should:
1. Receive data on MOSI (GPIO10)
2. Log received data to serial console
3. Broadcast received data via ESP-NOW
4. Send back a test pattern (0x00, 0x01, 0x02, ...)

### Serial Monitor Output
When running the ESP32-C3, you should see output like:
```
I (1234) SPI_SLAVE: Starting SPI Slave with ESP-NOW example
I (1235) SPI_SLAVE: ESP-NOW initialized successfully
I (1236) SPI_SLAVE: SPI Slave initialized successfully
I (1237) SPI_SLAVE: MOSI: GPIO10, MISO: GPIO9, SCLK: GPIO20, CS: GPIO7
I (1238) SPI_SLAVE: Received 5 bytes:
0x48 0x65 0x6c 0x6c 0x6f 
I (1239) SPI_SLAVE: Broadcasting 5 bytes via ESP-NOW
I (1240) SPI_SLAVE: ESP-NOW send status: SUCCESS
```

## Troubleshooting

### Common Issues

1. **SPI device not found:**
   ```bash
   ls -la /dev/spi*
   # Should show /dev/spidev0.0 and /dev/spidev0.1
   ```

2. **Permission denied:**
   ```bash
   sudo usermod -a -G spi $USER
   # Log out and back in
   ```

3. **No response from ESP32-C3:**
   - Check wiring connections
   - Verify ESP32-C3 is running SPI slave firmware
   - Check serial monitor for ESP32-C3 output

4. **ESP-NOW not working:**
   - Ensure ESP32-C3 has WiFi/ESP-NOW initialized
   - Check for other ESP32-C3 devices to receive broadcasts
   - Monitor serial output for ESP-NOW status

### Debug Mode
Enable debug output by modifying the test script:
```python
# Add debug prints
print(f"SPI Mode: {spi_test.spi.mode}")
print(f"SPI Speed: {spi_test.spi.max_speed_hz}")
print(f"SPI Bits per word: {spi_test.spi.bits_per_word}")
```

## Performance Notes

- **SPI Speed**: Default 1MHz, can be increased for faster communication
- **Transaction Rate**: Typically 100-1000 transactions/second depending on data size
- **ESP-NOW Broadcast**: Adds ~1-2ms delay per transaction
- **Buffer Size**: ESP32-C3 supports up to 256 bytes per transaction

## Files

- `send_json.py` - **Main script** - Send JSON over SPI to ESP32-C3
- `quick_test.py` - Quick basic functionality test
- `spi_master_test.py` - Comprehensive test suite
- `setup_spi.sh` - Setup script for Raspberry Pi
- `requirements.txt` - Python dependencies
- `README.md` - This documentation