StrokeEngine-Bibliothek

StrokeEngine ist eine Bibliothek zum Erstellen verschiedener Hubbewegungen mit Schritt- oder Servomotoren auf einem ESP32. Sie können sie mit jeder Heimwerkermaschine verwenden, die über einen linearen Positionsantrieb verfügt, der von einem Schritt- oder Servomotor angetrieben wird.

Kernkonzepte

StrokeEngine nutzt die Vorteile von Maschinen mit Servo- und Schrittantrieb gegenüber Konstruktionen mit festem Nockenantrieb voll aus. Unter der Haube nutzt es die FastAccelStepper-Bibliothek, um über Standard-STEP/DIR-Signale mit Motoren zu kommunizieren.

Koordinatensystem

Die Maschine verwendet ein internes Koordinatensystem, das reale metrische Einheiten in Encoder-/Schrittschritte umwandelt. Diese Abstraktion funktioniert mit allen Maschinengrößen, unabhängig vom gewählten Motor.

Wichtige Koordinatenkonzepte:

Muster

StrokeEngine verwendet einen Mustergenerator, um eine Vielzahl von Empfindungen zu erzeugen. Mithilfe trapezförmiger Bewegungsprofile passen Muster Parameter wie speed, stroke und depth Bewegung für Bewegung dynamisch an.

Jedes Muster akzeptiert vier Parameter:

• depth – Maximale Ausfahrposition
• stroke – Bewegungsamplitude
• speed – Zyklen pro Minute
• sensation – Beliebiger Modifikator für Musterverhalten (-100 bis 100)

Fehlerbehandlung ohne Unterbrechung

StrokeEngine verarbeitet ungültige Parameter ordnungsgemäß, ohne den Betrieb zu unterbrechen:

• Alle Setter-Funktionen verwenden constrain(), um Eingaben auf die physischen Fähigkeiten der Maschine zu beschränken
• Werte außerhalb der Grenzen werden automatisch beschnitten
• Musterbefehle, die die Maschinengrenzen überschreiten, führen zu verkürzten Hüben oder angepassten Rampen
• Die Bewegung wird über die gesamte Distanz abgeschlossen, kann jedoch etwas länger dauern als erwartet

Parameteraktualisierungen während des Hubs

Sie können die Parameter für Depth, Stroke, speed und pattern während des Hubs aktualisieren, um ein reaktionsschnelles, flüssiges Benutzererlebnis zu gewährleisten. Integrierte Sicherheitsvorrichtungen sorgen dafür, dass die Maschine jederzeit innerhalb der Grenzen bleibt.

Zustandsmaschine

Eine interne Finite-State-Maschine verwaltet die Maschinenzustände:

Verwendung

StrokeEngine bietet eine einfache, aber leistungsstarke API. Geben Sie alle Eingabeparameter in realen metrischen Einheiten an.

Initialisieren Sie die Bibliothek

#include <code>

// Pin Definitions
#define SERVO_PULSE       4
#define SERVO_DIR         16
#define SERVO_ENABLE      17
#define SERVO_ENDSTOP     25        // Optional: Only needed with a homing switch

// Calculation Aid:
#define STEP_PER_REV      2000      // Steps per revolution (check driver DIP switches)
#define PULLEY_TEETH      20        // Teeth on the drive pulley
#define BELT_PITCH        2         // Timing belt pitch in mm
#define MAX_RPM           3000.0    // Maximum motor RPM
#define STEP_PER_MM       STEP_PER_REV / (PULLEY_TEETH * BELT_PITCH)
#define MAX_SPEED         (MAX_RPM / 60.0) * PULLEY_TEETH * BELT_PITCH

static motorProperties servoMotor {
  .maxSpeed = MAX_SPEED,              // Maximum speed in mm/s
  .maxAcceleration = 10000,           // Maximum acceleration in mm/s²
  .stepsPerMillimeter = STEP_PER_MM,  // Steps per millimeter
  .invertDirection = true,            // Flip direction if motor moves wrong way
  .enableActiveLow = true,            // Enable signal polarity
  .stepPin = SERVO_PULSE,             // STEP signal pin
  .directionPin = SERVO_DIR,          // DIR signal pin
  .enablePin = SERVO_ENABLE           // Enable signal pin
};

static machineGeometry strokingMachine = {
  .physicalTravel = 160.0,            // Total travel between hard endstops (mm)
  .keepoutBoundary = 5.0              // Safety margin on each side (mm)
};

static endstopProperties endstop = {
  .homeToBack = true,                 // Endstop at rear of machine
  .activeLow = true,                  // Switch wired active low
  .endstopPin = SERVO_ENDSTOP,        // Endstop pin number
  .pinMode = INPUT                    // Use INPUT with external pull-up
};

StrokeEngine Stroker;

void setup() {
  // Initialize StrokeEngine
  Stroker.begin(&strokingMachine, &servoMotor);
  Stroker.enableAndHome(&endstop);

  // Your other initialization code here

  // Wait for homing to complete
  while (Stroker.getState() != READY) {
    delay(100);
  }
}

Manuelles Homing (kein Endschalter)

Wenn Ihre Maschine keinen Homing-Schalter hat, können Sie manuelles Homing verwenden:

1. Bewegen Sie die Maschine physisch bis zum hinteren Endanschlag
2. Rufen Sie Stroker.thisIsHome() auf

Stroker.thisIsHome();

Dadurch wird der Treiber aktiviert, die aktuelle Position als -keepoutBoundary festgelegt und langsam auf Position 0 gefahren.

Verfügbare Muster abrufen

Verwenden Sie getNumberOfPattern() und getPatternName(), um verfügbare Muster aufzulisten:

String getPatternJSON() {
    String JSON = "[{\"";
    for (size_t i = 0; i < Stroker.getNumberOfPattern(); i++) {
        JSON += String(Stroker.getPatternName(i));
        JSON += "\": ";
        JSON += String(i, DEC);
        if (i < Stroker.getNumberOfPattern() - 1) {
            JSON += "},{\"";
        } else {
            JSON += "}]";
        }
    }
    Serial.println(JSON);
    return JSON;
}

Bewegungssteuerung

Bewegung starten und stoppen

Positionsbefehle

Bewegen Sie die Maschine zu Einrichtungszwecken an ein beliebiges Ende:

Stroker.moveToMin();        // Move to rear (home) position
Stroker.moveToMax();        // Move to front (maximum) position
Stroker.moveToMax(10.0);    // Move at 10 mm/s (default speed)

Interaktives Tiefen-Setup

Rufen Sie den Tiefen-Setup-Modus auf, in dem der Motor der Tiefenposition in Echtzeit folgt:

Stroker.setupDepth();           // Default 10 mm/s
Stroker.setupDepth(10.0);       // Specify speed

Aktualisieren Sie die Tiefenposition mit Stroker.setDepth(float) und lesen Sie den aktuellen Wert mit Stroker.getDepth().

Parameterfunktionen

Aktualisieren Sie die Parameter jederzeit. Die Werte werden automatisch auf die Maschinengrenzen beschränkt:

// Setter functions
Stroker.setSpeed(float speed, bool applyNow);      // 0.5–6000 cycles/min
Stroker.setDepth(float depth, bool applyNow);      // 0 to _travel (mm)
Stroker.setStroke(float stroke, bool applyNow);    // 0 to _travel (mm)
Stroker.setSensation(float sensation, bool applyNow); // -100 to 100
Stroker.setPattern(int index, bool applyNow);      // 0 to getNumberOfPattern()-1

Lesen Sie die tatsächlich von StrokeEngine verwendeten eingeschränkten Werte zurück:

// Getter functions
float speed = Stroker.getSpeed();         // Cycles per minute
float depth = Stroker.getDepth();         // Depth in mm
float stroke = Stroker.getStroke();       // Stroke length in mm
float sensation = Stroker.getSensation(); // -100 to 100
int pattern = Stroker.getPattern();       // Pattern index

Erweiterte Funktionen

Telemetrie-Rückruf

Registrieren Sie einen Rückruf, um Telemetriedaten für jede Trapezbewegung zu erhalten:

void callbackTelemetry(float position, float speed, bool clipping) {
  // Handle telemetry data
}

Stroker.registerTelemetryCallback(callbackTelemetry);