Update README and clarifications in jogging document.

README.md

@@ -3,7 +3,7 @@
 
 ***
 
-_**This is the development branch for Grbl v1.0's upcoming release. Please keep in mind, the new features here are beta, so use with caution. If you'd like to help, please report any bugs or oddities that you find! Thanks!**_
+_**This is the development branch for Grbl v1.1's upcoming release. Please keep in mind, the new features here are beta, so use with caution. If you'd like to help, please report any bugs or oddities that you find! Thanks!**_
 
 ***
 
@@ -19,9 +19,9 @@ Grbl includes full acceleration management with look ahead. That means the contr
 
 * For more information and help, check out our **[Wiki pages!](https://github.com/gnea/grbl/wiki)** If you find that the information is out-dated, please to help us keep it updated by editing it or notifying our community! Thanks!
 
-* Lead Developer [_2011 - Current_]: Sungeun "Sonny" Jeon, Ph.D. (USA) aka @chamnit
+* Lead Developer: Sungeun "Sonny" Jeon, Ph.D. (USA) aka @chamnit
 
-* This work is built on the wonderful Grbl v0.6 firmware in 2011 written by Simen Svale Skogsrud (Norway).
+* Built on the wonderful Grbl v0.6 (2011) firmware written by Simen Svale Skogsrud (Norway).
 
 ***
 
@@ -31,26 +31,39 @@ Grbl includes full acceleration management with look ahead. That means the contr
 
 ***
 
-##Update Summary for v1.0
+##Update Summary for v1.1
 - **IMPORTANT:** Your EEPROM will be wiped and restored with new settings. This is due to the addition of two new spindle speed '$' settings.
 
-- New safety door parking motion as a compile-option. Grbl will retract, disable the spindle/coolant, and park near Z max. When resumed, it will perform these task in reverse order and continue the program. Highly configurable. See config.h for details.
+- **Real-time Overrides** : Alters the machine running state immediately with feed, rapid, spindle speed, spindle stop, and coolant toggle controls. This huge contribution by the Grbl project is feature that is common only on industrial machines, often used to optimize cutting while the job is running. Most hobby CNC's try to mimic this with varying results. 
+
+- **Jogging Mode** : New jogging commands seperate from the g-code parser, so that the parser state doesn't get altered and cause a potential crash if not restored properly. Documentation is included on how to use this with a joystick with a low-latency.
+
+- **Laser Mode** : Grbl now has a "laser" mode, where consecutive G1, G2, and G3 commands do not stop and continuously move through them with a spindle speed change.  Spindle speed overrides also work with laser mode so you can tweak the laser power, if you need to during the job. Switch between "laser" mode and "normal" mode via a `$` setting.
+
+- **Significant Interface Improvements**: Just this one time and done simultaneously with adding override controls, Grbl has tweaked the communication interface to make it easier for developers to write better GUIs. _NOTE: GUIs need to specifically update their code to be compatible with v1.1 and later._
+
+	- **New Status Reports**: To account for the additional override data, status reports have been tweaked to cram more data into it, while still being smaller than before. Documentation is included, outlining how it has been changed. 
+	- **Improved Error/Alarm Feedback** : All Grbl error and alarm messages have been changed to providing a code. Each code is associated with a specific problem, so users will know exactly what is wrong without having to guess. Documentation and an easy to parse CSV is included in the repo.
+	- **Extended-ASCII realtime commands** : All overrides and future real-time commands are defined in the extended-ASCII character space. Unfortunately not easily type-able on a keyboard, but helps prevent accidental commands from a g-code file having these characters and gives lots of space for future expansion.
+	- **Message Prefixes** : Every message type from Grbl has a unique prefix to help GUIs immediately determine what the message is and parse it accordingly without having to know context. The prior interface had several instances of GUIs having to figure out the meaning of a message, which made everything more complicated than it needed to be.
+
+- New OEM specific features, such as safety door parking, single configuration file build option, EEPROM restrictions and restoring controls, and storing product data information.
+ 
+- New safety door parking motion as a compile-option. Grbl will retract, disable the spindle/coolant, and park near Z max. When resumed, it will perform these task in reverse order and continue the program. Highly configurable, even to add more than one parking motion. See config.h for details.
 
 - New '$' Grbl settings for max and min spindle rpm. Allows for tweaking the PWM output to more closely match true spindle rpm. When max rpm is set to zero or less than min rpm, the PWM pin D11 will act like a simple enable on/off output.
 
 - Updated G28 and G30 behavior from NIST to LinuxCNC g-code description. In short, if a intermediate motion is specified, only the axes specified will move to the stored coordinates, not all axes as before.
 
+- Lots of minor bug fixes and refactoring to make the code more efficient and flexible.
+
 - **NOTE:** Arduino Mega2560 support has been moved to an active, official Grbl-Mega [project](http://www.github.com/gnea/grbl-Mega/). All new developments here and there will be synced when it makes sense to.
 
-- Single file configuration for custom firmware.
-
-- A few bug fixes and lots of refactoring to make the code more efficient and flexible.
-
 
 -
 
 ```
-List of Supported G-Codes in Grbl v0.9 Master:
+List of Supported G-Codes in Grbl v1.1:
   - Non-Modal Commands: G4, G10L2, G10L20, G28, G30, G28.1, G30.1, G53, G92, G92.1
   - Motion Modes: G0, G1, G2, G3, G38.2, G38.3, G38.4, G38.5, G80
   - Feed Rate Modes: G93, G94

doc/log/commit_log_v1.1.txt

@@ -1,3 +1,42 @@
+----------------
+Date: 2016-09-26
+Author: Sonny Jeon
+Subject: 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.
+
+
 ----------------
 Date: 2016-09-25
 Author: Sonny Jeon

doc/markdown/jogging.md

@@ -9,8 +9,7 @@ Executing a jog requires a specific command structure, as described below:
  - Required words:
    - XYZ: One or more axis words with target value.
    - F - Feed rate value. NOTE: Each jog requires this value and is not treated as modal.
- - Optional words: Jog executes based on current G20/G21 and G90/G91 g-code parser state. If one
-   of the following optional words is passed, that state is overridden for one command only.
+ - Optional words: Jog executes based on current G20/G21 and G90/G91 g-code parser state. If one of the following optional words is passed, that state is overridden for one command only.
    - G20 or G21 - Inch and millimeter mode
    - G90 or G91 - Absolute and incremental distances
    - G53 - Move in machine coordinates
@@ -31,49 +30,44 @@ 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
-  a lockout error, if attempted.
-- All jogging motion(s) may be cancelled at anytime with a simple feed hold command. Grbl
-  will automatically flush Grbl's internal buffers of any queued jogging motions and return
-  to the 'Idle' state. No soft-reset required.
-- IMPORTANT: Jogging does not alter the g-code parser state. Hence, no g-code modes need to
-  be explicitly managed, unlike previous ways of implementing jogs with commands like
-  '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.
+- Jogging motions may not be mixed with g-code commands while executing, which will return a lockout error, if attempted.
+- All jogging motion(s) may be cancelled at anytime with a simple feed hold command. Grbl will automatically flush Grbl's internal buffers of any queued jogging motions and return to the 'Idle' state. No soft-reset required.
+- If soft-limits are enabled, jog commands that exceed the machine travel simply does not execute the command and return an error, rather than throwing an alarm in normal operation.
+- IMPORTANT: Jogging does not alter the g-code parser state. Hence, no g-code modes need to be explicitly managed, unlike previous ways of implementing jogs with commands like '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. 
+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 methodology. 
 
-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.
+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 or similar control device.
 
 - 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.
+  - If the joystick is returned to its neutral position, stop the jog loop and simply send Grbl a jog cancel (or feed hold) real-time 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.
+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-1.0 second latency. When combined with the immediate jog cancel 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. 
+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 jogging 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.
+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 want to avoid.
 
 #### 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.
+`s = v * dt` - Computes distance traveled for next jog command.
 
 where:  
 
+- `s` - Incremental distance of jog command.
 - `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`)
@@ -81,7 +75,7 @@ where:
  
 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 > 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 still be greater than `10ms` due to round-trip communication latency.
 
 - `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. 
 
@@ -91,4 +85,6 @@ The time increment `dt` may be defined to whatever value you need. Obviously, yo
 
 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!
+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 too shabby!
+
+With some ingenuity, this jogging methodology may be applied to different devices such as a rotary dial or touchscreen. An "inertial-feel", like swipe-scrolling on a smartphone or tablet, can be simulated by managing the jog rate decay and sending Grbl the associated jog commands. While this jogging implementation requires more initial work by a GUI, it is also inherently more flexible because you have complete deterministic control of how jogging behaves.