From e557f2d0c0cf7dd8ef3312ba69559d4df91d3fa6 Mon Sep 17 00:00:00 2001 From: Kevin O'Connor Date: Wed, 4 Dec 2019 11:09:22 -0500 Subject: [PATCH] docs: Add information on coordinate systems to Code_Overview.md Signed-off-by: Kevin O'Connor --- docs/Code_Overview.md | 87 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) 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 ====