docs: Add information on coordinate systems to Code_Overview.md

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>
This commit is contained in:
Kevin O'Connor 2019-12-04 11:09:22 -05:00
parent 98d1fee8ad
commit e557f2d0c0
1 changed files with 87 additions and 0 deletions

View File

@ -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
====