docs: Add information on coordinate systems to Code_Overview.md

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>

1 files changed, 87 insertions, 0 deletions

diff --git a/docs/Code_Overview.md b/docs/Code_Overview.md
index 7f4be890..c64766a0 100644
--- a/docs/Code_Overview.md
+++ b/docs/Code_Overview.md
@@ -400,6 +400,93 @@ Useful steps:
    the micro-controller with the main klippy.py program.
 9. Consider adding build test cases in the test/ directory.
 
+Coordinate Systems
+==================
+
+The position of the toolhead is primarily tracked in cartesian
+coordinates that are relative to the coordinate system specified in
+the config file. That is, the coordinate system generally does not
+change during run-time. If a request is made to alter the origin (eg,
+a `G92` command) then that effect is obtained by translating future
+commands to the existing coordinate system.
+
+However, in some cases it is useful to obtain the toolhead position in
+some other coordinate system and Klipper has several tools to
+facilitate that. This can be seen by running the GET_POSITION
+command. For example:
+
+```
+Send: GET_POSITION
+Recv: // mcu: stepper_a:-2060 stepper_b:-1169 stepper_c:-1613
+Recv: // stepper: stepper_a:457.254159 stepper_b:466.085669 stepper_c:465.382132
+Recv: // kinematic: X:8.339144 Y:-3.131558 Z:233.347121
+Recv: // toolhead: X:8.338078 Y:-3.123175 Z:233.347878 E:0.000000
+Recv: // gcode: X:8.338078 Y:-3.123175 Z:233.347878 E:0.000000
+Recv: // gcode base: X:0.000000 Y:0.000000 Z:0.000000 E:0.000000
+Recv: // gcode homing: X:0.000000 Y:0.000000 Z:0.000000
+```
+
+The "mcu" position (`stepper.get_mcu_position()` in the code) is the
+total number of steps the micro-controller has issued in a positive
+direction minus the number of steps issued in a negative direction
+since the micro-controller was last reset. The value reported is only
+valid after the stepper has been homed. If the robot is in motion when
+the query is issued then the reported value includes moves buffered on
+the micro-controller, but does not include moves on the look-ahead
+queue.
+
+The "stepper" position (`stepper.get_commanded_position()`) is the
+position for the given stepper as tracked by the kinematics code. This
+generally corresponds to the position of the carriage along its rail
+in units of millimeters and is generally relative to the
+endstop_position specified in the config file. (Some kinematics track
+the position in radians instead of millimeters.) If the robot is in
+motion when the query is issued then the reported value includes moves
+buffered on the micro-controller, but does not include moves on the
+look-ahead queue. One may use the `toolhead.flush_step_generation()`
+or `toolhead.wait_moves()` calls to fully flush the look-ahead and
+step generation code.
+
+The "kinematic" position (`kin.set_tag_position()` and
+`kin.calc_tag_position()`) is the cartesian position of the toolhead
+as derived from the "stepper" position and is relative to the
+coordinate system specified in the config file. This may differ from
+the requested cartesian position due to the granularity of the stepper
+motors. If the robot is in motion when `kin.set_tag_position()` is
+issued then the reported value includes moves buffered on the
+micro-controller, but does not include moves on the look-ahead
+queue. One may use the `toolhead.flush_step_generation()` or
+`toolhead.wait_moves()` calls to fully flush the look-ahead and step
+generation code.
+
+The "toolhead" position (`toolhead.get_position()`) is the last
+requested position of the toolhead in cartesian coordinates relative
+to the coordinate system specified in the config file. If the robot is
+in motion when the query is issued then the reported value includes
+all requested moves (even those in buffers waiting to be issued to the
+stepper motor drivers).
+
+The "gcode" position is the last requested position from a `G1` (or
+`G0`) command in cartesian coordinates relative to the coordinate
+system specified in the config file. This may differ from the
+"toolhead" position if a g-code transformation (eg, bed_mesh,
+bed_tilt, skew_correction) is in effect. This may differ from the
+actual coordinates specified in the last `G1` command if the g-code
+origin has been changed (eg, `G92`, `SET_GCODE_OFFSET`, `M221`). The
+`M114` command (`gcode.get_status()['gcode_position']`) will report
+the last g-code position relative to the current g-code coordinate
+system.
+
+The "gcode base" is the location of the g-code origin in cartesian
+coordinates relative to the coordinate system specified in the config
+file. Commands such as `G92`, `SET_GCODE_OFFSET`, and `M221` alter
+this value.
+
+The "gcode homing" is the location to use for the g-code origin (in
+cartesian coordinates relative to the coordinate system specified in
+the config file) after a `G28` home command. The `SET_GCODE_OFFSET`
+command can alter this value.
+
 Time
 ====