update README/CHANGELOG/FastAccelStepper.md and fix for #268

CHANGELOG.md

@@ -6,6 +6,10 @@ TODO:
 - rename RampConstAcceleration to e.g. RampControl
 - merge the two esp32 rmt drivers as soon as esp32c3 works
 
+pre-0.30.16:
+- Fix missing parenthesis in preprocessor macro (#271)
+- Position parameter for `forceStopAndNewPosition()` changed from `uint32_t` to `int32_t` (#268)
+
 0.30.15:
 - Fix missing initialization in `getCurrentSpeedInTicks()` (#262)
 

README.md

@@ -508,4 +508,6 @@ As mentioned by kthod861 in [Issue #110](https://github.com/gin66/FastAccelStepp
 - Thanks DaAwesomeP for the extension to ATmega 168/168P/328 (https://github.com/gin66/FastAccelStepper/pull/179)
 - Thanks turley for the patch for missing `_stepper_cnt` initialization (https://github.com/gin66/FastAccelStepper/pull/204)
 - Thanks GarmischWg for adding rmt-support to ESP32-S3 (https://github.com/gin66/FastAccelStepper/pull/225)
-- THanks SHWotever for avr patch to fix missing direction pin toggle (https://github.com/gin66/FastAccelStepper/pull/252)
+- Thanks SHWotever for avr patch to fix missing direction pin toggle (https://github.com/gin66/FastAccelStepper/pull/252)
+- Thanks HalfVoxel for pull requests (https://github.com/gin66/FastAccelStepper/pull/270) and (https://github.com/gin66/FastAccelStepper/pull/271): improved doc and missing parenthesis in preprocessor macros
+

extras/doc/FastAccelStepper_API.md

@@ -430,6 +430,7 @@ This is convenient especially, if the stepper is set to continuous running.
   void applySpeedAcceleration();
 ```
 ## Move commands
+### move() and moveTo()
 start/move the stepper for (move) steps or to an absolute position.
 
 If the stepper is already running, then the current running move will be
@@ -442,6 +443,7 @@ return values are the MOVE_... constants
   int8_t move(int32_t move, bool blocking = false);
   int8_t moveTo(int32_t position, bool blocking = false);
 ```
+### keepRunning()
 This command flags the stepper to keep run continuously into current
 direction. It can be stopped by stopMove.
 Be aware, if the motor is currently decelerating towards reversed
@@ -451,13 +453,15 @@ reversal first.
   void keepRunning();
   bool isRunningContinuously() { return _rg.isRunningContinuously(); }
 ```
-This command just let the motor run continuously in one direction.
+### runForward() and runBackwards()
+These commands just let the motor run continuously in one direction.
 If the motor is running in the opposite direction, it will reverse
 return value as with move/moveTo
 ```cpp
   int8_t runForward();
   int8_t runBackward();
 ```
+### forwardStep() and backwardStep()
 forwardStep()/backwardstep() can be called, while stepper is not moving
 If stepper is moving, this is a no-op.
 backwardStep() is a no-op, if no direction pin defined
@@ -467,6 +471,7 @@ If blocking = true, then the routine will wait till isRunning() is false
   void forwardStep(bool blocking = false);
   void backwardStep(bool blocking = false);
 ```
+### moveByAcceleration()
 moveByAcceleration() can be called, if only the speed of the stepper
 is of interest and that speed to be controlled by acceleration.
 The maximum speed (in both directions) to be set by setSpeedInUs() before.
@@ -480,13 +485,15 @@ return value as with move/moveTo
 ```cpp
   int8_t moveByAcceleration(int32_t acceleration, bool allow_reverse = true);
 ```
-stop the running stepper with normal deceleration.
+### stopMove()
+Stop the running stepper with normal deceleration.
 This only sets a flag and can be called from an interrupt !
 ```cpp
   void stopMove();
   bool isStopping() { return _rg.isStopping(); }
 ```
-abruptly stop the running stepper without deceleration.
+### forceStop()
+Abruptly stop the running stepper without deceleration.
 This can be called from an interrupt !
 
 The stepper command queue will be processed, but no further commands are
@@ -503,7 +510,7 @@ queue, the actual stop position is lost (recovering this position cannot be
 done within an interrupt). So the new position after stop has to be
 provided and will be set as current position after stop.
 ```cpp
-  void forceStopAndNewPosition(uint32_t new_pos);
+  void forceStopAndNewPosition(int32_t new_pos);
 ```
 get the target position for the current move.
 As of now, this position is the view of the stepper task.
@@ -513,30 +520,33 @@ In keep running mode, the targetPos() is not updated
 ```cpp
   int32_t targetPos() { return _rg.targetPosition(); }
 ```
+### Task planning
 The stepper task adds commands to the stepper queue until
 either at least two commands are planned, or the commands
 cover sufficient time into the future. Default value for that time is 20ms.
 
 The stepper task is cyclically executed every ~4ms.
 Especially for avr, the step interrupts puts a significant load on the uC,
 so the cyclical stepper task can even run for 2-3 ms. On top of that,
-other interrupts caused by the application could increase the load even further.
+other interrupts caused by the application could increase the load even
+further.
 
-Consequently, the forward planning should fill the queue for ideally two cycles,
-this means 8ms. This means, the default 20ms provide a sufficient margin and
-even a missed cycle is not an issue.
+Consequently, the forward planning should fill the queue for ideally two
+cycles, this means 8ms. This means, the default 20ms provide a sufficient
+margin and even a missed cycle is not an issue.
 
-The drawback of the 20ms is, that any change in speed/acceleration are added after
-those 20ms and for an application, requiring fast reaction times, this may 
-impact the expected performance.
+The drawback of the 20ms is, that any change in speed/acceleration are
+added after those 20ms and for an application, requiring fast reaction
+times, this may impact the expected performance.
 
-Due to this the forward planning time can be adjusted with the following API call
-for each stepper individually.
+Due to this the forward planning time can be adjusted with the following
+API call for each stepper individually.
 
 Attention:
 - This is only for advanced users: no error checking is implemented.
 - Only change the forward planning time, if the stepper is not running.
-- Too small values bear the risk of a stepper running at full speed suddenly stopping
+- Too small values bear the risk of a stepper running at full speed
+suddenly stopping
   due to lack of commands in the queue.
 ```cpp
   void setForwardPlanningTimeInMs(uint8_t ms) {

src/FastAccelStepper.cpp

@@ -668,7 +668,7 @@ void FastAccelStepper::forceStop() {
   // inform ramp generator to force stop
   _rg.forceStop();
 }
-void FastAccelStepper::forceStopAndNewPosition(uint32_t new_pos) {
+void FastAccelStepper::forceStopAndNewPosition(int32_t new_pos) {
   StepperQueue* q = &fas_queue[_queue_num];
 
   // ensure no more commands are added to the queue

src/FastAccelStepper.h

@@ -533,7 +533,7 @@ class FastAccelStepper {
   // queue, the actual stop position is lost (recovering this position cannot be
   // done within an interrupt). So the new position after stop has to be
   // provided and will be set as current position after stop.
-  void forceStopAndNewPosition(uint32_t new_pos);
+  void forceStopAndNewPosition(int32_t new_pos);
 
   // get the target position for the current move.
   // As of now, this position is the view of the stepper task.