Startseite Erkunden Hilfe
Registrieren Anmelden
fdamstra
/
OCTv2
1
0
Fork 0
Dateien Issues 0 Pull-Requests 0 Wiki
Branch: main
Branches Tags
OCTv2
/
esp32_firmware
/
ESP32_COMMANDS.md

ESP32_COMMANDS.md 7.6 KB
Permalink Verlauf Originalformat

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

// 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.