v1.1b: Tweaked Bf reports, jogging doc, saved another 160 bytes, minor bug fixes

- Increment to v1.1b due to status report tweak.

- Tweaked the buffer state status reports to show bytes and blocks
available, rather than in use. This does not require knowing the buffer
sizes beforehand. It’s implicit.

- Also, since buffer states are not used by most devs (after
inquiries), it is no longer enabled by default and a status mask option
was added for this.

- Fixed some typos and updated for the report tweak in the
documentation.

- Wrote a joystick implementation concept in the jogging markdown
document. Outlines how to get a low-latency feel to a joystick (and
other input devices).

- Removed XON/XOFF support. It’s not used by anyone because of its
inherent problems. Remains in older versions for reference.

- Added a compile option on how to handle the probe position during a
check mode.

- Fixed a jogging bug. If G93 is the modal state before a jogging
motion, the feed rate did not get calculated correctly. Fixed the issue.

- Refactored some code to save another 160+ bytes. Included an improved
float vector comparison macro and reducing a few large and repetitive
function calls.

- Fixed a probing bug (existing in v0.9 too) where the target positions
were not set correct and error handling was improper.

doc/log/commit_log_v1.1.txt

@@ -1,3 +1,26 @@
+----------------
+Date: 2016-09-25
+Author: Sonny Jeon
+Subject: Addressed much larger flash size with avr-gcc v4.9.2. Refactored reports to save 160KB.
+
+- The newest Arduino IDE 1.6.12 has recently updated to avr-gcc v4.9.2.
+Unfortunately, it produces a compiled size almost 0.7KB to 1KB larger
+than prior versions! This can easily cause the base build to exceed the
+Arduino Duemilanove/Nano flash limit of 30.5KB. The Arduino Uno seems
+to be ok still with its 31.5KB flash limit.
+
+- Makefile `-flto` compile flag added to cut down on the horrible flash
+size when using the new avr-gcc. (Edit Makefile and remove comment on
+COMPILE definition). This brings it in-line with what the IDE produces.
+
+- Functionalized repetitive tasks in report.c to try to reduce overall
+flash size. Successfully cut down about 160bytes.
+
+- Removed printFloat_SettingValue() and printFloat_RPMValue()
+functions. These aren’t required and can be replaced with a direct call
+to printFloat() because they don’t require a unit conversion check.
+
+
 ----------------
 Date: 2016-09-24
 Author: Sonny Jeon

doc/markdown/change_summary.md

@@ -13,7 +13,7 @@ Grbl v1.1's interface protocol has been tweaked in the attempt to make GUI devel
 
 - `< >` : Enclosed chevrons contains status report data.
 
-- `Grbl vX.Xx ['$' for help]` : Welcome message indicates initialization.
+- `Grbl X.Xx ['$' for help]` : Welcome message indicates initialization.
 
 - `ALARM:x` : Indicates an alarm has been thrown. Grbl is now in an alarm state.
 
@@ -72,7 +72,8 @@ On a final note, this interface tweak came about out of necessity, as more data
 
 - Buffer data (planner and serial RX) reports have been tweaked and combined.
 
-  - `Bf:0,0`. The first value is planner blocks in use and the second is RX bytes in use.
+  - `Bf:15,128`. The first value is the available blocks in the planner buffer and the second is available bytes in the serial RX buffer.
+  - Note that this is different than before, where it reported blocks/bytes "in-use", rather than "available". This change does not require a GUI to know how many blocks/bytes Grbl has been compiled with, which can be substantially different on a Grbl-Mega build.
 
 
 - Override reports are intermittent since they don't change often once set.

doc/markdown/interface.md

@@ -11,11 +11,11 @@ In other words, both commands sent to Grbl and messages received from Grbl have
 
 #### Start Up Message
 
-**`Grbl vX.Xx ['$' for help]`**
+**`Grbl X.Xx ['$' for help]`**
 
 The start up message always prints upon startup and after a reset. Whenever you see this message, this also means that Grbl has completed re-initializing all its systems, so everything starts out the same every time you use Grbl.
 
-* `vX.Xx` indicates the major version number, followed by a minor version letter. The major version number indicates the general release, while the letter simply indicates a feature update or addition from the preceding minor version letter.
+* `X.Xx` indicates the major version number, followed by a minor version letter. The major version number indicates the general release, while the letter simply indicates a feature update or addition from the preceding minor version letter.
 * Bug fix revisions are tracked by the build info version number, printed when an `$I` command is sent. These revisions don't update the version number and are given by date revised in year, month, and day, like so `20160820`.
 
 #### Grbl `$` Help Message
@@ -423,11 +423,19 @@ Feedback messages provide non-critical information on what Grbl is doing, what i
 
     - **Buffer State:**
 
-        - `Bf:0,0`. The first value is planner blocks in use and the second is RX bytes in use.
+        - `Bf:15,128`. The first value is the number of available blocks in the planner buffer and the second is number of available bytes in the serial RX buffer.
+        
+        - The usage of this data is generally for debugging an interface, but is known to be used to control some GUI-specific tasks. While this is disabled by default, GUIs should expect this data field to appear, but they may ignore it, if desired.
+        
+        - NOTE: The buffer state values changed from showing "in-use" blocks or bytes to "available". This change does not require the GUI knowing how many block/bytes Grbl has been compiled with.
 
+        - This data field appears:
+        
+          - In every status report when enabled. It is disabled in the settings mask by default.
+        
         - This data field will not appear if:
 
-          - It is disabled by the `$` status report mask setting.
+          - It is disabled by the `$` status report mask setting or disabled in the config.h file.
 
     - **Line Number:**
 
@@ -547,7 +555,7 @@ Grbl v1.1's interface protocol has been tweaked in the attempt to make GUI devel
 
 - `< >` : Enclosed chevrons contains status report data.
 
-- `Grbl vX.Xx ['$' for help]` : Welcome message indicates initialization.
+- `Grbl X.Xx ['$' for help]` : Welcome message indicates initialization.
 
 - `ALARM:x` : Indicates an alarm has been thrown. Grbl is now in an alarm state.
 

doc/markdown/jogging.md

@@ -1,5 +1,6 @@
-## Grbl v1.0 Jogging
+# Grbl v1.1 Jogging
 
+## How to Use
 Executing a jog requires a specific command structure, as described below:
 
  - The first three characters must be '$J=' to indicate the jog.
@@ -26,7 +27,8 @@ return an 'ok' when the jogging motion has been parsed and is setup for executio
 command is not valid, Grbl will return an 'error:'. Multiple jogging commands may be
 queued in sequence.
 
-The main differences are:
+The main differences are:  
+
 - During a jog, Grbl will report a 'Jog' state while executing the jog.
 - A jog command will only be accepted when Grbl is in either the 'Idle' or 'Jog' states.
 - Jogging motions may not be mixed with g-code commands while executing, which will return
@@ -39,3 +41,54 @@ The main differences are:
   'G91G1X1F100'. Since G91, G1, and F feed rates are modal and if they are not changed
   back prior to resuming/starting a job, a job may not run how its was intended and result
   in a crash.
+
+------
+
+## Joystick Implementation
+
+Jogging in Grbl v1.1 is generally intended to address some prior issues with old bootstrapped jogging methods. Unfortunately, the new Grbl jogging is not a complete solution. Flash and memory restrictions prevent the original envisioned implementation, but most of these can be mimicked by the following suggested methods. 
+
+With a combination of the new jog cancel and moving in `G91` incremental mode, the following implementation can create low latency feel for an analog joystick.
+
+- Basic Implementation Overview: 
+  - Create a loop to read the joystick signal and translate it to a desired jog motion vector.
+  - Send Grbl a very short `G91` incremental distance jog command with a feed rate based on the joystick throw.
+  - Wait for an 'ok' acknowledgement before restarting the loop.
+  - Continually read the joystick input and send Grbl short jog motions to keep Grbl's planner buffer full.
+  - If the joystick is returned to its neutral position, stop the jog loop and simply send Grbl a `!` feed hold command. This will stop motion immediately somewhere along the programmed jog path with virtually zero-latency and automatically flush Grbl's planner queue.
+
+
+The overall idea is to minimize the total distance in the planner queue to provide a low-latency feel to joystick control. The main trick is ensuring there is just enough distance in the planner queue, such that the programmed feed rate is always met. How to compute this will be explain later. In practice, most machines will have a 0.5 second latency. When combined with the immediate joy cancel by a feed hold command, joystick interaction can be quite enjoyable and satisfying.
+
+However, please note, if a machine has a low acceleration and is being asked to move at a high programmed feed rate, joystick latency can get up to a handful of seconds. It may sound bad, but this is how long it'll take for a low acceleration machine, traveling at a high feed rate, to slow down to a stop. The argument can be made for a low acceleration machine that you really shouldn't be traveling at a high feed rate. It is difficult for a user to gauge where the machine will come to a stop. You risk overshooting your target destination, which can result in an expensive or dangerous crash. 
+
+One of the advantages of this approach is that a GUI can deterministically track where Grbl will go by the jog commands it has already sent to Grbl. As long as a feed hold doesn't cancel the jog state, every jog command is guaranteed to execute. In the event a feed hold is sent, the GUI would just need to refresh their internal position from a status report after Grbl has cleared planner buffer and returned to the IDLE state from the JOG state. This stopped position will always be somewhere along the programmed jog path. If desired, jogging can then be quickly and easily restarted with a new tracked path.
+
+In combination with `G53` move in machine coordinates, a GUI can restrict jogging from moving into "keep-out" zones inside the machine space. This can be very useful for avoiding crashing into delicate probing hardware, workholding mechanisms, or other fixed features inside machine space that you don't want to damage.
+
+#### How to compute incremental distances
+
+The quickest and easiest way to determine what the length of a jog motion needs to be to minimize latency are defined by the following equations.
+
+`d = v * dt` - Computes distance traveled for next jog command.
+
+where:  
+
+- `dt` - Estimated execution time of a single jog command in seconds.  
+- `v` - Current jog feed rate in **mm/sec**, not mm/min. Less than or equal to max jog rate.
+- `N` - Number of Grbl planner blocks (`N=15`)
+- `T = dt * N` - Computes total estimated latency in seconds.
+ 
+The time increment `dt` may be defined to whatever value you need. Obviously, you'd like the lowest value, since that translates to lower overall latency `T`. However, it is constrained by two factors.
+
+- `dt > 10ms` - The time it takes Grbl to parse and plan one jog command and receive the next one. Depending on a lot of factors, this can be around 1 to 5 ms. To be conservative, `10ms` is used. Keep in mind that on some systems, this value may be greater than `10ms`.
+
+- `dt > v^2 / (2 * a * (N-1))` - The time increment needs to be large enough to ensure the jog feed rate will be acheived. Grbl always plans to a stop over the total distance queued in the planner buffer. This is primarily to ensure the machine will safely stop if a disconnection occurs. This equation simply ensures that `dt` is big enough to satisfy this constraint. 
+
+	- For simplicity, use the max jog feed rate for `v` in mm/sec and the smallest acceleration setting between the jog axes being moved in mm/sec^2.
+
+	- For a lower latency, `dt` can be computed for each jog motion, where `v` is the current rate and `a` is the max acceleration along the jog vector. This is very useful if traveling a very slow speeds to locate a part zero. The `v` rate would be much lower in this scenario and the total latency would decrease quadratically.
+
+In practice, most CNC machines will operate with a jogging time increment of `0.025 sec` < `dt` < `0.06 sec`, which translates to about a `0.4` to `0.9` second total latency when traveling at the max jog rate. Good enough for most people. 
+
+However, if jogging at a slower speed and a GUI adjusts the `dt` with it, you can get very close to the 0.1 second response time by human-interface guidelines for "feeling instantaneous". Not to shabby!