docs: Add Example_Configs.md - info on adding new config files to Klipper

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>
This commit is contained in:
Kevin O'Connor 2021-03-22 21:05:54 -04:00
parent 8a3a32058f
commit 8524188203
2 changed files with 76 additions and 0 deletions

74
docs/Example_Configs.md Normal file
View File

@ -0,0 +1,74 @@
This document contains guidelines for contributing an example Klipper
configuration.
The example Klipper configs are located in the [config
directory](../config/).
# Guidelines
1. Select the appropriate config filename prefix.
1. The `printer` prefix is used for stock printers sold by a
mainstream manufacturer.
2. The `generic` prefix is used for a 3d printer board that may be
used in many different types of printers.
3. The `kit` prefix is for 3d printers that are assembled according
to a widely used specification. These "kit" printers are
generally distinct from normal "printers" in that they are not
sold by a manufacturer.
4. The `sample` prefix is used for config "snippets" that one may
copy-and-paste into the main config file.
5. The `example` prefix is used to describe printer kinematics.
This type of config is typically only added along with code for
a new type of printer kinematics.
2. Use the appropriate filename suffix. The `printer` config files
must end in a year followed by `.cfg` (eg, `-2019.cfg`). In this
case, the year is an approximate year the given printer was
sold. All example configuration files must end in `.cfg`.
3. Klipper must be able to start `printer`, `generic`, and `kit`
example config file without error. These config files should be
added to the
[test/klippy/printers.test](../test/klippy/printers.test)
regression test case. Add new config files to that test case in the
appropriate section and in alphabetical order within that section.
4. The example configuration should be for the "stock" configuration
of the printer. (There are too many "customized" configurations to
track in the main Klipper repository.) Similarly, we only add
example config files for printers, kits, and boards that have
mainstream popularity (eg, there should be at least a 100 of them
in active use).
1. For `generic` config files, only those devices on the mainboard
should be described. For example, it would not make sense to add
a display config section to a "generic" config as there is no
way to know if the board will be attached to that type of
display. If the board has a specific hardware port to facilitate
an optional peripheral (eg, a bltouch port) then one can add a
"commented out" config section for the given device.
5. Where possible, it is best to use the same wording, phrasing, and
indentation as the existing config files.
1. The top of each config file should list the type of
micro-controller the user should select during "make
menuconfig". It should also have a reference to
"docs/Config_Reference.md".
2. Do not copy the field documentation into the example config
files. (Doing so creates a maintenance burden as an update to
the documentation would then require changing it in many
places.)
3. Example config files should not contain a "SAVE_CONFIG" section.
If necessary, copy the relevant fields from the SAVE_CONFIG
section to the appropriate section in the main config area.
4. Use `field: value` syntax instead of `field=value`.
5. When adding an extruder `rotation_distance` it is preferable to
specify a `gear_ratio` if the extruder has a gearing mechanism.
We expect the rotation_distance in the example configs to
correlate with the circumference of the hobbed gear in the
extruder - it is normally in the range of 20 to 35mm. When
specifying a `gear_ratio` it is preferable to specify the actual
gears on the mechanism (eg, prefer `gear_ratio: 80:20` over
`gear_ratio: 4:1`).
6. Do not use any deprecated features in the example config file. The
`step_distance` parameter is deprecated and should not be in any
example config file.
Example config files are submitted by creating a github "pull
request". Please also follow the directions in the [contributing
document](CONTRIBUTING.md).

View File

@ -52,6 +52,8 @@ communication with the Klipper developers.
- [Code overview](Code_Overview.md): Developers should read this
first.
- [Example configs](Example_Configs.md): Information on adding an
example config file to Klipper.
- [Kinematics](Kinematics.md): Technical details on how Klipper
implements motion.
- [Protocol](Protocol.md): Information on the low-level messaging