KrakenKodersLights/INSTALLATION_GUIDE.md

# Installation Guide - D1 Mini Blinkin Emulator

## Two Ways to Install

### Option 1: PlatformIO (Recommended for VS Code Users)

#### Step 1: Install PlatformIO
1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "PlatformIO IDE"
4. Click Install
5. Restart VS Code

#### Step 2: Open the Project
1. File → Open Folder
2. Select `KrakenKodersAllianceLights` folder
3. PlatformIO will auto-detect the project

#### Step 3: Install Libraries
The libraries should install automatically when you build. If not:

**Method A: Through PlatformIO Home**
1. Click PlatformIO icon in sidebar
2. Open "PIO Home" → Libraries
3. Search for "Adafruit NeoPixel"
4. Click "Add to Project"
5. Select your project

**Method B: Manual Command**
1. Open PlatformIO Terminal (bottom toolbar)
2. Run: `pio lib install "Adafruit NeoPixel"`

#### Step 4: Configure Your Settings
Edit `src/D1Mini_Blinkin_Ready.ino`:
```cpp
#define NUM_LEDS 60        // Your LED count
#define BRIGHTNESS 100     // 0-255
```

#### Step 5: Build and Upload
1. Connect D1 Mini via USB
2. Click checkmark (✓) to build
3. Click arrow (→) to upload

### Option 2: Arduino IDE (Simpler for Beginners)

#### Step 1: Install Arduino IDE
Download from: https://www.arduino.cc/en/software

#### Step 2: Add ESP8266 Board Support
1. Open Arduino IDE
2. File → Preferences
3. In "Additional Board Manager URLs" add:
   ```
   http://arduino.esp8266.com/stable/package_esp8266com_index.json
   ```
4. Click OK
5. Tools → Board → Board Manager
6. Search "ESP8266"
7. Install "ESP8266 by ESP8266 Community"

#### Step 3: Install NeoPixel Library
1. Tools → Manage Libraries
2. Search "Adafruit NeoPixel"
3. Click Install
4. Also install any dependencies it asks for

#### Step 4: Open the Sketch
1. File → Open
2. Navigate to `D1Mini_Blinkin_Arduino.ino`

#### Step 5: Configure Board Settings
Tools menu:
- Board: "LOLIN(WEMOS) D1 R2 & mini"
- Upload Speed: 921600
- CPU Frequency: 80 MHz
- Flash Size: 4MB (FS:2MB OTA:~1019KB)
- Port: Select your COM port (appears when D1 Mini connected)

#### Step 6: Configure Your LEDs
Edit these lines in the code:
```cpp
#define NUM_LEDS 60        // Your LED count
#define BRIGHTNESS 100     // 0-255
```

#### Step 7: Upload
1. Connect D1 Mini via USB
2. Click Upload button (→)
3. Wait for "Done uploading"

## Troubleshooting

### PlatformIO Issues

**"Adafruit_NeoPixel.h not found"**
- Ensure platformio.ini contains:
  ```ini
  lib_deps = 
      adafruit/Adafruit NeoPixel@^1.11.0
  ```
- Clean and rebuild: PlatformIO → Clean, then Build

**"Platform not installed"**
- Terminal: `pio platform install espressif8266`

**Wrong COM Port**
- Add to platformio.ini:
  ```ini
  upload_port = COM3  ; Change to your port
  monitor_port = COM3
  ```

### Arduino IDE Issues

**"Board not found"**
- Ensure ESP8266 package is installed
- Restart Arduino IDE
- Select correct board from Tools → Board menu

**"Port not showing"**
- Install CH340 drivers: https://sparks.gogo.co.nz/ch340.html
- Try different USB cable (data cable, not charge-only)
- Windows: Check Device Manager for COM port

**"Upload failed"**
- Hold FLASH button on D1 Mini while uploading starts
- Release after upload begins
- Try slower upload speed (115200)

### General Issues

**LEDs not working after upload**
- Check wiring (D4 → LED Data)
- Verify LED strip has power
- Test with Serial Monitor for debug output
- Check voltage divider if using servo port

**Wrong colors or flickering**
- Some LED strips are RGB instead of GRB
- Change in code:
  ```cpp
  // From:
  Adafruit_NeoPixel strip(NUM_LEDS, LED_DATA_PIN, NEO_GRB + NEO_KHZ800);
  // To:
  Adafruit_NeoPixel strip(NUM_LEDS, LED_DATA_PIN, NEO_RGB + NEO_KHZ800);
  ```

## Testing Your Installation

### Serial Monitor Test
1. Open Serial Monitor (115200 baud)
2. Should see:
   ```
   D1 Mini Blinkin Emulator
   Kraken Koders FTC Team
   LEDs: 60
   Ready!
   ```

### LED Test
1. LEDs should show green sweep on startup
2. Without PWM input, LEDs turn off
3. With PWM input, patterns change

### Simple Blink Test
Upload this minimal test first:
```cpp
#include <Adafruit_NeoPixel.h>
#define PIN 2  // D4
#define NUMPIXELS 10

Adafruit_NeoPixel pixels(NUMPIXELS, PIN, NEO_GRB + NEO_KHZ800);

void setup() {
  pixels.begin();
  pixels.setBrightness(50);
}

void loop() {
  pixels.clear();
  pixels.setPixelColor(0, pixels.Color(255, 0, 0));
  pixels.show();
  delay(500);
  pixels.clear();
  pixels.show();
  delay(500);
}
```

## Next Steps

1. **Build the voltage divider** - See VOLTAGE_DIVIDER_BUILD_GUIDE.md
2. **Test with servo tester** - Verify PWM reading
3. **Connect to FTC robot** - Configure as servo device
4. **Customize patterns** - Add your team colors!

## Quick Command Reference

### PlatformIO Commands
```bash
pio run                  # Build
pio run -t upload        # Upload
pio run -t clean         # Clean
pio device monitor       # Serial monitor
pio lib install "name"   # Install library
```

### Arduino IDE Shortcuts
- Ctrl+R - Verify/Compile
- Ctrl+U - Upload
- Ctrl+Shift+M - Serial Monitor
- Ctrl+Shift+L - Library Manager

## Support

If you're still having issues:
1. Check all connections with multimeter
2. Try the simple blink test first
3. Enable DEBUG_MODE in code for more output
4. Verify voltage divider output is 2.5-3.3V
5. Test with different USB cable/port

Remember: The D1 Mini is 3.3V logic - never connect 5V directly to GPIO pins!