Enhancements to CLI interface

README.md

@@ -290,6 +290,7 @@ this is the main class and the one you want to start with.
 |`void getButtonStatusRegister(byte buffer[ESPServerSwitchStatusRegisterCount])`|Populate the given byte buffer with the switch status for each configured button (1 = button is triggered, 0 = button is not triggered)|`byte buffer[]`: a byte array to populate with the status register contents for all configured switches (basically the current switch status in regards to being active/inactive)|
 |`String getIpAddress()`|get the current IP address of the server. Only Available if connected to a WIFI or if started in AP mode|none|
 |`ESPStepperMotorServer_Configuration *getCurrentServerConfiguration()`|get the pointer of the ESPStepperMotorServer_Configuration instance that represents the current server complete configuration|none|
+|`ESPStepperMotorServer_CLI *getCLIHandler() const`|get the pointer of the serial CLI handler instance. This can be used to register custom CLI commands.|none|
 
 ### REST API documentation
 Besides the web-based User Interface the ESP StepperMotor Server offers a REST API to control all aspects of the server that can also be controlled via the web UI (in fact the web UI uses the REST API for all operations).
@@ -327,9 +328,11 @@ The output should look like this (depending on the version and how up2date this
 The following commands are available:
 
 <command> [<shortcut>]: <description>
+
+Built in commands:
 help [h]:               show a list of all available commands
-moveby [mb]*:           move by a specified number of units. requires the id of the stepper to move, the amount pf movement and also optional the unit for the movement (mm, steps, revs). If no unit is specified steps will be assumed as unit. E.g. mb=0&v:-100&u:mm to move the stepper with id 0 by -100 mm
-moveto [mt]*:           move to an absolute position. requires the id of the stepper to move, the amount pf movement and also optional the unit for the movement (mm, steps, revs). If no unit is specified steps will be assumed as unit. E.g. mt=0&v:100&u:revs to move the stepper with id 0 to the absolute position at 100 revolutions
+moveby [mb]*:           move by a specified number of units. requires the id of the stepper to move, the amount of movement and also optional the unit for the movement (mm, steps, revs). If no unit is specified steps will be assumed as unit. Optionally you can also set the speed in steps/second, acceleration and deceleration, each in steps/second/second). Set speeds, acceleration and deceleration are rememebered until overwritten again. E.g. mb=0&v:-100&u:mm&s:200 to move the stepper with id 0 by -100 mm with a speed of 200 steps per second
+moveto [mt]*:           move to an absolute position. requires the id of the stepper to move, the amount of movement and also optional the unit for the movement (mm, steps, revs). If no unit is specified steps will be assumed as unit. Optionally you can also set the speed in steps/second, acceleration and deceleration, each in steps/second/second). Set speeds, acceleration and deceleration are rememebered until overwritten again. E.g. mt=0&v:100&u:revs&a:100 to move the stepper with id 0 to the absolute position at 100 revolutions with an acceleration of 100 steps per second^2
 config [c]:             print the current configuration to the console as JSON formatted string
 emergencystop [es]:     trigger emergency stop for all connected steppers. This will clear all target positions and stop the motion controller module immediately. In order to proceed normal operation after this command has been issued, you need to call the `revokeemergencystop` [res] command
 revokeemergencystop [res]:      revoke a previously triggered emergency stop. This must be called before any motions can proceed after a call to the emergency-stop command
@@ -361,10 +364,10 @@ Each command also has a shortcut (listed in the `help` output in `[]`) that can
 Commands with parameters must be invoked following this schema:
 `<commandname or shortcut name>=<primary parameter>&<optional additional parameter name>:<optional additional parameter value>`
 An example for a command with multiple parameters is the `moveto` command. The shortcut for this command is `mt`.
-The command supports three parameters: the id of the stepper to move (primary parameter), the amount/value for the movement (v parameter) and the unit (u parameter) for the movement (mm, steps or revolutions).
-Example: 
-If you want to move the configured stepper motor with the id 0 by 10 revolutions the command looks as follows:
-`mt=0&v=10&u=revs`
+The command supports six parameters: the id of the stepper to move (primary parameter), the amount/value for the movement (v parameter), the unit (u parameter) for the movement (mm, steps or revolutions), the speed (s parameter) in steps per second, the acceleration (a parameter) in steps per second per second and the deceleration (d parameter) in steps per second per second.
+Example:
+If you want to move the configured stepper motor with the id 0 by 10 revolutions with a speed of 100 steps per second the command looks as follows:
+`mt=0&v:10&u:revs&s:100`
 
 ### Further documentation
 for further details have a look at 

examples/Example4_StepperMotorServer_with_user_cli_command/Example4_StepperMotorServer_with_user_cli_command.ino

@@ -0,0 +1,97 @@
+//      *****************************************************
+//      *     Example how to register a new CLI command     *
+//      *            Tobias Ellinghaus         05.12.2023   *
+//      *****************************************************
+//
+// This examples show how to register a custom command for the CLI interface.
+// This could be useful if you want to control specific GPIO pins or trigger some other control logic.
+// This example is based on the hardcoded config example, so all remarks of that apply here, too.
+//
+// This library requires that your stepper motor be connected to the ESP32
+// using an external driver that has a "Step and Direction" interface.
+//
+// For all driver boards, it is VERY important that you set the motor
+// current before running the example. This is typically done by adjusting
+// a potentiometer on the board or using dip switches.
+// Read the driver board's documentation to learn how to configure the driver
+//
+// for a detailed manual on how to use this library please visit: https://github.com/pkerspe/ESP-StepperMotor-Server/blob/master/README.md
+// ***********************************************************************
+#include <Arduino.h>
+#include <ESPStepperMotorServer.h>
+#include <ESPStepperMotorServer_PositionSwitch.h>
+#include <ESPStepperMotorServer_StepperConfiguration.h>
+#include <ESP_FlexyStepper.h>
+
+ESPStepperMotorServer *stepperMotorServer;
+ESPStepperMotorServer_StepperConfiguration *stepperConfiguration;
+ESPStepperMotorServer_CLI *cli_handler;
+
+#define STEP_PIN 16
+#define DIRECTION_PIN 17
+#define ENABLE_PIN 18
+
+void toggle_enable(char *cmd, char *args)
+{
+  const int stepperid = cli_handler->getValidStepperIdFromArg(args);
+#ifndef ESPStepperMotorServer_COMPILE_NO_DEBUG
+  ESPStepperMotorServer_Logger::logDebugf("%s called for stepper id %i\n", cmd, stepperid);
+#endif
+  if (stepperid > -1)
+  {
+    char value[20];
+    cli_handler->getParameterValue(args, "v", value);
+    if (value[0] != '\0')
+    {
+#ifndef ESPStepperMotorServer_COMPILE_NO_DEBUG
+      ESPStepperMotorServer_Logger::logDebugf("enabled called with v = %s\n", value);
+#endif
+
+      const int on_off = (String(value).toInt());
+      digitalWrite(ENABLE_PIN, on_off ? HIGH : LOW);
+
+      Serial.println(cmd);
+    }
+    else
+    {
+      Serial.println("error: missing required v parameter");
+    }
+  }
+}
+
+void setup()
+{
+  // configure our custom pin as an output and initialize it to LOW
+  pinMode(ENABLE_PIN, OUTPUT);
+  digitalWrite(ENABLE_PIN, LOW);
+
+  Serial.begin(115200);
+  // now create a new ESPStepperMotorServer instance (this must be done AFTER the Serial interface has been started)
+  // In this example we create the server instance with only the serial command line interface enabled
+  stepperMotorServer = new ESPStepperMotorServer(ESPServerSerialEnabled, ESPServerLogLevel_DEBUG);
+  stepperMotorServer->setWifiMode(ESPServerWifiModeDisabled);
+
+  // register a new CLI command to set the ENABLE pin
+  cli_handler = stepperMotorServer->getCLIHandler();
+  cli_handler->registerNewUserCommand({String("enable"), String("e"), String("set the ENABLE signal of a specific stepper. requires the id of the stepper and also the value. E.g. e=0&v:1 to enable the ENABLE input on the stepper with id 0"), true}, &toggle_enable);
+
+  //create a new configuration for a stepper
+  stepperConfiguration = new ESPStepperMotorServer_StepperConfiguration(STEP_PIN, DIRECTION_PIN);
+  stepperConfiguration->setDisplayName("X-Axis");
+  //configure the step size and microstepping setup of the drive/motor
+  stepperConfiguration->setMicrostepsPerStep(1);
+  stepperConfiguration->setStepsPerMM(100);
+  stepperConfiguration->setStepsPerRev(200);
+
+  // now add the configuration to the server
+  unsigned int stepperId = stepperMotorServer->addOrUpdateStepper(stepperConfiguration);
+
+  //start the server
+  stepperMotorServer->start();
+  // check the serial console for more details and to send control signals
+}
+
+void loop()
+{
+  //put your custom code here
+}

src/ESPStepperMotorServer.cpp

@@ -472,6 +472,15 @@ byte ESPStepperMotorServer::getPositionSwitchStatus(int positionSwitchIndex)
     return 0;
 }
 
+// ---------------------------------------------------------------------------------
+//                          CLI API functions
+// ---------------------------------------------------------------------------------
+
+ESPStepperMotorServer_CLI *ESPStepperMotorServer::getCLIHandler() const
+{
+    return this->cliHandler;
+}
+
 // ---------------------------------------------------------------------------------
 //                          Web Server and REST API functions
 // ---------------------------------------------------------------------------------

src/ESPStepperMotorServer.h

@@ -140,6 +140,7 @@ class ESPStepperMotorServer
   signed char updateSwitchStatusRegister();
   String getIpAddress();
   ESPStepperMotorServer_Configuration *getCurrentServerConfiguration();
+  ESPStepperMotorServer_CLI *getCLIHandler() const;
   void requestReboot(String rebootReason);
   bool isSPIFFSMounted();