diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Config_Reference.md | 235 | ||||
| -rw-r--r-- | docs/G-Codes.md | 59 | ||||
| -rw-r--r-- | docs/Status_Reference.md | 6 |
3 files changed, 286 insertions, 14 deletions
diff --git a/docs/Config_Reference.md b/docs/Config_Reference.md index e65b79bf..f9ef676b 100644 --- a/docs/Config_Reference.md +++ b/docs/Config_Reference.md @@ -84,8 +84,9 @@ The printer section controls high level printer settings. [printer] kinematics: # The type of printer in use. This option may be one of: cartesian, -# corexy, corexz, hybrid_corexy, hybrid_corexz, rotary_delta, delta, -# deltesian, polar, winch, or none. This parameter must be specified. +# corexy, corexz, hybrid_corexy, hybrid_corexz, generic_cartesian, +# rotary_delta, delta, deltesian, polar, winch, or none. +# This parameter must be specified. max_velocity: # Maximum velocity (in mm/s) of the toolhead (relative to the # print). This value may be changed at runtime using the @@ -712,6 +713,172 @@ anchor_z: # These parameters must be provided. ``` +### Generic Cartesian Kinematics + +See [example-generic-cartesian.cfg](../config/example-generic-caretesian.cfg) +for an example generic Cartesian kinematics config file. + +This printer kinematic class allows a user to define in a pretty flexible +manner an arbitrary Cartesian-style kinematics. In principle, the regular +cartesian, corexy, hybrid_corexy can be defined this way too. However, +more importantly, various otherwise unsupported kinematics such as +inverted hybrid_corexy or corexyuv can be defined using this kinematic. + +Notably, the definition of a generic Cartesian kinematic deviates +significantly from the other kinematic types. It follows the following +convention: a user defines a set of carriages with certain range of motion +that can move independently from each other (they should move over the +Cartesian axes X, Y, and Z, hence the name of the kinematic) and +corresponding endstops that allow the firmware to determine the position +of carriages during homing, as well as a set of steppers that move those +carriages. The `[printer]` section must specify the kinematic and +other printer-level settings same as the regular Cartesian kinematic: +``` +[printer] +kinematics: generic_cartesian +max_velocity: +max_accel: +#minimum_cruise_ratio: +#square_corner_velocity: +#max_accel_to_decel: +#max_z_velocity: +#max_z_accel: + +``` + +Then a user must define the following three carriages: `[carriage x]`, +`[carriage y]`, and `[carriage z]`, e.g. +``` +[carriage x] +endstop_pin: +# Endstop switch detection pin. If this endstop pin is on a +# different mcu than the stepper motor(s) moving this carriage, +# then it enables "multi-mcu homing". This parameter must be provided. +#position_min: 0 +# Minimum valid distance (in mm) the user may command the carriage to +# move to. The default is 0mm. +position_endstop: +# Location of the endstop (in mm). This parameter must be provided. +position_max: +# Maximum valid distance (in mm) the user may command the stepper to +# move to. This parameter must be provided. +#homing_speed: 5.0 +# Maximum velocity (in mm/s) of the carriage when homing. The default +# is 5mm/s. +#homing_retract_dist: 5.0 +# Distance to backoff (in mm) before homing a second time during +# homing. Set this to zero to disable the second home. The default +# is 5mm. +#homing_retract_speed: +# Speed to use on the retract move after homing in case this should +# be different from the homing speed, which is the default for this +# parameter +#second_homing_speed: +# Velocity (in mm/s) of the carriage when performing the second home. +# The default is homing_speed/2. +#homing_positive_dir: +# If true, homing will cause the carriage to move in a positive +# direction (away from zero); if false, home towards zero. It is +# better to use the default than to specify this parameter. The +# default is true if position_endstop is near position_max and false +# if near position_min. +``` + +Afterwards, a user specifies the stepper motors that move these carriages, +for instance +``` +[stepper my_stepper] +carriages: +# A string describing the carriages the stepper moves. All defined +# carriages can be specified here, as well as their linear combinations, +# e.g. x, x+y, y-0.5*z, x-z, etc. This parameter must be provided. +step_pin: +dir_pin: +enable_pin: +rotation_distance: +microsteps: +#full_steps_per_rotation: 200 +#gear_ratio: +#step_pulse_duration: +``` +See [stepper](#stepper) section for more information on the regular +stepper parameters. The `carriages` parameter defines how the stepper +affects the motion of the carriages. For example, `x+y` indicates that +the motion of the stepper in the positive direction by the distance `d` +moves the carriages `x` and `y` by the same distance `d` in the positive +direction, while `x-0.5*y` means the motion of the stepper in the positive +direction by the distance `d` moves the carriage `x` by the distance `d` +in the positive direction, but the carriage `y` will travel distance `d/2` +in the negative direction. + +More than a single stepper motor can be defined to drive the same axis +or belt. For example, on a CoreXY AWD setups two motors driving the same +belt can be defined as +``` +[carriage x] +endstop_pin: ... +... + +[carriage y] +endstop_pin: ... +... + +[stepper a0] +carriages: x-y +step_pin: ... +dir_pin: ... +enable_pin: ... +rotation_distance: ... +... + +[stepper a1] +carriages: x-y +step_pin: ... +dir_pin: ... +enable_pin: ... +rotation_distance: ... +... +``` +with `a0` and `a1` steppers having their own control pins, but +sharing the same `carriages` and corresponding endstops. + +There are situations when a user wants to have more than one endstop +per axis. Examples of such configurations include Y axis driven by +two independent stepper motors with belts attached to both ends of the +X beam, with effectively two carriages on Y axis each having an +independent endstop, and multi-stepper Z axis with each stepper having +its own endstop (not to be confused with the configurations with +multiple Z motors but only a single endstop). These configurations +can be declared by specifying additional carriage(s) with their endstops: + +``` +[extra_carriage my_carriage] +primary_carriage: +# The name of the primary carriage this carriage corresponds to. +# It also effectively defines the axis the carriage moves over. +# This parameter must be provided. +endstop_pin: +# Endstop switch detection pin. This parameter must be provided. +``` + +and the corresponding stepper motors, for example: +``` +[extra_carriage y1] +primary_carriage: y +endstop_pin: ... + +[stepper sy1] +carriages: y1 +... +``` +Notably, an `[extra_carriage]` does not define parameters such as +`position_min`, `position_max`, and `position_endstop`, but instead +inherits them from the specified `primary_carriage`, thus sharing +the same range of motion with the primary carriage. + +For the references on how to configure IDEX setups, see the +[dual carriage](#dual-carriage) section. + ### None Kinematics It is possible to define a special "none" kinematics to disable @@ -2207,8 +2374,8 @@ for an example configuration. ### [dual_carriage] -Support for cartesian and hybrid_corexy/z printers with dual carriages -on a single axis. The carriage mode can be set via the +Support for cartesian, generic_cartesian and hybrid_corexy/z printers with +dual carriages on a single axis. The carriage mode can be set via the SET_DUAL_CARRIAGE extended g-code command. For example, "SET_DUAL_CARRIAGE CARRIAGE=1" command will activate the carriage defined in this section (CARRIAGE=0 will return activation to the primary carriage). @@ -2235,7 +2402,7 @@ typically be achieved with or a similar command. See [sample-idex.cfg](../config/sample-idex.cfg) for an example -configuration. +configuration with a regular Cartesian kinematic. ``` [dual_carriage] @@ -2249,7 +2416,7 @@ axis: # error. If safe_distance is not provided, it will be inferred from # position_min and position_max for the dual and primary carriages. If set # to 0 (or safe_distance is unset and position_min and position_max are -# identical for the primary and dual carraiges), the carriages proximity +# identical for the primary and dual carriages), the carriages proximity # checks will be disabled. #step_pin: #dir_pin: @@ -2263,6 +2430,62 @@ axis: # See the "stepper" section for the definition of the above parameters. ``` +For an example of dual carriage configuration with `generic_cartesian` +kinematic, see the following configuration +[sample](../config/example-generic-caretesian.cfg). +Please note that in this case the `[dual_carriage]` configuration deviates +from the configuration described above: +``` +[dual_carriage my_dc_carriage] +primary_carriage: +# Defines the matching primary carriage of this dual carriage and +# the corresponding IDEX axis. Valid choices are x, y, z. +# This parameter must be provided. +#safe_distance: +# The minimum distance (in mm) to enforce between the dual and the primary +# carriages. If a G-Code command is executed that will bring the carriages +# closer than the specified limit, such a command will be rejected with an +# error. If safe_distance is not provided, it will be inferred from +# position_min and position_max for the dual and primary carriages. If set +# to 0 (or safe_distance is unset and position_min and position_max are +# identical for the primary and dual carriages), the carriages proximity +# checks will be disabled. +endstop_pin: +#position_min: +position_endstop: +position_max: +#homing_speed: +#homing_retract_dist: +#homing_retract_speed: +#second_homing_speed: +#homing_positive_dir: +... +``` +Refer to [generic cartesian](#generic-cartesian) section for more information +on the regular `carriage` parameters. + +Then a user must define one or more stepper motors moving the dual carriage +(and other carriages as appropriate), for instance +``` +[carriage x] +... + +[carriage y] +... + +[dual_carriage u] +primary_carriage: x +... + +[stepper dc_stepper] +carriages: u-y +... +``` + +It is worth noting that `generic_cartesian` kinematic can support two +dual carriages for X and Y axes. For reference, see for instance a +[sample](../config/sample-corexyuv.cfg) of CoreXYUV configuration. + ### [extruder_stepper] Support for additional steppers synchronized to the movement of an diff --git a/docs/G-Codes.md b/docs/G-Codes.md index ae3ebc2b..b8a0ce69 100644 --- a/docs/G-Codes.md +++ b/docs/G-Codes.md @@ -341,15 +341,18 @@ The following command is available when the enabled. #### SET_DUAL_CARRIAGE -`SET_DUAL_CARRIAGE CARRIAGE=[0|1] [MODE=[PRIMARY|COPY|MIRROR]]`: +`SET_DUAL_CARRIAGE CARRIAGE=<carriage> [MODE=[PRIMARY|COPY|MIRROR]]`: This command will change the mode of the specified carriage. -If no `MODE` is provided it defaults to `PRIMARY`. Setting the mode -to `PRIMARY` deactivates the other carriage and makes the specified -carriage execute subsequent G-Code commands as-is. `COPY` and `MIRROR` -modes are supported only for `CARRIAGE=1`. When set to either of these -modes, carriage 1 will then track the subsequent moves of the carriage 0 -and either copy relative movements of it (in `COPY` mode) or execute them -in the opposite (mirror) direction (in `MIRROR` mode). +If no `MODE` is provided it defaults to `PRIMARY`. `<carriage>` must +reference a defined primary or dual carriage for `generic_cartesian` +kinematics or be 0 (for primary carriage) or 1 (for dual carriage) +for all other kinematics supporting IDEX. Setting the mode to `PRIMARY` +deactivates the other carriage and makes the specified carriage execute +subsequent G-Code commands as-is. `COPY` and `MIRROR` modes are supported +only for dual carriages. When set to either of these modes, dual carriage +will then track the subsequent moves of its primary carriage and either +copy relative movements of it (in `COPY` mode) or execute them in the +opposite (mirror) direction (in `MIRROR` mode). #### SAVE_DUAL_CARRIAGE_STATE `SAVE_DUAL_CARRIAGE_STATE [NAME=<state_name>]`: Save the current positions @@ -715,6 +718,46 @@ is specified then the toolhead move will be performed with the given speed (in mm/s); otherwise the toolhead move will use the restored g-code speed. +### [generic_cartesian] +The commands in this section become automatically available when +`kinematics: generic_cartesian` is specified as the printer kinematics. + +#### SET_STEPPER_CARRIAGES +`SET_STEPPER_CARRIAGES STEPPER=<stepper_name> CARRIAGES=<carriages> +[DISABLE_CHECKS=[0|1]]`: Set or update the stepper carriages. +`<stepper_name>` must reference an existing stepper defined in `printer.cfg`, +and `<carriages>` describes the carriages the stepper moves. See +[Generic Cartesian Kinematics](Config_Reference.md#generic-cartesian-kinematics) +for a more detailed overview of the `carriages` parameter in the +stepper configuration section. Note that it is only possible +to change the coefficients or signs of the carriages with this +command, but a user cannot add or remove the carriages that the stepper +controls. + +`SET_STEPPER_CARRIAGES` is an advanced tool, and the user is advised +to exercise an extreme caution using it, since specifying incorrect +configuration may physically damage the printer. + +Note that `SET_STEPPER_CARRIAGES` performs certain internal validations +of the new printer kinematics after the change. Keep in mind that if it +detects an issue, it may leave printer kinematics in an invalid state. +This means that if `SET_STEPPER_CARRIAGES` reports an error, it is unsafe +to issue other GCode commands, and the user must inspect the error message +and either fix the problem, or manually restore the previous stepper(s) +configuration. + +Since `SET_STEPPER_CARRIAGES` can update a configuration of a single +stepper at a time, some sequences of changes can lead to invalid +intermediate kinematic configurations, even if the final configuration +is valid. In such cases a user can pass `DISABLE_CHECKS=1` parameters to +all but the last command to disable intermediate checks. For example, +if `stepper a` and `stepper b` initially have `x-y` and `x+y` carriages +correspondingly, then the following sequence of commands will let a user +effectively swap the carriage controls: +`SET_STEPPER_CARRIAGES STEPPER=a CARRIAGES=x+y DISABLE_CHECKS=1` +and `SET_STEPPER_CARRIAGES STEPPER=b CARRIAGES=x-y`, while +still validating the final kinematics state. + ### [hall_filament_width_sensor] The following commands are available when the diff --git a/docs/Status_Reference.md b/docs/Status_Reference.md index e8f7f2c0..0276c413 100644 --- a/docs/Status_Reference.md +++ b/docs/Status_Reference.md @@ -570,6 +570,12 @@ on a cartesian, hybrid_corexy or hybrid_corexz robot - `carriage_1`: The mode of the carriage 1. Possible values are: "INACTIVE", "PRIMARY", "COPY", and "MIRROR". +On a `generic_cartesian` kinematic, the following information is +available in `dual_carriage`: +- `carriages["<carriage>"]`: The mode of the carriage `<carriage>`. Possible + values are "INACTIVE" and "PRIMARY" for the primary carriage and "INACTIVE", + "PRIMARY", "COPY", and "MIRROR" for the dual carriage. + ## virtual_sdcard The following information is available in the |