# ESP32 Motor Controller - Command Reference

This document describes all commands supported by the OCTv2 ESP32 motor controller firmware.

## Overview

The ESP32 controller handles precise stepper motor control for the OCTv2 system via serial communication at 115200 baud. All commands are text-based and must end with a newline character.

## Command Categories

### **Movement Commands**

#### `HOME`
- **Description**: Home both rotation and pitch motors to their limit switches
- **Parameters**: None
- **Response**: `OK` on success, `ERROR: <message>` on failure
- **Example**:
  ```
  HOME
  OK
  ```
- **Notes**: Must be run before any positioning commands. Sets current position to (0°, 0°)

#### `MOVE <rotation> <pitch>`
- **Description**: Set target position in degrees (non-blocking)
- **Parameters**:
  - `rotation`: -90.0 to +90.0 degrees (horizontal aim)
  - `pitch`: 0.0 to 60.0 degrees (vertical aim)
- **Response**: `OK` immediately (movement happens in background)
- **Examples**:
  ```
  MOVE 45.0 30.0    # Set target to 45° right, 30° up
  MOVE -30.0 15.5   # Update target to 30° left, 15.5° up
  MOVE 0.0 0.0      # Set target to home position
  ```
- **Notes**:
  - Values are automatically clamped to safe limits
  - New targets override previous ones immediately
  - Motors move smoothly to new position using acceleration profiles

#### `REL <delta_rotation> <delta_pitch>`
- **Description**: Adjust target relative to current target (non-blocking)
- **Parameters**:
  - `delta_rotation`: Degrees to adjust horizontally (+ = right, - = left)
  - `delta_pitch`: Degrees to adjust vertically (+ = up, - = down)
- **Response**: `OK` immediately (movement happens in background)
- **Examples**:
  ```
  REL 5.0 0.0       # Adjust target 5° right
  REL -2.5 1.0      # Adjust target 2.5° left, 1° up
  REL 0.0 -5.0      # Adjust target 5° down
  ```
- **Notes**:
  - Adjustments are relative to current target position
  - Perfect for continuous tracking adjustments

### **Action Commands**

#### `FIRE`
- **Description**: Trigger the Oreo firing mechanism
- **Parameters**: None
- **Response**: `OK` after firing sequence complete
- **Example**:
  ```
  FIRE
  🔥 FIRING OREO!
  OK
  ```
- **Notes**: Uses either servo (90° pulse) or solenoid (100ms pulse) depending on configuration

### **Status Commands**

#### `POS`
- **Description**: Get current motor positions
- **Parameters**: None
- **Response**: `<rotation> <pitch>` in degrees
- **Example**:
  ```
  POS
  45.0 30.0
  ```

#### `STATUS`
- **Description**: Get detailed system status
- **Parameters**: None
- **Response**: Comprehensive status string
- **Example**:
  ```
  STATUS
  HOMED:1 ROT:43.2 ELEV:28.7 TARGET_ROT:45.0 TARGET_ELEV:30.0 MOVING:1 EMERGENCY:0 LIMITS:0,0
  ```
- **Status Fields**:
  - `HOMED`: 1 if homed, 0 if not
  - `ROT`: Current actual rotation in degrees
  - `ELEV`: Current actual pitch in degrees
  - `TARGET_ROT`: Target rotation in degrees
  - `TARGET_ELEV`: Target pitch in degrees
  - `MOVING`: 1 if motors moving, 0 if stopped
  - `EMERGENCY`: 1 if in emergency stop, 0 if normal
  - `LIMITS`: Limit switch states (rotation,pitch: 1=triggered, 0=clear)

### **Safety Commands**

#### `STOP`
- **Description**: Emergency stop - immediately disable all motors
- **Parameters**: None
- **Response**: `EMERGENCY STOP ACTIVATED`
- **Example**:
  ```
  STOP
  EMERGENCY STOP ACTIVATED
  ```
- **Notes**: Disables stepper drivers, stops all motion. Use `RESET` to recover.

#### `RESET`
- **Description**: Reset from emergency stop state
- **Parameters**: None
- **Response**: `Emergency stop reset - system ready`
- **Example**:
  ```
  RESET
  Emergency stop reset - system ready
  ```
- **Notes**: Re-enables stepper drivers, resets watchdog timer

## Communication Protocol

### **Serial Settings**
- **Baud Rate**: 115200
- **Data Bits**: 8
- **Parity**: None
- **Stop Bits**: 1
- **Line Ending**: Newline (`\n`) or Carriage Return + Newline (`\r\n`)

### **Command Format**
- Commands are **case-insensitive** (automatically converted to uppercase)
- Maximum command length: **50 characters**
- Parameters separated by **spaces**
- Commands longer than 50 characters are rejected with `ERROR: Command too long`

### **Response Types**
- **`OK`**: Command executed successfully
- **`ERROR: <description>`**: Command failed with error description
- **Data responses**: Position data, status information
- **Informational**: Status messages (e.g., "🔥 FIRING OREO!")

## Safety Features

### **Watchdog Timer**
- **Timeout**: 30 seconds
- **Behavior**: Automatic emergency stop if no commands received
- **Reset**: Any valid command resets the timer
- **Warning**: `WARNING: Communication timeout - emergency stop`

### **Software Limits**
- **Rotation**: Hard-limited to -90° to +90°
- **Elevation**: Hard-limited to 0° to 60°
- **Enforcement**: Values automatically clamped to safe ranges

### **Emergency Protection**
- **Emergency stop** disables stepper drivers immediately
- **Buffer overflow protection** prevents command injection
- **Invalid command** handling with clear error messages
- **Limit switch** protection during homing

### **Status LED Indicators**
- **Solid ON**: System idle and ready
- **Fast Blinking (100ms)**: Motors moving
- **Very Fast Blinking (200ms)**: Emergency stop active

## Error Conditions

### **Common Errors**
- `ERROR: Not homed` - Attempted movement before homing
- `ERROR: Invalid MOVE syntax` - Incorrect command format
- `ERROR: Invalid REL syntax` - Incorrect command format
- `ERROR: Command too long` - Command exceeds 50 characters
- `ERROR: Unknown command` - Unrecognized command

### **Recovery Procedures**
1. **Communication lost**: Check USB connection, restart ESP32
2. **Emergency stop**: Send `RESET` command to restore operation
3. **Not homed**: Send `HOME` command before movement
4. **Invalid commands**: Check command syntax and try again

## Hardware Configuration

### **Default Pin Assignments**
```cpp
// Rotation Motor (A4988 Driver)
#define ROTATION_STEP_PIN     2
#define ROTATION_DIR_PIN      3
#define ROTATION_ENABLE_PIN   4
#define ROTATION_LIMIT_PIN    5

// Elevation Motor (A4988 Driver)
#define ELEVATION_STEP_PIN    6
#define ELEVATION_DIR_PIN     7
#define ELEVATION_ENABLE_PIN  8
#define ELEVATION_LIMIT_PIN   9

// Fire Mechanism
#define FIRE_SERVO_PIN        10
#define FIRE_SOLENOID_PIN     11

// Status
#define STATUS_LED_PIN        13
```

### **Motor Settings**
- **Steps per revolution**: 200 (1.8° steppers)
- **Microstepping**: 16x (A4988 drivers)
- **Gear ratios**: 5:1 rotation, 3:1 pitch (configurable)
- **Max speed**: 2000 steps/sec rotation, 1500 steps/sec pitch
- **Acceleration**: 1000 steps/sec²

## Usage Examples

### **Basic Operation Sequence**
```
HOME                    # Home motors first
OK
MOVE 30.0 20.0         # Aim 30° right, 20° up
OK
FIRE                   # Fire Oreo
🔥 FIRING OREO!
OK
POS                    # Check position
30.0 20.0
REL -30.0 -20.0        # Return to center
OK
```

### **Status Monitoring**
```
STATUS
HOMED:1 ROT:30.0 ELEV:20.0 RUNNING:0 EMERGENCY:0

# During movement:
MOVE 45.0 30.0
STATUS
HOMED:1 ROT:35.2 ELEV:25.1 RUNNING:1 EMERGENCY:0
```

### **Emergency Procedures**
```
STOP                   # Emergency stop
EMERGENCY STOP ACTIVATED

STATUS
HOMED:1 ROT:35.2 ELEV:25.1 RUNNING:0 EMERGENCY:1

RESET                  # Recover from emergency
Emergency stop reset - system ready
```

## Integration Notes

This ESP32 controller is designed to work with the OCTv2 Raspberry Pi server, which handles:
- iOS app communication
- Computer vision targeting
- High-level control logic
- Distance estimation and trajectory calculation

The ESP32 focuses purely on precise, reliable motor control and safety.