commit b0a1b7b2107d12145c47e94bfec4a789740f6f72
Author: Ghassan Yusuf <ghassan.yousif.83@gmail.com>
Date:   Tue Mar 24 19:25:28 2026 +0300

    Add readme.md

diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..4613f8f
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,564 @@
+# 📖 BlazePod C3 - DIY Reaction Light System
+## Complete User Documentation
+
+---
+
+## 📋 Table of Contents
+
+1. [Overview](#overview)
+2. [Hardware Requirements](#hardware-requirements)
+3. [Wiring Diagram](#wiring-diagram)
+4. [Software Setup](#software-setup)
+5. [Configuration](#configuration)
+6. [BLE Commands Reference](#ble-commands-reference)
+7. [Using the Device](#using-the-device)
+8. [Mobile App Testing](#mobile-app-testing)
+9. [Troubleshooting](#troubleshooting)
+10. [Advanced Features](#advanced-features)
+
+---
+
+## 🎯 Overview
+
+**BlazePod C3** is a DIY reaction light training system inspired by commercial products like BlazePod. It uses an ESP32-C3 microcontroller to create a wireless, Bluetooth-controlled LED pod that measures reaction time with **millisecond accuracy**.
+
+### Key Features
+- ✅ **Wireless BLE 5.0** control
+- ✅ **Millisecond-accurate** reaction timing
+- ✅ **Customizable RGB colors** via mobile app
+- ✅ **Multiple trigger options**: Piezo (slap), Button (press), Accelerometer (shake)
+- ✅ **Smooth breathing animations**
+- ✅ **Modular design** - enable/disable sensors as needed
+- ✅ **Low power consumption**
+
+---
+
+## 🔧 Hardware Requirements
+
+### Required Components
+
+| Component | Quantity | Notes |
+| :--- | :--- | :--- |
+| **ESP32-C3 Super Mini** | 1 | Main controller |
+| **WS2812B NeoPixel Ring (12 LEDs)** | 1 | 5V, 12-LED ring |
+| **Piezo Disc** | 1 | Optional - for slap detection |
+| **Momentary Push Button** | 1 | Optional - for press detection |
+| **ADXL335 Accelerometer** | 1 | Optional - for shake detection |
+| **1M Ω Resistor** | 1 | For piezo sensor |
+| **3.7V LiPo Battery** | 1 | 500-1000mAh recommended |
+| **TP4056 Charging Module** | 1 | Battery charging |
+| **Slide Switch** | 1 | On/Off power switch |
+
+### Tools Needed
+- Soldering iron & solder
+- USB-C cable (data-capable)
+- Wire cutters/strippers
+- Hot glue gun
+- 3D printer (optional, for case)
+
+---
+
+## 🔌 Wiring Diagram
+
+### ESP32-C3 Super Mini Pinout
+
+| Component | ESP32-C3 Pin | Notes |
+| :--- | :--- | :--- |
+| **NeoPixel Data** | **GPIO 3** | DIN pin on ring |
+| **NeoPixel VCC** | **5V** (VIN) | Use 5V for brightness |
+| **NeoPixel GND** | **GND** | Common ground |
+| **Piezo (+)** | **GPIO 4** | With 1M Ω resistor to GND |
+| **Piezo (-)** | **GND** | |
+| **Button (Leg 1)** | **GPIO 5** | |
+| **Button (Leg 2)** | **GND** | No resistor needed (internal pullup) |
+| **Accel X** | **GPIO 6** | ADXL335 X-Out |
+| **Accel Y** | **GPIO 7** | ADXL335 Y-Out |
+| **Accel Z** | **GPIO 0** | ADXL335 Z-Out |
+| **Accel VCC** | **3.3V** | ⚠️ **3.3V ONLY!** |
+| **Accel GND** | **GND** | |
+
+### Wiring Schematic
+
+```
+ESP32-C3 Super Mini
+┌─────────────────┐
+│   GPIO 3  ──────┼──> NeoPixel DIN
+│   5V      ──────┼──> NeoPixel VCC
+│   GND     ──────┼──> NeoPixel GND, Piezo (-), Button (Leg 2)
+│   GPIO 4  ──────┼──> Piezo (+) [with 1MΩ to GND]
+│   GPIO 5  ──────┼──> Button (Leg 1)
+│   GPIO 6  ────────> ADXL335 X
+│   GPIO 7  ──────┼──> ADXL335 Y
+│   GPIO 0  ──────┼──> ADXL335 Z
+│   3.3V    ──────┼──> ADXL335 VCC
+└─────────────────┘
+```
+
+---
+
+## 💻 Software Setup
+
+### Step 1: Install Arduino IDE
+Download from: https://www.arduino.cc/en/software
+
+### Step 2: Add ESP32 Board Support
+
+1. Open **Arduino IDE**
+2. Go to **File > Preferences**
+3. Add this URL to **"Additional Board Manager URLs"**:
+   ```
+   https://espressif.github.io/arduino-esp32/package_esp32_index.json
+   ```
+4. Go to **Tools > Board > Boards Manager**
+5. Search for **"esp32"**
+6. Install **"esp32 by Espressif Systems"** (version 2.0.9 or higher)
+
+### Step 3: Install Required Libraries
+
+1. Go to **Sketch > Include Library > Manage Libraries**
+2. Search and install:
+   - **Adafruit NeoPixel** by Adafruit
+
+### Step 4: Select Board Settings
+
+1. **Tools > Board**: Select **"ESP32C3 Dev Module"**
+2. **Tools > USB CDC On Boot**: **"Enabled"**
+3. **Tools > Partition Scheme**: **"Default 4MB with spiffs"**
+4. **Tools > Port**: Select your ESP32-C3 port
+
+### Step 5: Upload Code
+
+1. Copy the full code into Arduino IDE
+2. Click **Verify** (✓) to compile
+3. **Hold BOOT button** on ESP32-C3
+4. **Press RESET** (or plug in USB while holding BOOT)
+5. Click **Upload** (→)
+6. Release BOOT button when you see "Connecting..."
+7. Press **RESET** once after upload completes
+
+---
+
+## ⚙️ Configuration
+
+### Enable/Disable Sensors
+
+At the top of the code, you'll find:
+
+```cpp
+// --- Feature Toggles (Comment to disable) ---
+#define FEATURE_PIEZO
+#define FEATURE_BUTTON
+#define FEATURE_ACCEL
+```
+
+**To enable a feature**: Leave the line as is (uncommented)  
+**To disable a feature**: Add `//` at the beginning
+
+#### Example Configurations
+
+**Button Only (Quiet Mode)**
+```cpp
+//#define FEATURE_PIEZO
+#define FEATURE_BUTTON
+//#define FEATURE_ACCEL
+```
+
+**Slap Only (Classic Mode)**
+```cpp
+#define FEATURE_PIEZO
+//#define FEATURE_BUTTON
+//#define FEATURE_ACCEL
+```
+
+**Full Features (All Triggers)**
+```cpp
+#define FEATURE_PIEZO
+#define FEATURE_BUTTON
+#define FEATURE_ACCEL
+```
+
+### Adjust Sensitivity
+
+```cpp
+#ifdef FEATURE_PIEZO
+  #define PIEZO_THRESHOLD   1500    // Higher = less sensitive
+#endif
+
+#ifdef FEATURE_BUTTON
+  #define BUTTON_THRESHOLD  100     // Not used (digital read)
+#endif
+
+#ifdef FEATURE_ACCEL
+  #define ACCEL_THRESHOLD   150     // Higher = less sensitive
+#endif
+```
+
+### Change Device Name
+
+```cpp
+#define DEVICE_NAME         "BlazeC3_Pod_01"
+```
+
+Change to any name (max 15 characters).
+
+### Adjust LED Brightness
+
+```cpp
+#define BRIGHTNESS          50      // 0-255 (0=off, 255=brightest)
+#define BREATHE_MAX         40      // Max brightness for breathing effect
+```
+
+---
+
+## 📱 BLE Commands Reference
+
+### Connection Details
+
+| Parameter | Value |
+| :--- | :--- |
+| **Device Name** | `BlazeC3_Pod_01` (or your custom name) |
+| **Service UUID** | `4fafc201-1fb5-459e-8fcc-c5c9c331914b` |
+| **Characteristic UUID** | `beb5483e-36e1-4688-b7f5-ea07361b26a8` |
+
+### Game Control Commands
+
+| Command | Description | Response |
+| :--- | :--- | :--- |
+| `START` | Start reaction test | `OK:STARTED` |
+| `RESET` | Stop game, return to connected state | `OK:RESET` |
+
+### Color Configuration Commands
+
+**Format**: `COLOR_NAME:R,G,B` where R,G,B are 0-255
+
+| Command | Example | Description |
+| :--- | :--- | :--- |
+| `COLOR_WAIT:0,0,255` | Blue breathing when waiting for connection |
+| `COLOR_CONN:0,255,255` | Cyan when connected, ready |
+| `COLOR_ACTIVE:255,0,0` | Red when game active (wait for trigger) |
+| `COLOR_SUCCESS:0,255,0` | Green when triggered (success) |
+
+**Responses**: `OK:COLOR_NAME:R,G,B`
+
+### Utility Commands
+
+| Command | Description | Response Example |
+| :--- | :--- | :--- |
+| `GET_COLORS` | Get all current colors | `COLORS\|WAIT:0,0,255\|CONN:0,255,255\|ACTIVE:255,0,0\|SUCCESS:0,255,0` |
+| `RESET_COLORS` | Reset to default colors | `OK:COLORS_RESET` |
+
+### Automatic Notifications
+
+| Notification | When Sent |
+| :--- | :--- |
+| `RESULT:245ms` | When trigger detected (reaction time) |
+| `OK:STARTED` | When game starts |
+| `OK:RESET` | When game resets |
+
+---
+
+## 🎮 Using the Device
+
+### Basic Workflow
+
+1. **Power On**
+   - Turn on the slide switch
+   - LEDs perform **rainbow spin** (2 seconds)
+   - LEDs enter **breathing blue** mode (waiting for connection)
+
+2. **Connect via Bluetooth**
+   - Open nRF Connect or your mobile app
+   - Scan for `BlazeC3_Pod_01`
+   - Tap **CONNECT**
+   - LEDs turn **solid cyan** (connected)
+
+3. **Customize Colors** (Optional)
+   - Send `COLOR_ACTIVE:255,0,255` for purple active color
+   - Send `GET_COLORS` to verify
+
+4. **Start Reaction Test**
+   - Send `START`
+   - LEDs turn **red** (or your custom active color)
+   - **Wait for the light...**
+
+5. **Trigger the Pod**
+   - **Slap** it (if piezo enabled)
+   - **Press** the button (if button enabled)
+   - **Shake** it (if accelerometer enabled)
+   - LEDs turn **green** (success)
+
+6. **View Result**
+   - Check notification: `RESULT:245ms`
+   - Lower = faster reaction time!
+
+7. **Repeat**
+   - Send `START` again for another round
+   - Or send `RESET` to stop
+
+### State Indicators
+
+| LED Behavior | State | Meaning |
+| :--- | :--- | :--- |
+| 🌈 Rainbow spin | Boot | Starting up |
+| 💙 Breathing blue | Waiting | No Bluetooth connection |
+| 💚 Solid cyan | Connected | Ready to train |
+| 🔴 Solid red | Active | Game started - wait for trigger |
+| 🟢 Solid green | Success | Triggered! Showing result |
+
+---
+
+## 📲 Mobile App Testing
+
+### Using nRF Connect (Android/iOS)
+
+**Download**: 
+- [Android](https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp)
+- [iOS](https://apps.apple.com/us/app/nrf-connect-for-mobile/id1054362403)
+
+#### Step-by-Step Testing
+
+1. **Open nRF Connect**
+2. **Scan** for devices
+3. **Find** `BlazeC3_Pod_01`
+4. **Tap CONNECT**
+5. **Expand** "Unknown Service" (`4fafc201...`)
+6. **Enable Notifications**:
+   - Tap the **up arrow** (↗️) on the characteristic
+   - Select **"Indicate"** or **"Notify"**
+7. **Send Commands**:
+   - Tap the **down arrow** (↙️) or **pencil icon** (✏️)
+   - Type command (e.g., `START`)
+   - Select **"UTF-8"** or **"TEXT"** format
+   - Tap **SEND**
+8. **View Results**:
+   - Notifications appear below the characteristic
+   - Look for `RESULT:XXXms`
+
+#### Quick Test Sequence
+
+```
+1. GET_COLORS          → Verify current colors
+2. COLOR_ACTIVE:255,0,255  → Set purple active color
+3. START               → Begin test
+4. [Press button]      → Trigger
+5. [See RESULT:XXXms]  → Check time
+6. RESET               → Stop
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### LED Issues
+
+**Problem**: LEDs don't turn on  
+**Solution**:
+- Check 5V power connection
+- Verify `BRIGHTNESS` is not set to 0
+- Ensure NeoPixel DIN is on GPIO 3
+
+**Problem**: LEDs flicker or show wrong colors  
+**Solution**:
+- Add 1000μF capacitor across NeoPixel VCC/GND
+- Add 330Ω resistor on data line (GPIO 3)
+- Check power supply (use 5V, not 3.3V)
+
+### Button Issues
+
+**Problem**: Button triggers immediately after START  
+**Solution**:
+- Check wiring: Button leg 1 to GPIO 5, leg 2 to GND
+- Verify `FEATURE_BUTTON` is enabled
+- Open Serial Monitor, check button value when NOT pressed (should be HIGH/1)
+- If reading LOW/0 when not pressed, check for loose wires
+
+**Problem**: Button doesn't trigger  
+**Solution**:
+- Test with multimeter: Should read 0V when pressed, 3.3V when released
+- Try increasing `BUTTON_THRESHOLD` (though digital read shouldn't need this)
+- Check if `FEATURE_BUTTON` is commented out
+
+### Piezo Issues
+
+**Problem**: Piezo too sensitive (triggers on its own)  
+**Solution**:
+- Increase `PIEZO_THRESHOLD` (try 2000-3000)
+- Ensure 1M Ω resistor is connected between GPIO 4 and GND
+- Check for loose wires picking up noise
+
+**Problem**: Piezo not sensitive enough  
+**Solution**:
+- Decrease `PIEZO_THRESHOLD` (try 800-1200)
+- Open Serial Monitor, slap piezo, note the value
+- Set threshold between idle value and slap value
+
+### Accelerometer Issues
+
+**Problem**: Triggers without movement  
+**Solution**:
+- Increase `ACCEL_THRESHOLD` (try 200-300)
+- Ensure ADXL335 is powered by **3.3V** (not 5V!)
+- Check wiring is secure
+
+**Problem**: Doesn't trigger on shake  
+**Solution**:
+- Decrease `ACCEL_THRESHOLD` (try 80-120)
+- Verify ADXL335 is working (check X/Y/Z values in Serial Monitor)
+- Shake harder!
+
+### Bluetooth Issues
+
+**Problem**: Can't find device  
+**Solution**:
+- Ensure device is powered (LEDs breathing blue)
+- Move closer to phone (within 5 meters)
+- Restart ESP32-C3 (press RESET)
+- Check if already connected to another device
+
+**Problem**: Can't send commands  
+**Solution**:
+- Enable **Notifications** on the characteristic
+- Use **UTF-8** or **TEXT** format (not HEX)
+- Don't include quotes: `START` not `"START"`
+- Check if device is connected (LEDs solid cyan)
+
+**Problem**: Commands not working  
+**Solution**:
+- Check Serial Monitor for "Received: [COMMAND]"
+- Verify command spelling (case-sensitive: `START` not `start`)
+- Enable notifications to see responses
+
+### Serial Monitor Debugging
+
+**Open Serial Monitor**:
+- Baud rate: **115200**
+- Line ending: **Newline** or **Both NL & CR**
+
+**What to look for**:
+```
+================================
+  BlazePod C3 - Production Ready
+================================
+Piezo:   OFF
+Button:  ON
+Accel:   OFF
+================================
+System Ready - Waiting for connection...
+Device Connected
+Received: [START]
+Game Started
+Trigger: Button
+Reaction Time: 245ms
+```
+
+---
+
+## 🚀 Advanced Features
+
+### Building a Mobile App
+
+For a production app, you can use:
+- **Flutter** (cross-platform)
+- **React Native** (cross-platform)
+- **Swift** (iOS only)
+- **Kotlin** (Android only)
+
+**Key BLE Libraries**:
+- Flutter: `flutter_blue_plus`
+- React Native: `react-native-ble-plx`
+
+### Multiple Pods Setup
+
+To build **6 pods** for group training:
+
+1. **Change device names**:
+   ```cpp
+   #define DEVICE_NAME "BlazeC3_Pod_01"  // Pod 1
+   #define DEVICE_NAME "BlazeC3_Pod_02"  // Pod 2
+   // etc.
+   ```
+
+2. **Connect to all pods** in your app
+3. **Send START to all** simultaneously
+4. **Collect results** from each pod
+
+### Power Optimization
+
+**Extend battery life**:
+- Reduce `BRIGHTNESS` to 30-40
+- Reduce `BREATHE_MAX` to 20
+- Add deep sleep after 10 minutes of inactivity
+- Use smaller battery (300mAh) for lighter weight
+
+### 3D Printed Case
+
+**Design considerations**:
+- **Diameter**: 100-120mm (to fit 12-LED ring)
+- **Height**: 20-30mm (for ESP32-C3 + battery)
+- **Diffuser**: 1-2mm thick milky white PLA over LEDs
+- **Mounting**: Magnets or velcro on bottom
+- **Button access**: Hole or membrane over button
+- **Charging port**: USB-C access hole
+
+**Recommended settings**:
+- Infill: 20%
+- Layer height: 0.2mm
+- Material: PLA or PETG
+
+---
+
+## 📊 Performance Specifications
+
+| Metric | Value |
+| :--- | :--- |
+| **Reaction Time Accuracy** | ±1ms |
+| **BLE Range** | 10-40 meters (open space) |
+| **Battery Life** | 4-8 hours (typical use) |
+| **Charging Time** | 2-3 hours |
+| **LED Refresh Rate** | 100 Hz |
+| **Touch Response Time** | <5ms |
+| **BLE Latency** | 10-20ms (not included in reaction time) |
+
+---
+
+## 📞 Support & Resources
+
+### Code Repository
+- GitHub: [Your Repo Link]
+
+### Community
+- Arduino Forum: https://forum.arduino.cc/
+- ESP32 Discord: https://discord.gg/esp32
+
+### Tutorials
+- ESP32-C3 Getting Started: https://docs.espressif.com/
+- NeoPixel Guide: https://learn.adafruit.com/adafruit-neopixel-uberguide
+- BLE GATT Tutorial: https://www.bluetooth.com/specifications/gatt/
+
+---
+
+## 📄 License
+
+This project is open-source. Feel free to modify, distribute, and use for personal or commercial projects.
+
+---
+
+## ✅ Quick Start Checklist
+
+- [ ] Solder all components
+- [ ] Install Arduino IDE & ESP32 board support
+- [ ] Install Adafruit NeoPixel library
+- [ ] Configure features (comment/uncomment defines)
+- [ ] Upload code to ESP32-C3
+- [ ] Open Serial Monitor, verify boot message
+- [ ] Download nRF Connect app
+- [ ] Connect to `BlazeC3_Pod_01`
+- [ ] Enable notifications
+- [ ] Send `START`
+- [ ] Trigger the pod
+- [ ] See `RESULT:XXXms`
+- [ ] **You're ready to train!** 🎉
+
+---
+
+**Happy Training! 💪🔥**
\ No newline at end of file