Update Stepper to better fit common use cases

[soundanalogous]

The current version of Stepper has a number of limitations. It should be updated to better meet common uses cases. A separate command byte (TBD) can be used to safely deprecate the old version.

[soundanalogous]

The existing (old) protocol is here: https://github.com/firmata/protocol/blob/master/stepper.md

[dtex]

Edited 9/22 to add Stepper zero and update command values

So here's my stab at a new protocol...

This adds support for enable pins, multiStepper and more stepper interface types.

In addition to step I've added to which allows a position to be passed (accelStepper keeps track for us). I've also added stop which will stop a stepper and report back the current position.

There was some talk in other threads about adding the ability to poll the current position. I don't want to add this, but I would like for firmata to reply with the current position when a move or to is completed, or when stop is called.

What limited steppers to 6 initially? Was it just a guess as to what Firmata could handle updating? I've bumped it to 10, but that's an arbitrary number.

---

Stepper Motor

Provides support for full 2 wire, full 3 wire, full 4 wire, half 3 wire, and half 4 wire stepper motor drivers (H-bridge, darlington array, etc) as well as step + direction drivers such as the EasyDriver.
Current implementation supports 10 stepper motors at the same time (#[0-9]).

Includes optional support for acceleration and deceleration of the motor.

Also includes multiStepper support which allows groups of steppers to be simultaneously passed different to values and the duration of their movements will match. Up to five multiStepper groups can be created. The total number of steppers is still limited to 10.

Example files:

• The Stepper feature is include by default in ConfigurableFirmata.ino.
• Example implementation as a configurable Firmata feature class.

Protocol

Stepper configuration

Note: stepDelay is the the number of microseconds between steps. The default
value is 1us. You can change the delay to 2us (useful for high current stepper
motor drivers). Additional delay values can be added in the future.

0  START_SYSEX                          (0xF0)
1  Stepper Command                      (0x62)
2  config command                       (0x00 = config)
3  device number                        (0-9) (supports up to 10 motors)
4  stepDelay | interface                (upper 3 bits = step delay:
                                            000XXXX = default 1us delay [default]
                                            001XXXX = 2us delay
                                            other bits not yet used)

                                         (4th bit = hasEnable:
                                            XXX0XXX = no enable pin
                                            XXX1XXX = enable pin)

                                         (lower 3 bits = interface:
                                            XXXX001 = step + direction driver
                                            XXXX010 = two wire
                                            XXXX011 = three wire
                                            XXXX100 = four wire
                                            XXXX101 = unused
                                            XXXX110 = half three wire
                                            XXXX111 = half four wire)

5  minPulseWidth                          (0-127)
6  steps-per-revolution LSB
7  steps-per-revolution MSB
8  maxSpeed LSB                           (steps in 0.01*rad/sec  (2050 = 20.50 rad/sec))
9  maxSpeed MSB
10 motorPin1 or directionPin number       (0-127)
11 motorPin2 or stepPin number            (0-127)
12 [when interface >= 0x03] motorPin3     (0-127)
13 [when interface = 0x04
    or interface = 0x08] motorPin4        (0-127)
14 [when hasEnable = 0x01] enablePin      (0-127)
15 [optional] pins to invert              (lower 5 bits = pins:
                                           XXXXXX1 = invert motorPin1
                                           XXXXX1X = invert motorPin2
                                           XXXX1XX = invert motorPin3
                                           XXX1XXX = invert motorPin4
                                           XX1XXXX = invert enablePin)
16 END_SYSEX                              (0xF7)

Stepper zero

0  START_SYSEX                             (0xF0)
1  Stepper Command                         (0x62)
2  stop command                            (0x01)
3  device number                           (0-9)
14 END_SYSEX                               (0xF7)

Stepper step

0  START_SYSEX                             (0xF0)
1  Stepper Command                         (0x62)
2  step command                            (0x02)
3  device number                           (0-9)
4  direction                               (0-1) (0x00 = CW, 0x01 = CCW)
5  num steps byte1 LSB
6  num steps byte2
7  num steps byte3 MSB                     (21 bits (2,097,151 steps max))
8  speed LSB                               (steps per second)
9  speed MSB
10 [optional] accel LSB                    (acceleration in steps/sec^2)
11 [optional] accel MSB
12 [optional] decel LSB                    (deceleration in steps/sec^2)
13 [optional] decel MSB
14 END_SYSEX                               (0xF7)

Stepper to

0  START_SYSEX                             (0xF0)
1  Stepper Command                         (0x62)
2  to command                              (0x03)
3  device number                           (0-9)
4  num target byte1 LSB
5  num target byte2 MSB
6  speed LSB                               (steps per second)
7  speed MSB
8  [optional] accel LSB                    (acceleration in steps/sec^2)
9  [optional] accel MSB
10 [optional] decel LSB                    (deceleration in steps/sec^2)
11 [optional] decel MSB
12 END_SYSEX                               (0xF7)

Stepper enable

0  START_SYSEX                             (0xF0)
1  Stepper Command                         (0x62)
2  enable command                          (0x04)
3  device number                           (0-9)
4  END_SYSEX                               (0xF7)

Stepper disable

0  START_SYSEX                             (0xF0)
1  Stepper Command                         (0x62)
2  disable command                         (0x05)
3  device number                           (0-9)
4  END_SYSEX                               (0xF7)

Stepper stop

0  START_SYSEX                             (0xF0)
1  Stepper Command                         (0x62)
2  stop command                            (0x06)
3  device number                           (0-9)
14 END_SYSEX                               (0xF7)

Stepper stop reply

0  START_SYSEX                             (0xF0)
1  Stepper Command                         (0x62)
2  stop reply command                      (0x07)
3  device number                           (0-9)
4  position byte 1 LSB                            
5  position byte 2 MSB                            
6  END_SYSEX                               (0xF7)

MultiStepper configuration

0  START_SYSEX                              (0xF0)
1  Stepper Command                          (0x62)
2  config command                           (0x08)
3  group number                             (0-4) (supports up to 5 groups)
4  member device                            (0-9)
5  member device                            (0-9)
6  [optional] member device number          (0-9)
7  [optional] member device number          (0-9)
8  [optional] member device number          (0-9)
9  [optional] member device number          (0-9)
10 [optional] member device number          (0-9)
11 [optional] member device number          (0-9)
12 [optional] member device number          (0-9)
13 [optional] member device number          (0-9)
14 END_SYSEX                                (0xF7)

MultiStepper to

Note: You must pass a value for every stepper in the group.

0  START_SYSEX                              (0xF0)
1  Stepper Command                          (0x62)
2  multi to command                         (0x09)
3  num device 0 target byte1 LSB
4  num device 0 target byte2 MSB
5  num device 1 target byte1 LSB
6  num device 1 target byte2 MSB
7  [optional] num device 2 target byte1 LSB
8  [optional] num device 2 target byte2 MSB
9  [optional] num device 3 target byte1 LSB
10 [optional] num device 3 target byte2 MSB
11 [optional] num device 4 target byte1 LSB
12 [optional] num device 4 target byte2 MSB
13 [optional] num device 5 target byte1 LSB
14 [optional] num device 5 target byte2 MSB
15 [optional] num device 6 target byte1 LSB
16 [optional] num device 6 target byte2 MSB
17 [optional] num device 7 target byte1 LSB
18 [optional] num device 7 target byte2 MSB
19 [optional] num device 8 target byte1 LSB
20 [optional] num device 8 target byte2 MSB
21 [optional] num device 9 target byte1 LSB
22 [optional] num device 9 target byte2 MSB
23 END_SYSEX                                (0xF7)

MultiStepper stop

0  START_SYSEX                             (0xF0)
1  Stepper Command                         (0x62)
2  multi stop command                      (0x0A)
3  group number                            (0-9)
4  END_SYSEX                               (0xF7)

MultiStepper stop reply

0  START_SYSEX                             (0xF0)
1  Stepper Command                         (0x62)
2  multi stop reply command                (0x0B)
3  group  number                           (0-9)
4  device 0 position byte 1 LSB                            
5  device 0 position byte 2 MSB                            
6  device 1 position byte 1 LSB                            
7  device 1 position byte 2 MSB                            
8  device 2 position byte 1 LSB (if necessary)                            
9  device 2 position byte 2 MSB (if necessary)                            
10 device 3 position byte 1 LSB (if necessary)                            
11 device 3 position byte 2 MSB (if necessary)                            
12 device 4 position byte 1 LSB (if necessary)                            
13 device 4 position byte 2 MSB (if necessary)                            
14 device 5 position byte 1 LSB (if necessary)                            
15 device 5 position byte 2 MSB (if necessary)                            
16 device 6 position byte 1 LSB (if necessary)                            
17 device 6 position byte 2 MSB (if necessary)                            
18 device 7 position byte 1 LSB (if necessary)                            
19 device 7 position byte 2 MSB (if necessary)                            
20 device 8 position byte 1 LSB (if necessary)                            
21 device 8 position byte 2 MSB (if necessary)                            
22 device 9 position byte 1 LSB (if necessary)                            
23 device 9 position byte 2 MSB (if necessary)                            
24 END_SYSEX                               (0xF7)

[soundanalogous]

I think the step to function in AccelStepper is blocking for the duration of the sequence, which is the reason I never used that library in the first place. However it's been a while since I've looked over the code so perhaps the authors made it non-blocking in a more recent release.

[dtex]

runToNewPosition blocks, but I think moveTo does not. I had planned on using the latter.

[soundanalogous]

Finally had time to review your proposal. Here are a few comments:

1. Is this comprehensive for stepper motor interface types? If not it should get it's own byte to ensure it will scale:

(lower 3 bits = interface:
                                            XXXX001 = step + direction driver
                                            XXXX010 = two wire
                                            XXXX011 = three wire
                                            XXXX100 = four wire
                                            XXXX101 = unused
                                            XXXX110 = half three wire
                                            XXXX111 = half four wire)

1. Regarding the multi-stepper commands, would a user ever want to control the motors in a random order. If so we may need to add an index byte for each motor rather than relying on the order in which the motors were defined in a group. I do like the brevity of not needing to specify an index, but just want to be sure that does not make this feature more difficult to use.
2. We also need a message at the end of the step sequence, or does the stop reply also cover that (this was also missing from the original stepper protocol, but it was implemented and unfortunately I never included a command for it, it just reported the index so that needs to be fixed in the updated protocol)?
3. There were some requests a couple years ago for a homing/limit capability. This could be done without any additional protocol updates by using a switch and using digital input to determine when the switch is triggered, then call the stop command on the stepper, but that incurs latency when conducted over the Firmata transport. Maybe it's useful to add a command that enables the user to identify when a specified pin (or multiple pins) has changed to a specified state (or states if multiple pins), then stop the motor (if D7 == HIGH then stop and report position). I'm not sure if just a digital input is sufficient or if there is an analog use case as well (if A0 > 127 then stop and report position). Could easily be added later as well.
4. Maybe start the multistepper commands at a value of 0x20 to allow some space for new commands to the single stepper configurations without having to add numbers after the multistepper sequence.

[dtex]

Is this comprehensive for stepper motor interface types?

No, it is not. I will give it its own byte.

would a user ever want to control the motors in a random order

I'm skeptical. The time between commands to the steppers would be very small and a little unpredictable. I think it's more likely that a user would want to move only some members of a MultiStepper group and indices would give us the ability to do that too so I think it's a good addition but for a different reason.

We also need a message at the end of the step sequence

The stop reply command can cover that. I'll make sure to document that.

Maybe it's useful to add a command that enables the user to identify when a specified pin (or multiple pins) has changed to a specified state

That seems like a good idea (and matches my use case) but we will need the ability to add two digital pins (limits at either end) or one analog pin (potentiometer) with a range passed in.

start the multistepper commands at a value of 0x20

👍

I'll submit as a PR next.

[soundanalogous]

Done in Stepper 2.0: https://github.com/firmata/protocol/blob/master/stepper-2.0.md