# Getting Started with OpenParanormal Builds

Complete beginner's guide to building your first ghost hunting device.

---

## Prerequisites

### Hardware You Need
1. ESP32 DevKit board
2. USB cable (Micro-USB or USB-C depending on board)
3. Computer (Windows, Mac, or Linux)
4. Breadboard and jumper wires (for testing)

### Software You Need
1. Arduino IDE (free download)
2. USB drivers (if needed)
3. Libraries (we'll install these)

---

## Step 1: Install Arduino IDE

### Download
1. Go to: https://www.arduino.cc/en/software
2. Download for your operating system (Windows, Mac, Linux)
3. Install following default prompts

### First Launch
1. Open Arduino IDE
2. You should see a blank sketch with `setup()` and `loop()`

---

## Step 2: Add ESP32 Board Support

The ESP32 is not included by default in Arduino IDE.

### Installation Steps

1. **Open Preferences**
   - Windows/Linux: File → Preferences
   - Mac: Arduino → Preferences

2. **Add Board Manager URL**
   - Find "Additional Board Manager URLs" field
   - Paste this URL:
   ```
   https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
   ```
   - Click OK

3. **Install ESP32 Boards**
   - Go to: Tools → Board → Boards Manager
   - Search: "esp32"
   - Find "esp32 by Espressif Systems"
   - Click Install
   - Wait for download (may take a few minutes)

4. **Select Your Board**
   - Go to: Tools → Board → ESP32 Arduino
   - Select: "ESP32 Dev Module" (works for most ESP32 boards)

5. **Select COM Port**
   - Plug in your ESP32 via USB
   - Go to: Tools → Port
   - Select the new port that appeared (e.g., COM3, /dev/ttyUSB0)

### Troubleshooting Drivers

**If ESP32 not detected:**

- **CH340G Chip** (most clone boards):
  - Windows: Download CH340 driver
  - Mac: May need to allow in Security settings
  - Linux: Usually works automatically

- **CP2102 Chip**:
  - Download from Silicon Labs website
  - Install driver
  - Restart computer

---

## Step 3: Test Your ESP32 - Blink LED

Let's make sure everything works!

### Code

```cpp
// Built-in LED is usually on GPIO 2
#define LED_PIN 2

void setup() {
  // Set LED pin as output
  pinMode(LED_PIN, OUTPUT);
}

void loop() {
  digitalWrite(LED_PIN, HIGH);  // Turn LED on
  delay(1000);                  // Wait 1 second
  digitalWrite(LED_PIN, LOW);   // Turn LED off
  delay(1000);                  // Wait 1 second
}
```

### Upload Steps

1. Copy code into Arduino IDE
2. Click "Verify" (checkmark icon) - should compile without errors
3. Click "Upload" (arrow icon)
4. Watch for "Connecting..." message
5. **If stuck:** Hold BOOT button on ESP32, then click Upload again
6. Wait for "Done uploading"
7. Look at ESP32 - small LED should blink!

### Troubleshooting Upload

**"Failed to connect":**
- Try different USB cable (data cable, not charge-only)
- Hold BOOT button during upload
- Check correct COM port selected
- Try lower upload speed: Tools → Upload Speed → 115200

**"Error compiling":**
- Make sure ESP32 board selected (not Arduino Uno)
- Check board manager installed ESP32 support

---

## Step 4: Install Required Libraries

Libraries add functionality for sensors, displays, etc.

### How to Install Libraries

**Method 1: Library Manager (Easiest)**
1. Go to: Sketch → Include Library → Manage Libraries
2. Search for library name
3. Click Install

**Method 2: ZIP File**
1. Download .zip file
2. Go to: Sketch → Include Library → Add .ZIP Library
3. Select downloaded file

### Core Libraries to Install Now

Install these via Library Manager:

1. **TFT_eSPI** (for touchscreen displays)
   - Search: "TFT_eSPI"
   - By: Bodmer
   - Used in: Spirit Box, Ovilus, Multi-Tool

2. **Adafruit BME280** (temperature/humidity sensor)
   - Search: "Adafruit BME280"
   - Also install dependencies when prompted
   - Used in: Ovilus, REM Pod

3. **Radio** (for FM radio modules)
   - Search: "Radio by Matthias Hertel"
   - Used in: Spirit Box

4. **Adafruit NeoPixel** (for LED rings/strips)
   - Search: "Adafruit NeoPixel"
   - Used in: REM Pod

5. **DFRobotDFPlayerMini** (for MP3 playback)
   - Search: "DFRobotDFPlayerMini"
   - Used in: Ovilus, BooBuddy

---

## Step 5: Configure TFT_eSPI for Your Display

**IMPORTANT:** TFT_eSPI needs configuration for your specific display!

### Find User_Setup.h File

**Windows:**
```
C:\Users\YourName\Documents\Arduino\libraries\TFT_eSPI\User_Setup.h
```

**Mac:**
```
~/Documents/Arduino/libraries/TFT_eSPI/User_Setup.h
```

**Linux:**
```
~/Arduino/libraries/TFT_eSPI/User_Setup.h
```

### Configuration for 2.8" ILI9341 Display

Open `User_Setup.h` in a text editor, find these lines and set them:

```cpp
// Uncomment this line:
#define ILI9341_DRIVER

// Set these pin numbers for ESP32:
#define TFT_CS   15  // Chip select
#define TFT_DC   2   // Data/Command
#define TFT_RST  4   // Reset
#define TFT_MOSI 23  // SPI Data
#define TFT_SCLK 18  // SPI Clock
#define TFT_MISO 19  // SPI MISO

// Touchscreen (if using)
#define TOUCH_CS 21
```

**Note:** Pin numbers may vary by display module. Check your display's documentation!

### Test Display

After configuring, try this example:
- File → Examples → TFT_eSPI → 160x128 → TFT_graphicstest_small
- Upload to ESP32 with display connected
- Should show colorful test patterns

---

## Step 6: Understanding Arduino Code Structure

### Basic Structure

```cpp
// 1. INCLUDES - Load libraries
#include <Wire.h>
#include <TFT_eSPI.h>

// 2. DEFINES - Constants
#define LED_PIN 2
#define BUTTON_PIN 4

// 3. GLOBAL VARIABLES - Accessible everywhere
TFT_eSPI tft = TFT_eSPI();
int counter = 0;

// 4. SETUP - Runs ONCE when ESP32 starts
void setup() {
  Serial.begin(115200);  // Start serial monitor
  pinMode(LED_PIN, OUTPUT);
  pinMode(BUTTON_PIN, INPUT_PULLUP);

  tft.init();
  tft.fillScreen(TFT_BLACK);

  Serial.println("Setup complete!");
}

// 5. LOOP - Runs FOREVER (continuously)
void loop() {
  if (digitalRead(BUTTON_PIN) == LOW) {
    digitalWrite(LED_PIN, HIGH);
    Serial.println("Button pressed!");
  } else {
    digitalWrite(LED_PIN, LOW);
  }

  delay(100);  // Small delay
}
```

### Key Concepts

**setup():**
- Runs once when powered on or reset
- Initialize sensors, displays, pins
- Set pin modes (INPUT, OUTPUT, INPUT_PULLUP)

**loop():**
- Runs continuously forever
- Read sensors
- Update display
- Check buttons
- Make decisions

**Serial Monitor:**
- View debug messages
- Tools → Serial Monitor
- Set baud rate to match `Serial.begin(115200)`

---

## Step 7: Simple Sensor Test - Temperature Display

Let's read a BME280 sensor and show on Serial Monitor.

### Wiring (Breadboard)

```
BME280 → ESP32
VCC    → 3.3V
GND    → GND
SCL    → GPIO 22 (I2C Clock)
SDA    → GPIO 21 (I2C Data)
```

### Code

```cpp
#include <Wire.h>
#include <Adafruit_Sensor.h>
#include <Adafruit_BME280.h>

Adafruit_BME280 bme;

void setup() {
  Serial.begin(115200);
  Serial.println("BME280 Test");

  if (!bme.begin(0x76)) {  // 0x76 or 0x77 depending on sensor
    Serial.println("Could not find BME280 sensor!");
    while (1);  // Stop here
  }

  Serial.println("BME280 found!");
}

void loop() {
  float temperature = bme.readTemperature();  // Celsius
  float humidity = bme.readHumidity();        // %
  float pressure = bme.readPressure() / 100.0F;  // hPa

  Serial.print("Temp: ");
  Serial.print(temperature);
  Serial.print(" °C | Humidity: ");
  Serial.print(humidity);
  Serial.print(" % | Pressure: ");
  Serial.print(pressure);
  Serial.println(" hPa");

  delay(2000);  // Update every 2 seconds
}
```

### Test
1. Wire BME280 to ESP32
2. Upload code
3. Open Serial Monitor (Tools → Serial Monitor)
4. Set baud rate to 115200
5. Should see temperature readings!

**Troubleshooting:**
- "Could not find sensor": Check wiring, try 0x77 instead of 0x76
- No output: Check baud rate matches code

---

## Step 8: Your First Build - Simple EMF Meter

Now let's build something useful!

### What You Need
- ESP32
- 5x LEDs (different colors)
- 5x 220Ω resistors
- Hall effect sensor (e.g., A3144) OR simple wire coil
- Breadboard and jumper wires

### Wiring

```
LED 1 (Green)  → GPIO 13 → 220Ω resistor → GND
LED 2 (Yellow) → GPIO 12 → 220Ω resistor → GND
LED 3 (Orange) → GPIO 14 → 220Ω resistor → GND
LED 4 (Red)    → GPIO 27 → 220Ω resistor → GND
LED 5 (Red)    → GPIO 26 → 220Ω resistor → GND

Hall Sensor:
VCC → 3.3V
GND → GND
OUT → GPIO 34 (analog input)
```

### Code

See `firmware/emf-meter/simple_emf_meter.ino` for full code.

### How It Works
1. Reads analog value from hall sensor
2. Higher EMF = higher voltage
3. Lights LEDs based on strength
4. Just like commercial K2 meter!

---

## Step 9: Next Steps

### Beginner Path
1. ✅ Blink LED (you did this!)
2. ✅ Read sensor (BME280 test)
3. ✅ Build EMF meter
4. 🔲 Add OLED display to EMF meter
5. 🔲 Build REM Pod with LED ring
6. 🔲 Build Spirit Box with touchscreen

### Intermediate Path
1. Build Ovulus with touchscreen UI
2. Add word database
3. Combine multiple sensors

### Advanced Path
1. Multi-function ghost hunter tool
2. WiFi data logging
3. Custom 3D printed enclosure

---

## Helpful Resources

### Websites
- **Arduino Reference:** https://www.arduino.cc/reference/en/
- **ESP32 Docs:** https://docs.espressif.com/projects/arduino-esp32/
- **Random Nerd Tutorials:** https://randomnerdtutorials.com/projects-esp32/

### Debugging Tips

**Serial Monitor is your friend!**
```cpp
Serial.println("Debug message here");
Serial.print("Variable value: ");
Serial.println(myVariable);
```

**Common Issues:**
- Sensor not working: Check I2C address (0x76 vs 0x77)
- Display blank: Check TFT_eSPI configuration
- Upload fails: Hold BOOT button
- Crashes: Add delays, check power supply

### Community Help
- Arduino Forum: https://forum.arduino.cc/
- ESP32 Reddit: r/esp32
- This project's issues: [link when available]

---

## Safety Notes

- ESP32 runs on 3.3V logic (not 5V)
- Don't connect 5V to GPIO pins
- Use resistors with LEDs (220Ω is safe)
- Unplug when wiring
- Double-check polarity (GND, VCC)

---

## Ready to Build?

Choose your first project:

1. **Easiest:** EMF Meter → `BUILD_GUIDES/02_EMF_METER.md`
2. **Most Fun:** REM Pod with LED Ring → `BUILD_GUIDES/03_REM_POD.md`
3. **Most Impressive:** Spirit Box with Touchscreen → `BUILD_GUIDES/04_SPIRIT_BOX.md`

Let's build some ghost hunting gear! 👻