config: Update example config files to be more clear on default values

Be more clear on which parameters have defaults and which parameters
must be specified in the config.

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

1 files changed, 89 insertions, 60 deletions

diff --git a/config/example.cfg b/config/example.cfg
index c1807581..1113351b 100644
--- a/config/example.cfg
+++ b/config/example.cfg
@@ -19,27 +19,35 @@
 # the X axis in a cartesian robot
 [stepper_x]
 step_pin: ar29
-#   Step GPIO pin (triggered high)
+#   Step GPIO pin (triggered high). This parameter must be provided.
 dir_pin: !ar28
-#   Direction GPIO pin (high indicates positive direction)
+#   Direction GPIO pin (high indicates positive direction). This
+#   parameter must be provided.
 enable_pin: !ar25
-#   Enable pin (default is enable high; use ! to indicate enable low)
+#   Enable pin (default is enable high; use ! to indicate enable
+#   low). If this parameter is not provided then the stepper motor
+#   driver must always be enabled.
 step_distance: .0225
-#   Distance in mm that each step causes the axis to travel
+#   Distance in mm that each step causes the axis to travel. This
+#   parameter must be provided.
 endstop_pin: ^ar0
-#   Endstop switch detection pin
-homing_speed: 50.0
-#   Maximum velocity (in mm/s) of the stepper when homing
-homing_retract_dist: 5.0
-#   Distance to backoff (in mm) before homing a second time during homing
-homing_positive_dir: False
-#   If true, homes in a positive direction (away from zero)
-homing_stepper_phases: 0
+#   Endstop switch detection pin. This parameter must be provided for
+#   the X, Y, and Z steppers on cartesian style printers.
+#homing_speed: 5.0
+#   Maximum velocity (in mm/s) of the stepper when homing. The default
+#   is 5mm/s.
+#homing_retract_dist: 5.0
+#   Distance to backoff (in mm) before homing a second time during
+#   homing. The default is 5mm.
+#homing_positive_dir: False
+#   If true, homes in a positive direction (away from zero). The
+#   default is False.
+#homing_stepper_phases: 0
 #   One may optionally set this to the number of phases of the stepper
 #   motor driver (which is the number of micro-steps multiplied by
 #   four). When set, the phase of the stepper driver will be used
 #   during homing to improve the accuracy of the endstop switch.
-homing_endstop_accuracy: 0.200
+#homing_endstop_accuracy: 0.200
 #   Sets the expected accuracy (in mm) of the endstop. This represents
 #   the maximum error distance the endstop may trigger (eg, if an
 #   endstop may occasionally trigger 100um early or up to 100um late
@@ -56,12 +64,14 @@ homing_endstop_accuracy: 0.200
 #   phase will be used on all subsequent homes.
 position_min: -0.25
 #   Minimum valid distance (in mm) the user may command the stepper to
-#   move to
+#   move to.  The default is 0mm.
 position_endstop: 0
-#   Location of the endstop (in mm)
+#   Location of the endstop (in mm). This parameter must be provided
+#   for the X, Y, and Z steppers on cartesian style printers.
 position_max: 200
 #   Maximum valid distance (in mm) the user may command the stepper to
-#   move to
+#   move to. This parameter must be provided for the X, Y, and Z
+#   steppers on cartesian style printers.
 
 # The stepper_y section is used to describe the stepper controlling
 # the Y axis in a cartesian robot. It has the same settings as the
@@ -101,46 +111,59 @@ enable_pin: !ar25
 step_distance: .004242
 max_velocity: 200000
 #   Maximum velocity (in mm/s) of the extruder motor for extrude only
-#   moves.
+#   moves. This parameter must be provided.
 max_accel: 3000
 #   Maximum acceleration (in mm/s^2) of the extruder motor for extrude
-#   only moves.
-#
-# The remaining variables describe the extruder heater
-pressure_advance: 0.0
+#   only moves. This parameter must be provided.
+#pressure_advance: 0.0
 #   The amount of raw filament to push into the extruder during
 #   extruder acceleration. An equal amount of filament is retracted
 #   during deceleration. It is measured in millimeters per
-#   millimeter/second
+#   millimeter/second. The default is 0, which disables pressure
+#   advance.
+#
+# The remaining variables describe the extruder heater
 heater_pin: ar4
-#   PWM output pin controlling the heater
+#   PWM output pin controlling the heater. This parameter must be
+#   provided.
 thermistor_pin: analog1
-#   Analog input pin connected to thermistor
+#   Analog input pin connected to thermistor. This parameter must be
+#   provided.
 thermistor_type: EPCOS 100K B57560G104F
-#   Type of thermistor (see klippy/heater.py for available types)
-pullup_resistor: 4700
-#   The resistance (in ohms) of the pullup attached to the thermistor
+#   Type of thermistor (see the Thermistors variable at the top of
+#   klippy/heater.py for available types). This parameter must be
+#   provided.
+#pullup_resistor: 4700
+#   The resistance (in ohms) of the pullup attached to the
+#   thermistor. The default is 4700 ohms.
 control: pid
-#   Control algorithm (either pid or watermark)
+#   Control algorithm (either pid or watermark). This parameter must
+#   be provided.
 pid_Kp: 22.2
-#   Kp is the "proportional" constant for the pid
+#   Kp is the "proportional" constant for the pid. This parameter must
+#   be provided for PID heaters.
 pid_Ki: 1.08
-#   Ki is the "integral" constant for the pid
+#   Ki is the "integral" constant for the pid. This parameter must be
+#   provided for PID heaters.
 pid_Kd: 114
-#   Kd is the "derivative" constant for the pid
-pid_deriv_time: 2.0
+#   Kd is the "derivative" constant for the pid. This parameter must
+#   be provided for PID heaters.
+#pid_deriv_time: 2.0
 #   A time value (in seconds) over which the derivative in the pid
-#   will be smoothed to reduce the impact of measurement noise
-pid_integral_max: 255
-#   The maximum "windup" the integral term may accumulate
-min_extrude_temp: 170
+#   will be smoothed to reduce the impact of measurement noise. The
+#   default is 2 seconds.
+#pid_integral_max: 255
+#   The maximum "windup" the integral term may accumulate. The default
+#   is 255.
+#min_extrude_temp: 170
 #   The minimum temperature (in Celsius) at which extruder move
-#   commands may be issued
+#   commands may be issued. The default is 170 Celsius.
 min_temp: 0
-#   Minimum temperature in Celsius (mcu will shutdown if not met)
+#   Minimum temperature in Celsius (mcu will shutdown if not
+#   met). This parameter must be provided.
 max_temp: 210
 #   Maximum temperature (mcu will shutdown if temperature is above
-#   this value)
+#   this value). This parameter must be provided.
 
 # The heater_bed section describes a heated bed (if present - omit
 # section if not present).
@@ -149,34 +172,37 @@ heater_pin: ar3
 thermistor_pin: analog0
 thermistor_type: EPCOS 100K B57560G104F
 control: watermark
-max_delta: 2.0
-#   The number of degrees in Celsius above the target temperature
-#   before disabling the heater as well as the number of degrees below
-#   the target before re-enabling the heater.
+#max_delta: 2.0
+#   On 'watermark' controlled heaters this is the number of degrees in
+#   Celsius above the target temperature before disabling the heater
+#   as well as the number of degrees below the target before
+#   re-enabling the heater. The default is 2 degrees Celsius.
 min_temp: 0
 max_temp: 110
 
 # Extruder print fan (omit section if fan not present)
 [fan]
 pin: ar14
-#   PWM output pin controlling the heater
+#   PWM output pin controlling the heater. This parameter must be
+#   provided.
 hard_pwm: 1
 #   Set this value to force hardware PWM instead of software PWM. Set
 #   to 1 to force a hardware PWM at the fastest rate; set to a higher
 #   number (eg, 1024) to force hardware PWM with the given cycle time
-#   in clock ticks.
-kick_start_time: 0.100
+#   in clock ticks. The default is 128 clock ticks.
+#kick_start_time: 0.100
 #   Time (in seconds) to run the fan at full speed when first enabling
-#   it (helps get the fan spinning)
+#   it (helps get the fan spinning). The default is 0.100 seconds.
 
 # Micro-controller information
 [mcu]
 serial: /dev/ttyACM0
-#   The serial port to connect to the MCU
-baud: 250000
-#   The baud rate to use
+#   The serial port to connect to the MCU. The default is /dev/ttyS0
+#baud: 250000
+#   The baud rate to use. The default is 250000.
 pin_map: arduino
-#   This option may be used to enable Arduino pin name aliases
+#   This option may be used to enable Arduino pin name aliases. The
+#   default is to not enable the aliases.
 custom:
 #   This option may be used to specify a set of custom
 #   micro-controller commands to be sent at the start of the
@@ -187,25 +213,28 @@ custom:
 # The printer section controls high level printer settings
 [printer]
 kinematics: cartesian
-#   This option must be "cartesian" for cartesian printers
+#   This option must be "cartesian" for cartesian printers.
 max_velocity: 500
 #   Maximum velocity (in mm/s) of the toolhead (relative to the
-#   print)
+#   print). This parameter must be specified.
 max_accel: 3000
 #   Maximum acceleration (in mm/s^2) of the toolhead (relative to the
-#   print)
+#   print). This parameter must be specified.
 max_z_velocity: 250
 #   For cartesian printers this sets the maximum velocity (in mm/s) of
 #   movement along the z axis. This setting can be used to restrict
-#   the maximum speed of the z stepper motor on cartesian printers.
+#   the maximum speed of the z stepper motor on cartesian
+#   printers. The default is to use max_velocity for max_z_velocity.
 max_z_accel: 30
 #   For cartesian printers this sets the maximum acceleration (in
 #   mm/s^2) of movement along the z axis. It limits the acceleration
-#   of the z stepper motor on cartesian printers.
-motor_off_time: 60
+#   of the z stepper motor on cartesian printers. The default is to
+#   use max_accel for max_z_accel.
+#motor_off_time: 60
 #   Time (in seconds) of idle time before the printer will try to
-#   disable active motors.
-junction_deviation: 0.02
+#   disable active motors. The default is 60 seconds.
+#junction_deviation: 0.02
 #   Distance (in mm) used to control the internal approximated
 #   centripetal velocity cornering algorithm. A larger number will
-#   permit higher "cornering speeds" at the junction of two moves.
+#   permit higher "cornering speeds" at the junction of two moves. The
+#   default is 0.02mm.