graduate accelStepperFirmata out of proposals and add link to impleme…

…ntation
firmata · Sep 16, 2017 · c0449c9 · c0449c9
1 parent 1b72dd7
commit c0449c9
Show file tree

Hide file tree

Showing 4 changed files with 28 additions and 26 deletions.
diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@ Firmata is a protocol for communicating with microcontrollers from software on a
 
 Firmata is based on the [midi message format](http://www.midi.org/techspecs/midimessages.php) in that commands bytes are 8 bits and data bytes are 7 bits. For example the midi Channel Pressure (Command: 0xD0) message is 2 bytes long, in Firmata the Command 0xD0 is used to enable reporting for a digital port (collection of 8 pins). Both the midi and Firmata versions are 2 bytes long, but the meaning is obviously different. In Firmata, the number of bytes in a message must conform with the corresponding midi message. Midi [System Exclusive](http://www.2writers.com/eddie/tutsysex.htm) (Sysex) messages however, can be any length and are therefore used most prominently throughout the Firmata protocol.
 
-This repository contains documentation of the Firmata protocol. The core of the protocol is described in the [protocol.md file](protocol.md) file. Feature-specific documentation is described in individual markdown files ([i2c.md](i2c.md), [stepper-2.0.md](https://github.com/firmata/protocol/blob/master/proposals/stepper-2.0.md), [servos.md](servos.md), etc). Files added to the proposals directory are proposals for new features that have not yet been finalized. See [firmata-registry.md](https://github.com/firmata/protocol/blob/master/feature-registry.md) for the full list of documented firmata features.
+This repository contains documentation of the Firmata protocol. The core of the protocol is described in the [protocol.md file](protocol.md) file. Feature-specific documentation is described in individual markdown files ([i2c.md](i2c.md), [accelStepperFirmata.md](https://github.com/firmata/protocol/blob/master/accelStepperFirmata.md), [servos.md](servos.md), etc). Files added to the proposals directory are proposals for new features that have not yet been finalized. See [firmata-registry.md](https://github.com/firmata/protocol/blob/master/feature-registry.md) for the full list of documented firmata features.
 
 The Firmata protocol could theoretically be implemented for any microcontroller platform. Currently however, the most complete implementation is for [Arduino](http://arduino.cc) (including Arduino-compatible microcontrollers). Here are the known Firmata microcontroller platform implementations:
 
@@ -84,8 +84,8 @@ To make a change to an existing protocol, submit a pull request with your propos
 Some hints for drafting a new proposal:
 
 * See [feature-registry.md](https://github.com/firmata/protocol/blob/master/feature-registry.md) for information on proposing a new feature and requesting a feature ID.
-* Use sub-commands (3rd byte) as necessary if you have more than one message. See the [stepper-2.0.md](https://github.com/firmata/protocol/blob/master/proposals/stepper-2.0.md) file for an example. Note the use of `0x62` for the feature ID and how each section has an enumerated set of subcommands (0x00 = config, 0x01 = stop, 02 = step, etc).
-* It's okay to have optional values in a sysex message as long as those values are all at the end of the message. See the bytes 8 - 11 of the Stepper `to` message in [stepper-2.0.md](https://github.com/firmata/protocol/blob/master/proposals/stepper-2.0.md)
+* Use sub-commands (3rd byte) as necessary if you have more than one message. See the [accelStepperFirmata.md](https://github.com/firmata/protocol/blob/master/accelStepperFirmata.md) file for an example. Note the use of `0x62` for the feature ID and how each section has an enumerated set of subcommands (0x00 = config, 0x01 = zero, 02 = step, etc).
+* It's okay to have optional values in a sysex message as long as those values are all at the end of the message. See the bytes 6 & 7 of the `SERIAL_CONFIG` message in [serial-1.0.md](https://github.com/firmata/protocol/blob/master/serial-1.0.md)
 * Try to keep your sysex messages as short as possible.
 * Pack bits if necessary. See the Response message for **Report encoder's position** in [encoder.md](encoder.md) for an example (also note how this was documented following the response message... please include similar documentation if you use bit packing in your proposal).
 * If your proposal uses any of the available non-sysex midi messages, the number of bytes in the message must correspond to the number of bytes in the midi message. The meaning however does not need to be the same. However if the midi message uses channels (such as Note Off (0x80)) then the Firmata message must also use channels since a midi parser may expect this.
diff --git a/proposals/accelStepperFirmata.md → accelStepperFirmata.md b/proposals/accelStepperFirmata.md → accelStepperFirmata.md
@@ -1,4 +1,4 @@
-accelStepperFirmata
+AccelStepperFirmata (Stepper 2.0)
 ===
 
 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](http://www.schmalzhaus.com/EasyDriver/).
@@ -12,7 +12,9 @@ AccelStepperFirmata sends and receives floats in a custom format described at th
 of this document.
 
 Example files:
- * accelStepperFirmata has not yet been implemented.
+ * ConfigurableFirmata [AccelStepperFirmata.cpp](https://github.com/firmata/ConfigurableFirmata/blob/master/src/AccelStepperFirmata.cpp).
+
+Added in Firmata protocol version 2.6.0.
 
 Protocol
 ---
@@ -23,7 +25,7 @@ This message is required and must be sent prior to any other message. The device
 
 ```
 0  START_SYSEX                                (0xF0)
-1  accelStepper Command                       (0x62)
+1  ACCELSTEPPER_DATA                          (0x62)
 2  config command                             (0x00 = config)
 3  device number                              (0-9) (Supports up to 10 motors)
 
@@ -65,7 +67,7 @@ accelStepper will store the current absolute position of the stepper motor (in s
 
 ```
 0  START_SYSEX                             (0xF0)
-1  Stepper Command                         (0x62)
+1  ACCELSTEPPER_DATA                       (0x62)
 2  zero command                            (0x01)
 3  device number                           (0-9)
 4  END_SYSEX                               (0xF7)
@@ -77,7 +79,7 @@ Steps to move is specified as a 32-bit signed long.
 
 ```
 0  START_SYSEX                             (0xF0)
-1  Stepper Command                         (0x62)
+1  ACCELSTEPPER_DATA                       (0x62)
 2  step command                            (0x02)
 3  device number                           (0-9)
 4  num steps, bits 0-6
@@ -95,7 +97,7 @@ Position is specified as a 32-bit signed long.
 
 ```
 0  START_SYSEX                             (0xF0)
-1  Stepper Command                         (0x62)
+1  ACCELSTEPPER_DATA                       (0x62)
 2  to command                              (0x03)
 3  device number                           (0-9)
 4  position, bits 0-6
@@ -112,7 +114,7 @@ For stepper motor controllers that are configured with an enable pin, the enable
 
 ```
 0  START_SYSEX                             (0xF0)
-1  Stepper Command                         (0x62)
+1  ACCELSTEPPER_DATA                       (0x62)
 2  enable command                          (0x04)
 3  device number                           (0-9)
 4  device state                            (HIGH : enabled | LOW : disabled)
@@ -125,7 +127,7 @@ Stops a stepper motor. Results in ```STEPPER_MOVE_COMPLETE``` being sent to the
 
 ```
 0  START_SYSEX                             (0xF0)
-1  Stepper Command                         (0x62)
+1  ACCELSTEPPER_DATA                       (0x62)
 2  stop command                            (0x05)
 3  device number                           (0-9)
 4  END_SYSEX                               (0xF7)
@@ -137,7 +139,7 @@ Request a position report.
 
 ```
 0  START_SYSEX                             (0xF0)
-1  Stepper Command                         (0x62)
+1  ACCELSTEPPER_DATA                       (0x62)
 2  report position command                 (0x06)
 3  device number                           (0-9)
 4  END_SYSEX                               (0xF7)
@@ -149,7 +151,7 @@ Sent when a report position is requested. Position is reported as a 32-bit signe
 
 ```
 0  START_SYSEX                             (0xF0)
-1  Stepper Command                         (0x62)
+1  ACCELSTEPPER_DATA                       (0x62)
 2  report position command                 (0x06)
 3  device number                           (0-9)
 4  position, bits 0-6
@@ -166,7 +168,7 @@ Sent when a move completes. Position is reported as a 32-bit signed long.
 
 ```
 0  START_SYSEX                             (0xF0)
-1  Stepper Command                         (0x62)
+1  ACCELSTEPPER_DATA                       (0x62)
 2  move complete command                   (0x0b)
 3  device number                           (0-9)
 4  position, bits 0-6
@@ -185,7 +187,7 @@ When a limit pin (digital) is set to its limit state, movement in that direction
 
 ```
 0  START_SYSEX                             (0xF0)
-1  Stepper Command                         (0x62)
+1  ACCELSTEPPER_DATA                       (0x62)
 2  stop limit command                      (0x07)
 3  device number                           (0-9)
 4  lower limit pin number                  (0-127)
@@ -203,7 +205,7 @@ using accelStepperFirmata's custom float format described below.
 
 ```
 0  START_SYSEX                             (0xF0)
-1  Stepper Command                         (0x62)
+1  ACCELSTEPPER_DATA                       (0x62)
 2  set acceleration command                (0x08)
 3  device number                           (0-9) (Supports up to 10 motors)
 4  accel, bits 0-6                         (acceleration in steps/sec^2)
@@ -221,7 +223,7 @@ The speed value is passed using accelStepperFirmata's custom float format descri
 
 ```
 0  START_SYSEX                             (0xF0)
-1  Stepper Command                         (0x62)
+1  ACCELSTEPPER_DATA                       (0x62)
 2  set speed command                       (0x09)
 3  device number                           (0-9) (Supports up to 10 motors)
 4  maxSpeed, bits 0-6                      (maxSpeed in steps per sec)
@@ -237,7 +239,7 @@ Stepper instances that have been created with the stepper configuration command
 
 ```
 0  START_SYSEX                              (0xF0)
-1  Stepper Command                          (0x62)
+1  ACCELSTEPPER_DATA                        (0x62)
 2  multiConfig command                      (0x20)
 3  group number                             (0-4)
 4  member 0x00 device number                (0-9)
@@ -264,7 +266,7 @@ will take the longest given the change in position and the stepper's max speed.
 
 ```
 0  START_SYSEX                              (0xF0)
-1  Stepper Command                          (0x62)
+1  ACCELSTEPPER_DATA                        (0x62)
 2  multi to command                         (0x21)
 3  group number                             (0-4)
 4  position, bits 0-6
@@ -284,7 +286,7 @@ Immediately stops all steppers in the group.
 
 ```
 0  START_SYSEX                             (0xF0)
-1  Stepper Command                         (0x62)
+1  ACCELSTEPPER_DATA                       (0x62)
 2  multi stop command                      (0x23)
 3  group number                            (0-4)
 4  END_SYSEX                               (0xF7)
@@ -296,7 +298,7 @@ Sent when a multiStepper move completes.
 
 ```
 0  START_SYSEX                             (0xF0)
-1  Stepper Command                         (0x62)
+1  ACCELSTEPPER_DATA                       (0x62)
 2  multi stepper move complete command     (0x24)
 3  group  number                           (0-4)
 4  END_SYSEX                               (0xF7)
@@ -365,4 +367,4 @@ so we would be passing in 4 bytes in this order:
 | Least most significant bits               |  0000001| 0x01|
 | Next most significant bits                |  0000000| 0x00|
 | Next most significant bits                |  0000000| 0x00|
-| Sign, Exponent and 2 most significant bits|  0110100| 0x34|
+| Sign, Exponent and 2 most significant bits|  0110100| 0x34|
diff --git a/feature-registry.md b/feature-registry.md
@@ -62,11 +62,11 @@ Each feature should be documented in a markdown file and versioned independently
 | 5FH         | DEVICE_RESPONSE                    | [proposal](https://github.com/finson-release/Luni/blob/master/extras/v0.9/v0.8-device-driver-C-firmata-messages.md) | proposed |
 | 60H         | SERIAL_DATA (1.0)                  | [serial-1.0.md](https://github.com/firmata/protocol/blob/master/serial.md) | current |
 | 61H         | ENCODER_DATA                       | [encoder.md](https://github.com/firmata/protocol/blob/master/encoder.md) | current |
-| 62H         | STEPPER_DATA (2.0)                 | [stepper-2.0.md](https://github.com/firmata/protocol/blob/master/proposals/stepper-2.0.md) | current |
+| 62H         | ACCELSTEPPER_DATA                  | [accelStepperFirmata.md](https://github.com/firmata/protocol/blob/master/accelStepperFirmata.md) | current |
 | 67H         | SERIAL_DATA (2.0)                  | [proposal](https://github.com/firmata/protocol/blob/master/proposals/serial-2.0-proposal.md) | proposed |
 | 68H         | SPI_DATA                           | [proposal](https://github.com/firmata/protocol/blob/master/proposals/spi-proposal.md) | proposed |
 | 70H         | SERVO_CONFIG                       | [servos.md](https://github.com/firmata/protocol/blob/master/servos.md) | current |
-| 72H         | STEPPER_DATA (1.0)                 | [stepper-1.0.md](https://github.com/firmata/protocol/blob/master/stepper-1.0.md) | deprecated |
+| 72H         | STEPPER_DATA                       | [stepper-legacy.md](https://github.com/firmata/protocol/blob/master/stepper-legacy.md) | deprecated |
 | 73H         | ONEWIRE_DATA                       | [onewire.md](https://github.com/firmata/protocol/blob/master/onewire.md) | current |
 | 75H         | SHIFT_DATA                         | [shift-proposal.md](https://github.com/firmata/protocol/blob/master/proposals/shift-proposal.md) | proposed |
 | 76H         | I2C_REQUEST                        | [i2c.md](https://github.com/firmata/protocol/blob/master/i2c.md) | current |

diff --git a/stepper-1.0.md → stepper-legacy.md b/stepper-1.0.md → stepper-legacy.md
@@ -1,7 +1,7 @@
-Stepper Motor 1.0
+Stepper Motor
 ===
 
-*Note: Version 1.0 will be deprectated once [version 2.0](https://github.com/firmata/protocol/blob/master/stepper-2.0.md) has been implemented in ConfigurableFirmata.*
+*Note: This legacy version is no longer supported not recommended for new implementations. Use the new, more full-featured [AccelStepper version](https://github.com/firmata/protocol/blob/master/accelStepperFirmata.md) instead.*
 
 Provides support for 4 wire and 2 wire stepper motor drivers (H-bridge, darlington array, etc) as well as step + direction drivers such as the [EasyDriver](http://www.schmalzhaus.com/EasyDriver/).
 Current implementation supports 6 stepper motors at the same time (#[0-5]).