# Universal Buffer Reader EA - Quick Start Guide

**Version**: 2.0
**Date**: 2025-01-20

---

## Overview

The Universal Buffer Reader EA is a sophisticated MetaTrader 5 Expert Advisor that reads custom indicator buffers to generate trading signals. It features advanced risk management, partial position closing, breakeven, trailing stops, and state persistence.

**Key Features**:
- ✅ Custom indicator signal detection
- ✅ Multiple take profit levels with partial closing
- ✅ Breakeven and trailing stop management
- ✅ Time-based trading filters
- ✅ Daily profit target enforcement
- ✅ State persistence across EA restarts
- ✅ Manual trading mode with chart controls
- ✅ Smart logging with error deduplication

---

## Installation

### Step 1: Copy Files to MetaTrader 5

1. Navigate to your MetaTrader 5 data folder:
   - **Windows**: `C:\Users\{Username}\AppData\Roaming\MetaQuotes\Terminal\{TerminalID}\MQL5\`
   - **Mac**: `Open MetaTrader 5 → File → Open Data Folder`

2. Copy the following files:
   ```
   Universal_Buffer_Reader_EA.mq5 → MQL5/Experts/
   Include/LoggingManager.mqh → MQL5/Include/
   Include/SignalDetector.mqh → MQL5/Include/
   Include/TimeFilter.mqh → MQL5/Include/
   Include/MoneyManager.mqh → MQL5/Include/
   Include/RiskManager.mqh → MQL5/Include/
   Include/PartialCloseManager.mqh → MQL5/Include/
   Include/TradeExecutor.mqh → MQL5/Include/
   Include/StateManager.mqh → MQL5/Include/
   Include/UIManager.mqh → MQL5/Include/
   ```

3. Copy your custom indicator file:
   ```
   YourIndicator.ex5 → MQL5/Indicators/
   ```

### Step 2: Compile the EA

1. Open MetaEditor 5 (press F4 in MetaTrader 5)
2. Open `Universal_Buffer_Reader_EA.mq5`
3. Press F7 or click "Compile"
4. Verify no errors in the "Errors" tab
5. Close MetaEditor 5

### Step 3: Enable Algorithmic Trading

1. In MetaTrader 5, go to **Tools → Options → Expert Advisors**
2. Check **"Allow algorithmic trading"**
3. Check **"Allow DLL imports"** (if your indicator requires it)
4. Click OK

---

## Quick Configuration

### Option 1: Indicator Mode (Recommended)

1. Open a chart (e.g., EURUSD H1)
2. Drag `Universal_Buffer Reader EA` from Navigator → Expert Advisors
3. Click on the chart to open EA settings
4. Configure the following essential parameters:

   **General Settings**:
   - `Trade_Mode`: `MODE_INDICATOR`
   - `LotSize`: `0.03` (or your preferred lot size)
   - `MagicNumber`: `24680` (or any unique number)
   - `EnableDebugPrints`: `true` (for testing)

   **Signal Detection**:
   - `IndicatorName`: `"Your Indicator Name"` (exact name)
   - `BuySignalBuffer`: `0` (buffer with buy signals)
   - `SellSignalBuffer`: `1` (buffer with sell signals)
   - `BuySLBuffer`: `2` (buffer with buy SL)
   - `BuyTP1Buffer`: `3` (buffer with buy TP1)
   - `BuyTP2Buffer`: `4` (buffer with buy TP2)
   - `BuyTP3Buffer`: `5` (buffer with buy TP3)
   - `SellSLBuffer`: `6` (buffer with sell SL)
   - `SellTP1Buffer`: `7` (buffer with sell TP1)
   - `SellTP2Buffer`: `8` (buffer with sell TP2)
   - `SellTP3Buffer`: `9` (buffer with sell TP3)

5. Click OK
6. Click the "AutoTrading" button in the toolbar (should be green)

### Option 2: Manual Mode

1. Open a chart
2. Drag `Universal Buffer Reader EA` from Navigator → Expert Advisors
3. Configure:
   - `Trade_Mode`: `MODE_MANUAL`
   - `LotSize`: `0.03`
   - `MagicNumber`: `24680`
4. Click OK
5. Click "AutoTrading" button
6. Use the Buy/Sell buttons that appear on the chart

---

## Indicator Buffer Setup

Your custom indicator must provide the following buffers:

| Buffer Index | Purpose | Description |
|--------------|---------|-------------|
| 0 | Buy Signal | Price level for buy entry (0 = no signal) |
| 1 | Sell Signal | Price level for sell entry (0 = no signal) |
| 2 | Buy SL | Stop loss for buy orders |
| 3 | Buy TP1 | First take profit for buy orders |
| 4 | Buy TP2 | Second take profit for buy orders |
| 5 | Buy TP3 | Third take profit for buy orders |
| 6 | Sell SL | Stop loss for sell orders |
| 7 | Sell TP1 | First take profit for sell orders |
| 8 | Sell TP2 | Second take profit for sell orders |
| 9 | Sell TP3 | Third take profit for sell orders |

**Example Indicator Code**:
```mql5
//+------------------------------------------------------------------+
//| Custom Indicator Example                                          |
//+------------------------------------------------------------------+
#property indicator_buffers 10
#property indicator_plots   2

double BuySignalBuffer[];
double SellSignalBuffer[];
double BuySLBuffer[];
double BuyTP1Buffer[];
double BuyTP2Buffer[];
double BuyTP3Buffer[];
double SellSLBuffer[];
double SellTP1Buffer[];
double SellTP2Buffer[];
double SellTP3Buffer[];

int OnInit() {
    SetIndexBuffer(0, BuySignalBuffer);
    SetIndexBuffer(1, SellSignalBuffer);
    SetIndexBuffer(2, BuySLBuffer);
    SetIndexBuffer(3, BuyTP1Buffer);
    SetIndexBuffer(4, BuyTP2Buffer);
    SetIndexBuffer(5, BuyTP3Buffer);
    SetIndexBuffer(6, SellSLBuffer);
    SetIndexBuffer(7, SellTP1Buffer);
    SetIndexBuffer(8, SellTP2Buffer);
    SetIndexBuffer(9, SellTP3Buffer);
    return(INIT_SUCCEEDED);
}

int OnCalculate(const int rates_total,
                const int prev_calculated,
                const datetime &time[],
                const double &open[],
                const double &high[],
                const double &low[],
                const double &close[],
                const long &tick_volume[],
                const long &volume[],
                const int &spread[]) {

    // Your signal logic here
    // Example: Simple moving average crossover
    // ...

    return(rates_total);
}
```

---

## Monitoring the EA

### Chart Information

When the EA is running, you'll see:

1. **Loss Display** (top-left corner):
   - Accumulated Loss: $X.XX
   - Consecutive Losses: X

2. **Manual Mode Controls** (if in manual mode):
   - Buy button
   - Sell button

### Experts Tab

Monitor the Experts tab for:
- Trade execution messages
- Error messages (with deduplication)
- Debug information (if enabled)

### Journal Tab

Monitor the Journal tab for:
- EA initialization messages
- EA deinitialization messages
- System-level errors

---

## Common Tasks

### Stop the EA

1. Click the "AutoTrading" button in the toolbar (should turn red)
2. Or right-click on chart → Expert Advisors → Remove

### Change Settings

1. Right-click on chart → Expert Advisors → Properties
2. Modify parameters
3. Click OK
4. EA will restart with new settings

### View Open Positions

1. Go to Terminal tab → Trade
2. Filter by MagicNumber to see EA trades

### Close All EA Trades

1. Go to Terminal tab → Trade
2. Right-click on any EA trade
3. Select "Close by Magic Number" (if available)
4. Or manually close each trade

### Reset State

To reset accumulated loss and consecutive losses:

1. Stop the EA
2. Go to Tools → Global Variables
3. Delete variables starting with `UnivBufEA_`
4. Restart the EA

---

## Troubleshooting

### EA Not Trading

**Symptoms**: EA is running but no trades are opening

**Solutions**:
1. Check "AutoTrading" button is green
2. Check `EnableTimeFilter` - ensure current time is allowed
3. Check `DailyProfitTargetPercent` - ensure target not reached
4. Check indicator is providing signals (enable `EnableDebugPrints`)
5. Check Experts tab for error messages

### Compilation Errors

**Symptoms**: Errors when compiling the EA

**Solutions**:
1. Verify all include files are in `MQL5/Include/`
2. Verify file paths are correct (use backslashes `\\`)
3. Check for syntax errors in custom indicator
4. Ensure MetaTrader 5 is up to date

### Indicator Not Found

**Symptoms**: "Indicator not found" error in Experts tab

**Solutions**:
1. Verify indicator name matches exactly (case-sensitive)
2. Verify indicator is in `MQL5/Indicators/`
3. Compile the indicator first
4. Check indicator has correct buffer indices

### Orders Rejected

**Symptoms**: Orders are rejected by broker

**Solutions**:
1. Check `LotSize` is within broker limits
2. Check account has sufficient margin
3. Increase `Slippage` parameter
4. Verify symbol is allowed for trading

### State Not Persisting

**Symptoms**: Accumulated loss resets after EA restart

**Solutions**:
1. Check global variables are not being deleted
2. Verify `MagicNumber` is consistent
3. Check symbol name is correct
4. Ensure EA is properly closed (not crashed)

---

## Testing Recommendations

### 1. Demo Account Testing

**Always test on a demo account first!**

- Test for at least 1-2 weeks
- Monitor all trades closely
- Check all features are working:
  - Signal detection
  - Order execution
  - Partial closes
  - Breakeven
  - Trailing stops
  - Time filtering
  - Daily profit target

### 2. Backtesting

1. Open Strategy Tester (press F4 or View → Strategy Tester)
2. Select `Universal Buffer Reader EA`
3. Select symbol and timeframe
4. Select test period
5. Configure input parameters
6. Click "Start"
7. Review results and optimize parameters

### 3. Forward Testing

After successful backtesting:
- Test on demo account with live data
- Monitor for 2-4 weeks
- Compare results with backtest
- Adjust parameters if needed

---

## Safety Tips

1. **Start Small**: Use small lot sizes initially
2. **Monitor Closely**: Check trades frequently in first week
3. **Use Stop Losses**: Always ensure SL is set
4. **Test Thoroughly**: Never skip demo testing
5. **Keep Backups**: Save working configurations
6. **Review Logs**: Check Experts tab regularly
7. **Know Limits**: Understand broker requirements
8. **Stay Updated**: Keep EA and indicator updated

---

## Getting Help

### Documentation

- **Test Plan**: `TEST_PLAN.md`
- **Input Parameters**: `INPUT_PARAMETERS_REFERENCE.md`
- **Original MQL4 Code**: `Indicator Signal EA base code.mq4`

### Debug Mode

Enable debug prints to see detailed information:
- Set `EnableDebugPrints = true`
- Monitor Experts tab
- Look for messages with `[ClassName]` prefix

### Common Error Messages

| Error | Cause | Solution |
|-------|-------|----------|
| "Indicator not found" | Indicator name incorrect | Check exact name in Indicators folder |
| "Invalid lot size" | Lot size outside broker limits | Adjust `LotSize` parameter |
| "Not enough money" | Insufficient margin | Reduce lot size or deposit funds |
| "Trading not allowed" | Time filter blocking | Check time filter settings |
| "Daily target reached" | Profit target met | Wait for next day or increase target |

---

## Next Steps

1. ✅ Install the EA
2. ✅ Configure for your indicator
3. ✅ Test on demo account
4. ✅ Monitor and adjust settings
5. ✅ Backtest and optimize
6. ✅ Deploy to live account (when ready)

---

## Version History

- **v2.0** (2025-01-20): Complete rewrite in MQL5 with enhanced features
- **v1.0**: Original MQL4 version

---

**Happy Trading! 📈**

**Last Updated**: 2025-01-20
**Version**: 2.0