- - - - - - - -Code overview¶ -This document describes the overall code layout and major code flow of -Klipper. -Directory Layout¶ -The src/ directory contains the C source for the micro-controller -code. The src/atsam/, src/atsamd/, src/avr/, -src/linux/, src/lpc176x/, src/pru/, and src/stm32/ -directories contain architecture specific micro-controller code. The -src/simulator/ contains code stubs that allow the micro-controller -to be test compiled on other architectures. The src/generic/ -directory contains helper code that may be useful across different -architectures. The build arranges for includes of "board/somefile.h" -to first look in the current architecture directory (eg, -src/avr/somefile.h) and then in the generic directory (eg, -src/generic/somefile.h). -The klippy/ directory contains the host software. Most of the host -software is written in Python, however the klippy/chelper/ -directory contains some C code helpers. The klippy/kinematics/ -directory contains the robot kinematics code. The klippy/extras/ -directory contains the host code extensible "modules". -The lib/ directory contains external 3rd-party library code that -is necessary to build some targets. -The config/ directory contains example printer configuration -files. -The scripts/ directory contains build-time scripts useful for -compiling the micro-controller code. -The test/ directory contains automated test cases. -During compilation, the build may create an out/ directory. This -contains temporary build time objects. The final micro-controller -object that is built is out/klipper.elf.hex on AVR and -out/klipper.bin on ARM. -Micro-controller code flow¶ -Execution of the micro-controller code starts in architecture specific -code (eg, src/avr/main.c) which ultimately calls sched_main() -located in src/sched.c. The sched_main() code starts by running -all functions that have been tagged with the DECL_INIT() macro. It -then goes on to repeatedly run all functions tagged with the -DECL_TASK() macro. -One of the main task functions is command_dispatch() located in -src/command.c. This function is called from the board specific -input/output code (eg, src/avr/serial.c, -src/generic/serial_irq.c) and it runs the command functions -associated with the commands found in the input stream. Command -functions are declared using the DECL_COMMAND() macro (see the -protocol document for more information). -Task, init, and command functions always run with interrupts enabled -(however, they can temporarily disable interrupts if needed). These -functions should never pause, delay, or do any work that lasts more -than a few micro-seconds. These functions schedule work at specific -times by scheduling timers. -Timer functions are scheduled by calling sched_add_timer() (located in -src/sched.c). The scheduler code will arrange for the given -function to be called at the requested clock time. Timer interrupts -are initially handled in an architecture specific interrupt handler -(eg, src/avr/timer.c) which calls sched_timer_dispatch() located -in src/sched.c. The timer interrupt leads to execution of schedule -timer functions. Timer functions always run with interrupts disabled. -The timer functions should always complete within a few micro-seconds. -At completion of the timer event, the function may choose to -reschedule itself. -In the event an error is detected the code can invoke shutdown() (a -macro which calls sched_shutdown() located in src/sched.c). -Invoking shutdown() causes all functions tagged with the -DECL_SHUTDOWN() macro to be run. Shutdown functions always run with -interrupts disabled. -Much of the functionality of the micro-controller involves working -with General-Purpose Input/Output pins (GPIO). In order to abstract -the low-level architecture specific code from the high-level task -code, all GPIO events are implemented in architecture specific -wrappers (eg, src/avr/gpio.c). The code is compiled with gcc's -"-flto -fwhole-program" optimization which does an excellent job of -inlining functions across compilation units, so most of these tiny -gpio functions are inlined into their callers, and there is no -run-time cost to using them. -Klippy code overview¶ -The host code (Klippy) is intended to run on a low-cost computer (such -as a Raspberry Pi) paired with the micro-controller. The code is -primarily written in Python, however it does use CFFI to implement -some functionality in C code. -Initial execution starts in klippy/klippy.py. This reads the -command-line arguments, opens the printer config file, instantiates -the main printer objects, and starts the serial connection. The main -execution of G-code commands is in the process_commands() method in -klippy/gcode.py. This code translates the G-code commands into -printer object calls, which frequently translate the actions to -commands to be executed on the micro-controller (as declared via the -DECL_COMMAND macro in the micro-controller code). -There are four threads in the Klippy host code. The main thread -handles incoming gcode commands. A second thread (which resides -entirely in the klippy/chelper/serialqueue.c C code) handles -low-level IO with the serial port. The third thread is used to process -response messages from the micro-controller in the Python code (see -klippy/serialhdl.py). The fourth thread writes debug messages to -the log (see klippy/queuelogger.py) so that the other threads -never block on log writes. -Code flow of a move command¶ -A typical printer movement starts when a "G1" command is sent to the -Klippy host and it completes when the corresponding step pulses are -produced on the micro-controller. This section outlines the code flow -of a typical move command. The kinematics document -provides further information on the mechanics of moves. - -Processing for a move command starts in gcode.py. The goal of - gcode.py is to translate G-code into internal calls. A G1 command - will invoke cmd_G1() in klippy/extras/gcode_move.py. The - gcode_move.py code handles changes in origin (eg, G92), changes in - relative vs absolute positions (eg, G90), and unit changes (eg, - F6000=100mm/s). The code path for a move is: _process_data() -> - _process_commands() -> cmd_G1(). Ultimately the ToolHead class is - invoked to execute the actual request: cmd_G1() -> ToolHead.move() - - -The ToolHead class (in toolhead.py) handles "look-ahead" and tracks - the timing of printing actions. The main codepath for a move is: - ToolHead.move() -> MoveQueue.add_move() -> MoveQueue.flush() -> - Move.set_junction() -> ToolHead._process_moves(). -ToolHead.move() creates a Move() object with the parameters of the -move (in cartesian space and in units of seconds and millimeters). -The kinematics class is given the opportunity to audit each move -(ToolHead.move() -> kin.check_move()). The kinematics classes are -located in the klippy/kinematics/ directory. The check_move() code -may raise an error if the move is not valid. If check_move() -completes successfully then the underlying kinematics must be able -to handle the move. -MoveQueue.add_move() places the move object on the "look-ahead" -queue. -MoveQueue.flush() determines the start and end velocities of each -move. -Move.set_junction() implements the "trapezoid generator" on a -move. The "trapezoid generator" breaks every move into three parts: -a constant acceleration phase, followed by a constant velocity -phase, followed by a constant deceleration phase. Every move -contains these three phases in this order, but some phases may be of -zero duration. -When ToolHead._process_moves() is called, everything about the -move is known - its start location, its end location, its -acceleration, its start/cruising/end velocity, and distance traveled -during acceleration/cruising/deceleration. All the information is -stored in the Move() class and is in cartesian space in units of -millimeters and seconds. - - - - -Klipper uses an - iterative solver - to generate the step times for each stepper. For efficiency reasons, - the stepper pulse times are generated in C code. The moves are first - placed on a "trapezoid motion queue": ToolHead._process_moves() -> - trapq_append() (in klippy/chelper/trapq.c). The step times are then - generated: ToolHead._process_moves() -> - ToolHead._update_move_time() -> MCU_Stepper.generate_steps() -> - itersolve_generate_steps() -> itersolve_gen_steps_range() (in - klippy/chelper/itersolve.c). The goal of the iterative solver is to - find step times given a function that calculates a stepper position - from a time. This is done by repeatedly "guessing" various times - until the stepper position formula returns the desired position of - the next step on the stepper. The feedback produced from each guess - is used to improve future guesses so that the process rapidly - converges to the desired time. The kinematic stepper position - formulas are located in the klippy/chelper/ directory (eg, - kin_cart.c, kin_corexy.c, kin_delta.c, kin_extruder.c). - - -Note that the extruder is handled in its own kinematic class: - ToolHead._process_moves() -> PrinterExtruder.move(). Since - the Move() class specifies the exact movement time and since step - pulses are sent to the micro-controller with specific timing, - stepper movements produced by the extruder class will be in sync - with head movement even though the code is kept separate. - - -After the iterative solver calculates the step times they are added - to an array: itersolve_gen_steps_range() -> stepcompress_append() - (in klippy/chelper/stepcompress.c). The array (struct - stepcompress.queue) stores the corresponding micro-controller clock - counter times for every step. Here the "micro-controller clock - counter" value directly corresponds to the micro-controller's - hardware counter - it is relative to when the micro-controller was - last powered up. - - -The next major step is to compress the steps: stepcompress_flush() - -> compress_bisect_add() (in klippy/chelper/stepcompress.c). This - code generates and encodes a series of micro-controller "queue_step" - commands that correspond to the list of stepper step times built in - the previous stage. These "queue_step" commands are then queued, - prioritized, and sent to the micro-controller (via - stepcompress.c:steppersync and serialqueue.c:serialqueue). - - -Processing of the queue_step commands on the micro-controller starts - in src/command.c which parses the command and calls - command_queue_step(). The command_queue_step() code (in - src/stepper.c) just appends the parameters of each queue_step - command to a per stepper queue. Under normal operation the - queue_step command is parsed and queued at least 100ms before the - time of its first step. Finally, the generation of stepper events is - done in stepper_event(). It's called from the hardware timer - interrupt at the scheduled time of the first step. The - stepper_event() code generates a step pulse and then reschedules - itself to run at the time of the next step pulse for the given - queue_step parameters. The parameters for each queue_step command - are "interval", "count", and "add". At a high-level, stepper_event() - runs the following, 'count' times: do_step(); next_wake_time = - last_wake_time + interval; interval += add; - -The above may seem like a lot of complexity to execute a movement. -However, the only really interesting parts are in the ToolHead and -kinematic classes. It's this part of the code which specifies the -movements and their timings. The remaining parts of the processing is -mostly just communication and plumbing. -Adding a host module¶ -The Klippy host code has a dynamic module loading capability. If a -config section named "[my_module]" is found in the printer config file -then the software will automatically attempt to load the python module -klippy/extras/my_module.py . This module system is the preferred -method for adding new functionality to Klipper. -The easiest way to add a new module is to use an existing module as a -reference - see klippy/extras/servo.py as an example. -The following may also be useful: - -Execution of the module starts in the module level load_config() - function (for config sections of the form [my_module]) or in - load_config_prefix() (for config sections of the form - [my_module my_name]). This function is passed a "config" object and - it must return a new "printer object" associated with the given - config section. -During the process of instantiating a new printer object, the config - object can be used to read parameters from the given config - section. This is done using config.get(), config.getfloat(), - config.getint(), etc. methods. Be sure to read all values from the - config during the construction of the printer object - if the user - specifies a config parameter that is not read during this phase then - it will be assumed it is a typo in the config and an error will be - raised. -Use the config.get_printer() method to obtain a reference to the - main "printer" class. This "printer" class stores references to all - the "printer objects" that have been instantiated. Use the - printer.lookup_object() method to find references to other printer - objects. Almost all functionality (even core kinematic modules) are - encapsulated in one of these printer objects. Note, though, that - when a new module is instantiated, not all other printer objects - will have been instantiated. The "gcode" and "pins" modules will - always be available, but for other modules it is a good idea to - defer the lookup. -Register event handlers using the printer.register_event_handler() - method if the code needs to be called during "events" raised by - other printer objects. Each event name is a string, and by - convention it is the name of the main source module that raises the - event along with a short name for the action that is occurring (eg, - "klippy:connect"). The parameters passed to each event handler are - specific to the given event (as are exception handling and execution - context). Two common startup events are: -klippy:connect - This event is generated after all printer objects - are instantiated. It is commonly used to lookup other printer - objects, to verify config settings, and to perform an initial - "handshake" with printer hardware. -klippy:ready - This event is generated after all connect handlers - have completed successfully. It indicates the printer is - transitioning to a state ready to handle normal operations. Do not - raise an error in this callback. - - -If there is an error in the user's config, be sure to raise it - during the load_config() or "connect event" phases. Use either - raise config.error("my error") or raise printer.config_error("my - error") to report the error. -Use the "pins" module to configure a pin on a micro-controller. This - is typically done with something similar to - printer.lookup_object("pins").setup_pin("pwm", - config.get("my_pin")). The returned object can then be commanded at - run-time. -If the printer object defines a get_status() method then the - module can export status information via - macros and via the - API Server. The get_status() method must return a - Python dictionary with keys that are strings and values that are - integers, floats, strings, lists, dictionaries, True, False, or - None. Tuples (and named tuples) may also be used (these appear as - lists when accessed via the API Server). Lists and dictionaries that - are exported must be treated as "immutable" - if their contents - change then a new object must be returned from get_status(), - otherwise the API Server will not detect those changes. -If the module needs access to system timing or external file - descriptors then use printer.get_reactor() to obtain access to the - global "event reactor" class. This reactor class allows one to - schedule timers, wait for input on file descriptors, and to "sleep" - the host code. -Do not use global variables. All state should be stored in the - printer object returned from the load_config() function. This is - important as otherwise the RESTART command may not perform as - expected. Also, for similar reasons, if any external files (or - sockets) are opened then be sure to register a "klippy:disconnect" - event handler and close them from that callback. -Avoid accessing the internal member variables (or calling methods - that start with an underscore) of other printer objects. Observing - this convention makes it easier to manage future changes. -It is recommended to assign a value to all member variables in the - Python constructor of Python classes. (And therefore avoid utilizing - Python's ability to dynamically create new member variables.) -If a Python variable is to store a floating point value then it is - recommended to always assign and manipulate that variable with - floating point constants (and never use integer constants). For - example, prefer self.speed = 1. over self.speed = 1, and prefer - self.speed = 2. * x over self.speed = 2 * x. Consistent use of - floating point values can avoid hard to debug quirks in Python type - conversions. -If submitting the module for inclusion in the main Klipper code, be - sure to place a copyright notice at the top of the module. See the - existing modules for the preferred format. - -Adding new kinematics¶ -This section provides some tips on adding support to Klipper for -additional types of printer kinematics. This type of activity requires -excellent understanding of the math formulas for the target -kinematics. It also requires software development skills - though one -should only need to update the host software. -Useful steps: - -Start by studying the - "code flow of a move" section and - the Kinematics document. -Review the existing kinematic classes in the klippy/kinematics/ - directory. The kinematic classes are tasked with converting a move - in cartesian coordinates to the movement on each stepper. One - should be able to copy one of these files as a starting point. -Implement the C stepper kinematic position functions for each - stepper if they are not already available (see kin_cart.c, - kin_corexy.c, and kin_delta.c in klippy/chelper/). The function - should call move_get_coord() to convert a given move time (in - seconds) to a cartesian coordinate (in millimeters), and then - calculate the desired stepper position (in millimeters) from that - cartesian coordinate. -Implement the calc_position() method in the new kinematics class. - This method calculates the position of the toolhead in cartesian - coordinates from the position of each stepper. It does not need to - be efficient as it is typically only called during homing and - probing operations. -Other methods. Implement the check_move(), get_status(), - get_steppers(), home(), and set_position() methods. These - functions are typically used to provide kinematic specific checks. - However, at the start of development one can use boiler-plate code - here. -Implement test cases. Create a g-code file with a series of moves - that can test important cases for the given kinematics. Follow the - debugging documentation to convert this g-code file - to micro-controller commands. This is useful to exercise corner - cases and to check for regressions. - -Porting to a new micro-controller¶ -This section provides some tips on porting Klipper's micro-controller -code to a new architecture. This type of activity requires good -knowledge of embedded development and hands-on access to the target -micro-controller. -Useful steps: - -Start by identifying any 3rd party libraries that will be used - during the port. Common examples include "CMSIS" wrappers and - manufacturer "HAL" libraries. All 3rd party code needs to be GNU - GPLv3 compatible. The 3rd party code should be committed to the - Klipper lib/ directory. Update the lib/README file with information - on where and when the library was obtained. It is preferable to - copy the code into the Klipper repository unchanged, but if any - changes are required then those changes should be listed explicitly - in the lib/README file. -Create a new architecture sub-directory in the src/ directory and - add initial Kconfig and Makefile support. Use the existing - architectures as a guide. The src/simulator provides a basic - example of a minimum starting point. -The first main coding task is to bring up communication support to - the target board. This is the most difficult step in a new port. - Once basic communication is working, the remaining steps tend to be - much easier. It is typical to use a UART type serial device during - initial development as these types of hardware devices are - generally easier to enable and control. During this phase, make - liberal use of helper code from the src/generic/ directory (check - how src/simulator/Makefile includes the generic C code into the - build). It is also necessary to define timer_read_time() (which - returns the current system clock) in this phase, but it is not - necessary to fully support timer irq handling. -Get familiar with the the console.py tool (as described in the - debugging document) and verify connectivity to the - micro-controller with it. This tool translates the low-level - micro-controller communication protocol to a human readable form. -Add support for timer dispatch from hardware interrupts. See - Klipper - commit 970831ee - as an example of steps 1-5 done for the LPC176x architecture. -Bring up basic GPIO input and output support. See Klipper - commit c78b9076 - as an example of this. -Bring up additional peripherals - for example see Klipper commit - 65613aed, - c812a40a, - and - c381d03a. -Create a sample Klipper config file in the config/ directory. Test - the micro-controller with the main klippy.py program. -Consider adding build test cases in the test/ directory. - -Additional coding tips: - -Avoid using "C bitfields" to access IO registers; prefer direct - read and write operations of 32bit, 16bit, or 8bit integers. The C - language specifications don't clearly specify how the compiler must - implement C bitfields (eg, endianness, and bit layout), and it's - difficult to determine what IO operations will occur on a C - bitfield read or write. -Prefer writing explicit values to IO registers instead of using - read-modify-write operations. That is, if updating a field in an IO - register where the other fields have known values, then it is - preferable to explicitly write the full contents of the register. - Explicit writes produce code that is smaller, faster, and easier to - debug. - -Coordinate Systems¶ -Internally, Klipper primarily tracks the position of the toolhead in -cartesian coordinates that are relative to the coordinate system -specified in the config file. That is, most of the Klipper code will -never experience a change in coordinate systems. If the user makes a -request to change the origin (eg, a G92 command) then that effect is -obtained by translating future commands to the primary 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. 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 of the given stepper as tracked by the kinematics code. This -generally corresponds to the position (in mm) of the carriage along -its rail, relative to the position_endstop specified in the config -file. (Some kinematics track stepper positions 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.calc_position()) is the cartesian -position of the toolhead as derived from "stepper" positions 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 the -"stepper" positions are taken 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_move.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¶ -Fundamental to the operation of Klipper is the handling of clocks, -times, and timestamps. Klipper executes actions on the printer by -scheduling events to occur in the near future. For example, to turn on -a fan, the code might schedule a change to a GPIO pin in a 100ms. It -is rare for the code to attempt to take an instantaneous action. Thus, -the handling of time within Klipper is critical to correct operation. -There are three types of times tracked internally in the Klipper host -software: - -System time. The system time uses the system's monotonic clock - it - is a floating point number stored as seconds and it is (generally) - relative to when the host computer was last started. System times - have limited use in the software - they are primarily used when - interacting with the operating system. Within the host code, system - times are frequently stored in variables named eventtime or - curtime. -Print time. The print time is synchronized to the main - micro-controller clock (the micro-controller defined in the "[mcu]" - config section). It is a floating point number stored as seconds and - is relative to when the main mcu was last restarted. It is possible - to convert from a "print time" to the main micro-controller's - hardware clock by multiplying the print time by the mcu's statically - configured frequency rate. The high-level host code uses print times - to calculate almost all physical actions (eg, head movement, heater - changes, etc.). Within the host code, print times are generally - stored in variables named print_time or move_time. -MCU clock. This is the hardware clock counter on each - micro-controller. It is stored as an integer and its update rate is - relative to the frequency of the given micro-controller. The host - software translates its internal times to clocks before transmission - to the mcu. The mcu code only ever tracks time in clock - ticks. Within the host code, clock values are tracked as 64bit - integers, while the mcu code uses 32bit integers. Within the host - code, clocks are generally stored in variables with names containing - clock or ticks. - -Conversion between the different time formats is primarily implemented -in the klippy/clocksync.py code. -Some things to be aware of when reviewing the code: - -32bit and 64bit clocks: To reduce bandwidth and to improve - micro-controller efficiency, clocks on the micro-controller are - tracked as 32bit integers. When comparing two clocks in the mcu - code, the timer_is_before() function must always be used to ensure - integer rollovers are handled properly. The host software converts - 32bit clocks to 64bit clocks by appending the high-order bits from - the last mcu timestamp it has received - no message from the mcu is - ever more than 2^31 clock ticks in the future or past so this - conversion is never ambiguous. The host converts from 64bit clocks - to 32bit clocks by simply truncating the high-order bits. To ensure - there is no ambiguity in this conversion, the - klippy/chelper/serialqueue.c code will buffer messages until - they are within 2^31 clock ticks of their target time. -Multiple micro-controllers: The host software supports using - multiple micro-controllers on a single printer. In this case, the - "MCU clock" of each micro-controller is tracked separately. The - clocksync.py code handles clock drift between micro-controllers by - modifying the way it converts from "print time" to "MCU clock". On - secondary mcus, the mcu frequency that is used in this conversion is - regularly updated to account for measured drift. - - - -
- - - - - - - -Frequently Asked Questions¶ - -How can I donate to the project? -How do I calculate the rotation_distance config parameter? -Where's my serial port? -When the micro-controller restarts the device changes to /dev/ttyUSB1 -The "make flash" command doesn't work -How do I change the serial baud rate? -Can I run Klipper on something other than a Raspberry Pi 3? -Can I run multiple instances of Klipper on the same host machine? -Do I have to use OctoPrint? -Why can't I move the stepper before homing the printer? -Why is the Z position_endstop set to 0.5 in the default configs? -I converted my config from Marlin and the X/Y axes work fine, but I just get a screeching noise when homing the Z axis -My TMC motor driver turns off in the middle of a print -I keep getting random "Lost communication with MCU" errors -My Raspberry Pi keeps rebooting during prints -When I set restart_method=command my AVR device just hangs on a restart -Will the heaters be left on if the Raspberry Pi crashes? -How do I convert a Marlin pin number to a Klipper pin name? -Do I have to wire my device to a specific type of micro-controller pin? -How do I cancel an M109/M190 "wait for temperature" request? -Can I find out whether the printer has lost steps? -Why does Klipper report errors? I lost my print! -How do I upgrade to the latest software? -How do I uninstall klipper? - -How can I donate to the project?¶ -Thanks. Kevin has a Patreon page at: -https://www.patreon.com/koconnor -How do I calculate the rotation_distance config parameter?¶ -See the rotation distance document. -Where's my serial port?¶ -The general way to find a USB serial port is to run ls -/dev/serial/by-id/* from an ssh terminal on the host machine. It will -likely produce output similar to the following: -/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 - - -The name found in the above command is stable and it is possible to -use it in the config file and while flashing the micro-controller -code. For example, a flash command might look similar to: -sudo service klipper stop -make flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 -sudo service klipper start - - -and the updated config might look like: -[mcu] -serial: /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0 - - -Be sure to copy-and-paste the name from the "ls" command that you ran -above as the name will be different for each printer. -If you are using multiple micro-controllers and they do not have -unique ids (common on boards with a CH340 USB chip) then follow the -directions above using the command ls /dev/serial/by-path/* instead. -When the micro-controller restarts the device changes to /dev/ttyUSB1¶ -Follow the directions in the -"Where's my serial port?" section to prevent -this from occurring. -The "make flash" command doesn't work¶ -The code attempts to flash the device using the most common method for -each platform. Unfortunately, there is a lot of variance in flashing -methods, so the "make flash" command may not work on all boards. -If you're having an intermittent failure or you do have a standard -setup, then double check that Klipper isn't running when flashing -(sudo service klipper stop), make sure OctoPrint isn't trying to -connect directly to the device (open the Connection tab in the web -page and click Disconnect if the Serial Port is set to the device), -and make sure FLASH_DEVICE is set correctly for your board (see the -question above). -However, if "make flash" just doesn't work for your board, then you -will need to manually flash. See if there is a config file in the -config directory with specific instructions for flashing -the device. Also, check the board manufacturer's documentation to see -if it describes how to flash the device. Finally, it may be possible -to manually flash the device using tools such as "avrdude" or -"bossac" - see the bootloader document for -additional information. -How do I change the serial baud rate?¶ -The recommended baud rate for Klipper is 250000. This baud rate works -well on all micro-controller boards that Klipper supports. If you've -found an online guide recommending a different baud rate, then ignore -that part of the guide and continue with the default value of 250000. -If you want to change the baud rate anyway, then the new rate will -need to be configured in the micro-controller (during make -menuconfig) and that updated code will need to be compiled and -flashed to the micro-controller. The Klipper printer.cfg file will -also need to be updated to match that baud rate (see the -config reference for details). For -example: -[mcu] -baud: 250000 - - -The baud rate shown on the OctoPrint web page has no impact on the -internal Klipper micro-controller baud rate. Always set the OctoPrint -baud rate to 250000 when using Klipper. -The Klipper micro-controller baud rate is not related to the baud rate -of the micro-controller's bootloader. See the -bootloader document for additional information on -bootloaders. -Can I run Klipper on something other than a Raspberry Pi 3?¶ -The recommended hardware is a Raspberry Pi 2, Raspberry Pi 3, or -Raspberry Pi 4. -Klipper will run on a Raspberry Pi 1 and on the Raspberry Pi Zero, but -these boards don't have enough processing power to run OctoPrint -well. It is common for print stalls to occur on these slower machines -when printing directly from OctoPrint. (The printer may move faster -than OctoPrint can send movement commands.) If you wish to run on one -one of these slower boards anyway, consider using the "virtual_sdcard" -feature when printing (see -config reference for details). -For running on the Beaglebone, see the -Beaglebone specific installation instructions. -Klipper has been run on other machines. The Klipper host software only -requires Python running on a Linux (or similar) computer. However, if -you wish to run it on a different machine you will need Linux admin -knowledge to install the system prerequisites for that particular -machine. See the install-octopi.sh -script for further information on the necessary Linux admin steps. -If you are looking to run the Klipper host software on a low-end chip, -then be aware that, at a minimum, a machine with "double precision -floating point" hardware is required. -If you are looking to run the Klipper host software on a shared -general-purpose desktop or server class machine, then note that -Klipper has some real-time scheduling requirements. If, during a -print, the host computer also performs an intensive general-purpose -computing task (such as defragmenting a hard drive, 3d rendering, -heavy swapping, etc.), then it may cause Klipper to report print -errors. -Note: If you are not using an OctoPi image, be aware that several -Linux distributions enable a "ModemManager" (or similar) package that -can disrupt serial communication. (Which can cause Klipper to report -seemingly random "Lost communication with MCU" errors.) If you install -Klipper on one of these distributions you may need to disable that -package. -Can I run multiple instances of Klipper on the same host machine?¶ -It is possible to run multiple instances of the Klipper host software, -but doing so requires Linux admin knowledge. The Klipper installation -scripts ultimately cause the following Unix command to be run: -~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer.cfg -l /tmp/klippy.log - - -One can run multiple instances of the above command as long as each -instance has its own printer config file, its own log file, and its -own pseudo-tty. For example: -~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer2.cfg -l /tmp/klippy2.log -I /tmp/printer2 - - -If you choose to do this, you will need to implement the necessary -start, stop, and installation scripts (if any). The -install-octopi.sh script and the -klipper-start.sh script may be useful -as examples. -Do I have to use OctoPrint?¶ -The Klipper software is not dependent on OctoPrint. It is possible to -use alternative software to send commands to Klipper, but doing so -requires Linux admin knowledge. -Klipper creates a "virtual serial port" via the "/tmp/printer" file, -and it emulates a classic 3d-printer serial interface via that file. -In general, alternative software may work with Klipper as long as it -can be configured to use "/tmp/printer" for the printer serial port. -Why can't I move the stepper before homing the printer?¶ -The code does this to reduce the chance of accidentally commanding the -head into the bed or a wall. Once the printer is homed the software -attempts to verify each move is within the position_min/max defined in -the config file. If the motors are disabled (via an M84 or M18 -command) then the motors will need to be homed again prior to -movement. -If you want to move the head after canceling a print via OctoPrint, -consider changing the OctoPrint cancel sequence to do that for -you. It's configured in OctoPrint via a web browser under: -Settings->GCODE Scripts -If you want to move the head after a print finishes, consider adding -the desired movement to the "custom g-code" section of your slicer. -If the printer requires some additional movement as part of the homing -process itself (or fundamentally does not have a homing process) then -consider using a safe_z_home or homing_override section in the config -file. If you need to move a stepper for diagnostic or debugging -purposes then consider adding a force_move section to the config -file. See config reference -for further details on these options. -Why is the Z position_endstop set to 0.5 in the default configs?¶ -For cartesian style printers the Z position_endstop specifies how far -the nozzle is from the bed when the endstop triggers. If possible, it -is recommended to use a Z-max endstop and home away from the bed (as -this reduces the potential for bed collisions). However, if one must -home towards the bed then it is recommended to position the endstop so -it triggers when the nozzle is still a small distance away from the -bed. This way, when homing the axis, it will stop before the nozzle -touches the bed. See the bed level document for more -information. -I converted my config from Marlin and the X/Y axes work fine, but I just get a screeching noise when homing the Z axis¶ -Short answer: First, make sure you have verified the stepper -configuration as described in the -config check document. If the problem persists, -try reducing the max_z_velocity setting in the printer config. -Long answer: In practice Marlin can typically only step at a rate of -around 10000 steps per second. If it is requested to move at a speed -that would require a higher step rate then Marlin will generally just -step as fast as it can. Klipper is able to achieve much higher step -rates, but the stepper motor may not have sufficient torque to move at -a higher speed. So, for a Z axis with a high gearing ratio or high -microsteps setting the actual obtainable max_z_velocity may be smaller -than what is configured in Marlin. -My TMC motor driver turns off in the middle of a print¶ -If using the TMC2208 (or TMC2224) driver in "standalone mode" then -make sure to use the -latest version of Klipper. A -workaround for a TMC2208 "stealthchop" driver problem was added to -Klipper in mid-March of 2020. -I keep getting random "Lost communication with MCU" errors¶ -This is commonly caused by hardware errors on the USB connection -between the host machine and the micro-controller. Things to look for: - -Use a good quality USB cable between the host machine and - micro-controller. Make sure the plugs are secure. -If using a Raspberry Pi, use a - good quality power supply - for the Raspberry Pi and use a - good quality USB cable - to connect that power supply to the Pi. If you get "under voltage" - warnings from OctoPrint, this is related to the power supply and it - must be fixed. -Make sure the printer's power supply is not being overloaded. (Power - fluctuations to the micro-controller's USB chip may result in resets - of that chip.) -Verify stepper, heater, and other printer wires are not crimped or - frayed. (Printer movement may place stress on a faulty wire causing - it to lose contact, briefly short, or generate excessive noise.) -There have been reports of high USB noise when both the printer's - power supply and the host's 5V power supply are mixed. (If you find - that the micro-controller powers on when either the printer's power - supply is on or the USB cable is plugged in, then it indicates the - 5V power supplies are being mixed.) It may help to configure the - micro-controller to use power from only one source. (Alternatively, - if the micro-controller board can not configure its power source, - one may modify a USB cable so that it does not carry 5V power - between the host and micro-controller.) - -My Raspberry Pi keeps rebooting during prints¶ -This is most likely do to voltage fluctuations. Follow the same -troubleshooting steps for a -"Lost communication with MCU" -error. -When I set restart_method=command my AVR device just hangs on a restart¶ -Some old versions of the AVR bootloader have a known bug in watchdog -event handling. This typically manifests when the printer.cfg file has -restart_method set to "command". When the bug occurs, the AVR device -will be unresponsive until power is removed and reapplied to the -device (the power or status LEDs may also blink repeatedly until the -power is removed). -The workaround is to use a restart_method other than "command" or to -flash an updated bootloader to the AVR device. Flashing a new -bootloader is a one time step that typically requires an external -programmer - see Bootloaders for further details. -Will the heaters be left on if the Raspberry Pi crashes?¶ -The software has been designed to prevent that. Once the host enables -a heater, the host software needs to confirm that enablement every 5 -seconds. If the micro-controller does not receive a confirmation every -5 seconds it goes into a "shutdown" state which is designed to turn -off all heaters and stepper motors. -See the "config_digital_out" command in the -MCU commands document for further details. -In addition, the micro-controller software is configured with a -minimum and maximum temperature range for each heater at startup (see -the min_temp and max_temp parameters in the -config reference for details). If the -micro-controller detects that the temperature is outside of that range -then it will also enter a "shutdown" state. -Separately, the host software also implements code to check that -heaters and temperature sensors are functioning correctly. See the -config reference for further -details. -How do I convert a Marlin pin number to a Klipper pin name?¶ -Short answer: A mapping is available in the -sample-aliases.cfg file. Use that file -as a guide to finding the actual micro-controller pin names. (It is -also possible to copy the relevant -board_pins config section into your -config file and use the aliases in your config, but it is preferable -to translate and use the actual micro-controller pin names.) Note that -the sample-aliases.cfg file uses pin names that start with the prefix -"ar" instead of "D" (eg, Arduino pin D23 is Klipper alias ar23) -and the prefix "analog" instead of "A" (eg, Arduino pin A14 is -Klipper alias analog14). -Long answer: Klipper uses the standard pin names defined by the -micro-controller. On the Atmega chips these hardware pins have names -like PA4, PC7, or PD2. -Long ago, the Arduino project decided to avoid using the standard -hardware names in favor of their own pin names based on incrementing -numbers - these Arduino names generally look like D23 or A14. This -was an unfortunate choice that has lead to a great deal of confusion. -In particular the Arduino pin numbers frequently don't translate to -the same hardware names. For example, D21 is PD0 on one common -Arduino board, but is PC7 on another common Arduino board. -To avoid this confusion, the core Klipper code uses the standard pin -names defined by the micro-controller. -Do I have to wire my device to a specific type of micro-controller pin?¶ -It depends on the type of device and type of pin: -ADC pins (or Analog pins): For thermistors and similar "analog" -sensors, the device must be wired to an "analog" or "ADC" capable pin -on the micro-controller. If you configure Klipper to use a pin that is -not analog capable, Klipper will report a "Not a valid ADC pin" error. -PWM pins (or Timer pins): Klipper does not use hardware PWM by default -for any device. So, in general, one may wire heaters, fans, and -similar devices to any general purpose IO pin. However, fans and -output_pin devices may be optionally configured to use hardware_pwm: -True, in which case the micro-controller must support hardware PWM on -the pin (otherwise, Klipper will report a "Not a valid PWM pin" -error). -IRQ pins (or Interrupt pins): Klipper does not use hardware interrupts -on IO pins, so it is never necessary to wire a device to one of these -micro-controller pins. -SPI pins: When using hardware SPI it is necessary to wire the pins to -the micro-controller's SPI capable pins. However, most devices can be -configured to use "software SPI", in which case any general purpose IO -pins may be used. -I2C pins: When using I2C it is necessary to wire the pins to the -micro-controller's I2C capable pins. -Other devices may be wired to any general purpose IO pin. For example, -steppers, heaters, fans, Z probes, servos, LEDs, common hd44780/st7920 -LCD displays, the Trinamic UART control line may be wired to any -general purpose IO pin. -How do I cancel an M109/M190 "wait for temperature" request?¶ -Navigate to the OctoPrint terminal tab and issue an M112 command in -the terminal box. The M112 command will cause Klipper to enter into a -"shutdown" state, and it will cause OctoPrint to disconnect from -Klipper. Navigate to the OctoPrint connection area and click on -"Connect" to cause OctoPrint to reconnect. Navigate back to the -terminal tab and issue a FIRMWARE_RESTART command to clear the Klipper -error state. After completing this sequence, the previous heating -request will be canceled and a new print may be started. -Can I find out whether the printer has lost steps?¶ -In a way, yes. Home the printer, issue a GET_POSITION command, run -your print, home again and issue another GET_POSITION. Then compare -the values in the mcu: line. -This might be helpful to tune settings like stepper motor currents, -accelerations and speeds without needing to actually print something -and waste filament: just run some high-speed moves in between the -GET_POSITION commands. -Note that endstop switches themselves tend to trigger at slightly -different positions, so a difference of a couple of microsteps is -likely the result of endstop inaccuracies. A stepper motor itself can -only lose steps in increments of 4 full steps. (So, if one is using 16 -microsteps, then a lost step on the stepper would result in the "mcu:" -step counter being off by a multiple of 64 microsteps.) -Why does Klipper report errors? I lost my print!¶ -Short answer: We want to know if our printers detect a problem so that -the underlying issue can be fixed and we can obtain great quality -prints. We definitely do not want our printers to silently produce low -quality prints. -Long answer: Klipper has been engineered to automatically workaround -many transient problems. For example, it automatically detects -communication errors and will retransmit; it schedules actions in -advance and buffers commands at multiple layers to enable precise -timing even with intermittent interference. However, should the -software detect an error that it can not recover from, if it is -commanded to take an invalid action, or if it detects it is hopelessly -unable to perform its commanded task, then Klipper will report an -error. In these situations there is a high risk of producing a -low-quality print (or worse). It is hoped that alerting the user will -empower them to fix the underlying issue and improve the overall -quality of their prints. -There are some related questions: Why doesn't Klipper pause the print -instead? Report a warning instead? Check for errors before the print? -Ignore errors in user typed commands? etc? Currently Klipper reads -commands using the G-Code protocol, and unfortunately the G-Code -command protocol is not flexible enough to make these alternatives -practical today. There is developer interest in improving the user -experience during abnormal events, but it is expected that will -require notable infrastructure work (including a shift away from -G-Code). -How do I upgrade to the latest software?¶ -The first step to upgrading the software is to review the latest -config changes document. On occasion, changes are -made to the software that require users to update their settings as -part of a software upgrade. It is a good idea to review this document -prior to upgrading. -When ready to upgrade, the general method is to ssh into the Raspberry -Pi and run: -cd ~/klipper -git pull -~/klipper/scripts/install-octopi.sh - - -Then one can recompile and flash the micro-controller code. For -example: -make menuconfig -make clean -make - -sudo service klipper stop -make flash FLASH_DEVICE=/dev/ttyACM0 -sudo service klipper start - - -However, it's often the case that only the host software changes. In -this case, one can update and restart just the host software with: -cd ~/klipper -git pull -sudo service klipper restart - - -If after using this shortcut the software warns about needing to -reflash the micro-controller or some other unusual error occurs, then -follow the full upgrade steps outlined above. -If any errors persist then double check the -config changes document, as you may need to -modify the printer configuration. -Note that the RESTART and FIRMWARE_RESTART g-code commands do not load -new software - the above "sudo service klipper restart" and "make -flash" commands are needed for a software change to take effect. -How do I uninstall Klipper?¶ -On the firmware end, nothing special needs to happen. Just follow the -flashing directions for the new firmware. -On the raspberry pi end, an uninstall script is available in -scripts/klipper-uninstall.sh. For -example: -sudo ~/klipper/scripts/klipper-uninstall.sh -rm -rf ~/klippy-env ~/klipper - - - -
- - - - - - - -TMC drivers¶ -This document provides information on using Trinamic stepper motor -drivers in SPI/UART mode on Klipper. -Klipper can also use Trinamic drivers in their "standalone mode". -However, when the drivers are in this mode, no special Klipper -configuration is needed and the advanced Klipper features discussed in -this document are not available. -In addition to this document, be sure to review the -TMC driver config reference. -Tuning motor current¶ -A higher driver current increases positional accuracy and torque. -However, a higher current also increases the heat produced by the -stepper motor and the stepper motor driver. If the stepper motor -driver gets too hot it will disable itself and Klipper will report an -error. If the stepper motor gets too hot, it loses torque and -positional accuracy. (If it gets very hot it may also melt plastic -parts attached to it or near it.) -As a general tuning tip, prefer higher current values as long as the -stepper motor does not get too hot and the stepper motor driver does -not report warnings or errors. In general, it is okay for the stepper -motor to feel warm, but it should not become so hot that it is painful -to touch. -Prefer to not specify a hold_current¶ -If one configures a hold_current then the TMC driver can reduce -current to the stepper motor when it detects that the stepper is not -moving. However, changing motor current may itself introduce motor -movement. This may occur due to "detent forces" within the stepper -motor (the permanent magnet in the rotor pulls towards the iron teeth -in the stator) or due to external forces on the axis carriage. -Most stepper motors will not obtain a significant benefit to reducing -current during normal prints, because few printing moves will leave a -stepper motor idle for sufficiently long to activate the -hold_current feature. And, it is unlikely that one would want to -introduce subtle print artifacts to the few printing moves that do -leave a stepper idle sufficiently long. -If one wishes to reduce current to motors during print start routines, -then consider issuing -SET_TMC_CURRENT commands in a -START_PRINT macro to adjust the -current before and after normal printing moves. -Some printers with dedicated Z motors that are idle during normal -printing moves (no bed_mesh, no bed_tilt, no Z skew_correction, no -"vase mode" prints, etc.) may find that Z motors do run cooler with a -hold_current. If implementing this then be sure to take into account -this type of uncommanded Z axis movement during bed leveling, bed -probing, probe calibration, and similar. The driver_TPOWERDOWN and -driver_IHOLDDELAY should also be calibrated accordingly. If unsure, -prefer to not specify a hold_current. -Setting "spreadCycle" vs "stealthChop" Mode¶ -By default, Klipper places the TMC drivers in "spreadCycle" mode. If -the driver supports "stealthChop" then it can be enabled by adding -stealthchop_threshold: 999999 to the TMC config section. -In general, spreadCycle mode provides greater torque and greater -positional accuracy than stealthChop mode. However, stealthChop mode -may produce significantly lower audible noise on some printers. -Tests comparing modes have shown an increased "positional lag" of -around 75% of a full-step during constant velocity moves when using -stealthChop mode (for example, on a printer with 40mm -rotation_distance and 200 steps_per_rotation, position deviation of -constant speed moves increased by ~0.150mm). However, this "delay in -obtaining the requested position" may not manifest as a significant -print defect and one may prefer the quieter behavior of stealthChop -mode. -It is recommended to always use "spreadCycle" mode (by not specifying -stealthchop_threshold) or to always use "stealthChop" mode (by -setting stealthchop_threshold to 999999). Unfortunately, the drivers -often produce poor and confusing results if the mode changes while the -motor is at a non-zero velocity. -TMC interpolate setting introduces small position deviation¶ -The TMC driver interpolate setting may reduce the audible noise of -printer movement at the cost of introducing a small systemic -positional error. This systemic positional error results from the -driver's delay in executing "steps" that Klipper sends it. During -constant velocity moves, this delay results in a positional error of -nearly half a configured microstep (more precisely, the error is half -a microstep distance minus a 512th of a full step distance). For -example, on an axis with a 40mm rotation_distance, 200 -steps_per_rotation, and 16 microsteps, the systemic error introduced -during constant velocity moves is ~0.006mm. -For best positional accuracy consider using spreadCycle mode and -disable interpolation (set interpolate: False in the TMC driver -config). When configured this way, one may increase the microstep -setting to reduce audible noise during stepper movement. Typically, a -microstep setting of 64 or 128 will have similar audible noise as -interpolation, and do so without introducing a systemic positional -error. -If using stealthChop mode then the positional inaccuracy from -interpolation is small relative to the positional inaccuracy -introduced from stealthChop mode. Therefore tuning interpolation is -not considered useful when in stealthChop mode, and one can leave -interpolation in its default state. -Sensorless Homing¶ -Sensorless homing allows to home an axis without the need for a -physical limit switch. Instead, the carriage on the axis is moved into -the mechanical limit making the stepper motor lose steps. The stepper -driver senses the lost steps and indicates this to the controlling MCU -(Klipper) by toggling a pin. This information can be used by Klipper -as end stop for the axis. -This guide covers the setup of sensorless homing for the X axis of -your (cartesian) printer. However, it works the same with all other -axes (that require an end stop). You should configure and tune it for -one axis at a time. -Limitations¶ -Be sure that your mechanical components are able to handle the load of -the carriage bumping into the limit of the axis repeatedly. Especially -leadscrews might generate a lot of force. Homing a Z axis by bumping -the nozzle into the printing surface might not be a good idea. For -best results, verify that the axis carriage will make a firm contact -with the axis limit. -Further, sensorless homing might not be accurate enough for your -printer. While homing X and Y axes on a cartesian machine can work -well, homing the Z axis is generally not accurate enough and may -result in an inconsistent first layer height. Homing a delta printer -sensorless is not advisable due to missing accuracy. -Further, the stall detection of the stepper driver is dependent on the -mechanical load on the motor, the motor current and the motor -temperature (coil resistance). -Sensorless homing works best at medium motor speeds. For very slow -speeds (less than 10 RPM) the motor does not generate significant back -EMF and the TMC cannot reliably detect motor stalls. Further, at very -high speeds, the back EMF of the motor approaches the supply voltage -of the motor, so the TMC cannot detect stalls anymore. It is advised -to have a look in the datasheet of your specific TMCs. There you can -also find more details on limitations of this setup. -Prerequisites¶ -A few prerequisites are needed to use sensorless homing: - -A stallGuard capable TMC stepper driver (tmc2130, tmc2209, tmc2660, - or tmc5160). -SPI / UART interface of the TMC driver wired to micro-controller - (stand-alone mode does not work). -The appropriate "DIAG" or "SG_TST" pin of TMC driver connected to - the micro-controller. -The steps in the config checks document must be - run to confirm the stepper motors are configured and working - properly. - -Tuning¶ -The procedure described here has six major steps: - -Choose a homing speed. -Configure the printer.cfg file to enable sensorless homing. -Find the stallguard setting with highest sensitivity that - successfully homes. -Find the stallguard setting with lowest sensitivity that - successfully homes with a single touch. -Update the printer.cfg with the desired stallguard setting. -Create or update printer.cfg macros to home consistently. - -Choose homing speed¶ -The homing speed is an important choice when performing sensorless -homing. It's desirable to use a slow homing speed so that the carriage -does not exert excessive force on the frame when making contact with -the end of the rail. However, the TMC drivers can't reliably detect a -stall at very slow speeds. -A good starting point for the homing speed is for the stepper motor to -make a full rotation every two seconds. For many axes this will be the -rotation_distance divided by two. For example: -[stepper_x] -rotation_distance: 40 -homing_speed: 20 -... - - -Configure printer.cfg for sensorless homing¶ -The homing_retract_dist setting must be set to zero in the -stepper_x config section to disable the second homing move. The -second homing attempt does not add value when using sensorless homing, -it will not work reliably, and it will confuse the tuning process. -Be sure that a hold_current setting is not specified in the TMC -driver section of the config. (If a hold_current is set then after -contact is made, the motor stops while the carriage is pressed against -the end of the rail, and reducing the current while in that position -may cause the carriage to move - that results in poor performance and -will confuse the tuning process.) -It is necessary to configure the sensorless homing pins and to -configure initial "stallguard" settings. A tmc2209 example -configuration for an X axis might look like: -[tmc2209 stepper_x] -diag_pin: ^PA1 # Set to MCU pin connected to TMC DIAG pin -driver_SGTHRS: 255 # 255 is most sensitive value, 0 is least sensitive -... - -[stepper_x] -endstop_pin: tmc2209_stepper_x:virtual_endstop -homing_retract_dist: 0 -... - - -An example tmc2130 or tmc5160 config might look like: -[tmc2130 stepper_x] -diag1_pin: ^!PA1 # Pin connected to TMC DIAG1 pin (or use diag0_pin / DIAG0 pin) -driver_SGT: -64 # -64 is most sensitive value, 63 is least sensitive -... - -[stepper_x] -endstop_pin: tmc2130_stepper_x:virtual_endstop -homing_retract_dist: 0 -... - - -An example tmc2660 config might look like: -[tmc2660 stepper_x] -driver_SGT: -64 # -64 is most sensitive value, 63 is least sensitive -... - -[stepper_x] -endstop_pin: ^PA1 # Pin connected to TMC SG_TST pin -homing_retract_dist: 0 -... - - -The examples above only show settings specific to sensorless -homing. See the -config reference -for all the available options. -Find highest sensitivity that successfully homes¶ -Place the carriage near the center of the rail. Use the SET_TMC_FIELD -command to set the highest sensitivity. For tmc2209: -SET_TMC_FIELD STEPPER=stepper_x FIELD=SGTHRS VALUE=255 - - -For tmc2130, tmc5160, and tmc2660: -SET_TMC_FIELD STEPPER=stepper_x FIELD=sgt VALUE=-64 - - -Then issue a G28 X0 command and verify the axis does not move at -all. If the axis does move, then issue an M112 to halt the printer - -something is not correct with the diag/sg_tst pin wiring or -configuration and it must be corrected before continuing. -Next, continually decrease the sensitivity of the VALUE setting and -run the SET_TMC_FIELD G28 X0 commands again to find the highest -sensitivity that results in the carriage successfully moving all the -way to the endstop and halting. (For tmc2209 drivers this will be -decreasing SGTHRS, for other drivers it will be increasing sgt.) Be -sure to start each attempt with the carriage near the center of the -rail (if needed issue M84 and then manually move the carriage to the -center). It should be possible to find the highest sensitivity that -homes reliably (settings with higher sensitivity result in small or no -movement). Note the found value as maximum_sensitivity. (If the -minimum possible sensitivity (SGTHRS=0 or sgt=63) is obtained without -any carriage movement then something is not correct with the -diag/sg_tst pin wiring or configuration and it must be corrected -before continuing.) -When searching for maximum_sensitivity, it may be convenient to jump -to different VALUE settings (so as to bisect the VALUE parameter). If -doing this then be prepared to issue an M112 command to halt the -printer, as a setting with a very low sensitivity may cause the axis -to repeatedly "bang" into the end of the rail. -Be sure to wait a couple of seconds between each homing attempt. After -the TMC driver detects a stall it may take a little time for it to -clear its internal indicator and be capable of detecting another -stall. -During these tuning tests, if a G28 X0 command does not move all the -way to the axis limit, then be careful with issuing any regular -movement commands (eg, G1). Klipper will not have a correct -understanding of the carriage position and a move command may cause -undesirable and confusing results. -Find lowest sensitivity that homes with one touch¶ -When homing with the found maximum_sensitivity value, the axis -should move to the end of the rail and stop with a "single touch" - -that is, there should not be a "clicking" or "banging" sound. (If -there is a banging or clicking sound at maximum_sensitivity then the -homing_speed may be too low, the driver current may be too low, or -sensorless homing may not be a good choice for the axis.) -The next step is to again continually move the carriage to a position -near the center of the rail, decrease the sensitivity, and run the -SET_TMC_FIELD G28 X0 commands - the goal is now to find the lowest -sensitivity that still results in the carriage successfully homing -with a "single touch". That is, it does not "bang" or "click" when -contacting the end of the rail. Note the found value as -minimum_sensitivity. -Update printer.cfg with sensitivity value¶ -After finding maximum_sensitivity and minimum_sensitivity, use a -calculator to obtain the recommend sensitivity as -minimum_sensitivity + (maximum_sensitivity - minimum_sensitivity)/3. -The recommended sensitivity should be in the range between the minimum -and maximum, but slightly closer to the minimum. Round the final value -to the nearest integer value. -For tmc2209 set this in the config as driver_SGTHRS, for other TMC -drivers set this in the config as driver_SGT. -If the range between maximum_sensitivity and minimum_sensitivity -is small (eg, less than 5) then it may result in unstable homing. A -faster homing speed may increase the range and make the operation more -stable. -Note that if any change is made to driver current, homing speed, or a -notable change is made to the printer hardware, then it will be -necessary to run the tuning process again. -Using Macros when Homing¶ -After sensorless homing completes the carriage will be pressed against -the end of the rail and the stepper will exert a force on the frame -until the carriage is moved away. It is a good idea to create a macro -to home the axis and immediately move the carriage away from the end -of the rail. -It is a good idea for the macro to pause at least 2 seconds prior to -starting sensorless homing (or otherwise ensure that there has been no -movement on the stepper for 2 seconds). Without a delay it is possible -for the driver's internal stall flag to still be set from a previous -move. -It can also be useful to have that macro set the driver current before -homing and set a new current after the carriage has moved away. -An example macro might look something like: -[gcode_macro SENSORLESS_HOME_X] -gcode: - {% set HOME_CUR = 0.700 %} - {% set driver_config = printer.configfile.settings['tmc2209 stepper_x'] %} - {% set RUN_CUR = driver_config.run_current %} - # Set current for sensorless homing - SET_TMC_CURRENT STEPPER=stepper_x CURRENT={HOME_CUR} - # Pause to ensure driver stall flag is clear - G4 P2000 - # Home - G28 X0 - # Move away - G90 - G1 X5 F1200 - # Set current during print - SET_TMC_CURRENT STEPPER=stepper_x CURRENT={RUN_CUR} - - -The resulting macro can be called from a -homing_override config section -or from a START_PRINT macro. -Note that if the driver current during homing is changed, then the -tuning process should be run again. -Tips for sensorless homing on CoreXY¶ -It is possible to use sensorless homing on the X and Y carriages of a -CoreXY printer. Klipper uses the [stepper_x] stepper to detect -stalls when homing the X carriage and uses the [stepper_y] stepper -to detect stalls when homing the Y carriage. -Use the tuning guide described above to find the appropriate "stall -sensitivity" for each carriage, but be aware of the following -restrictions: - -When using sensorless homing on CoreXY, make sure there is no - hold_current configured for either stepper. -While tuning, make sure both the X and Y carriages are near the - center of their rails before each home attempt. -After tuning is complete, when homing both X and Y, use macros to - ensure that one axis is homed first, then move that carriage away - from the axis limit, pause for at least 2 seconds, and then start - the homing of the other carriage. The move away from the axis - avoids homing one axis while the other is pressed against the axis - limit (which may skew the stall detection). The pause is necessary - to ensure the driver's stall flag is cleared prior to homing again. - -Querying and diagnosing driver settings¶ -The `DUMP_TMC command is a useful tool when -configuring and diagnosing the drivers. It will report all fields -configured by Klipper as well as all fields that can be queried from -the driver. -All of the reported fields are defined in the Trinamic datasheet for -each driver. These datasheets can be found on the -Trinamic website. Obtain and review the -Trinamic datasheet for the driver to interpret the results of -DUMP_TMC. -Configuring driver_XXX settings¶ -Klipper supports configuring many low-level driver fields using -driver_XXX settings. The -TMC driver config reference -has the full list of fields available for each type of driver. -In addition, almost all fields can be modified at run-time using the -SET_TMC_FIELD command. -Each of these fields is defined in the Trinamic datasheet for each -driver. These datasheets can be found on the -Trinamic website. -Note that the Trinamic datasheets sometime use wording that can -confuse a high-level setting (such as "hysteresis end") with a -low-level field value (eg, "HEND"). In Klipper, driver_XXX and -SET_TMC_FIELD always set the low-level field value that is actually -written to the driver. So, for example, if the Trinamic datasheet -states that a value of 3 must be written to the HEND field to obtain a -"hysteresis end" of 0, then set driver_HEND=3 to obtain the -high-level value of 0. -Common Questions¶ -Can I use stealthChop mode on an extruder with pressure advance?¶ -Many people successfully use "stealthChop" mode with Klipper's -pressure advance. Klipper implements -smooth pressure advance which does -not introduce any instantaneous velocity changes. -However, "stealthChop" mode may produce lower motor torque and/or -produce higher motor heat. It may or may not be an adequate mode for -your particular printer. -I keep getting "Unable to read tmc uart 'stepper_x' register IFCNT" errors?¶ -This occurs when Klipper is unable to communicate with a tmc2208 or -tmc2209 driver. -Make sure that the motor power is enabled, as the stepper motor driver -generally needs motor power before it can communicate with the -micro-controller. -If this error occurs after flashing Klipper for the first time, then -the stepper driver may have been previously programmed in a state that -is not compatible with Klipper. To reset the state, remove all power -from the printer for several seconds (physically unplug both USB and -power plugs). -Otherwise, this error is typically the result of incorrect UART pin -wiring or an incorrect Klipper configuration of the UART pin settings. -I keep getting "Unable to write tmc spi 'stepper_x' register ..." errors?¶ -This occurs when Klipper is unable to communicate with a tmc2130 or -tmc5160 driver. -Make sure that the motor power is enabled, as the stepper motor driver -generally needs motor power before it can communicate with the -micro-controller. -Otherwise, this error is typically the result of incorrect SPI wiring, -an incorrect Klipper configuration of the SPI settings, or an -incomplete configuration of devices on an SPI bus. -Note that if the driver is on a shared SPI bus with multiple devices -then be sure to fully configure every device on that shared SPI bus in -Klipper. If a device on a shared SPI bus is not configured, then it -may incorrectly respond to commands not intended for it and corrupt -the communication to the intended device. If there is a device on a -shared SPI bus that can not be configured in Klipper, then use a -static_digital_output config section -to set the CS pin of the unused device high (so that it will not -attempt to use the SPI bus). The board's schematic is often a useful -reference for finding which devices are on an SPI bus and their -associated pins. -Why did I get a "TMC reports error: ..." error?¶ -This type of error indicates the TMC driver detected a problem and has -disabled itself. That is, the driver stopped holding its position and -ignored movement commands. If Klipper detects that an active driver -has disabled itself, it will transition the printer into a "shutdown" -state. -It's also possible that a TMC reports error shutdown occurs due to -SPI errors that prevent communication with the driver (on tmc2130, -tmc5160, or tmc2660). If this occurs, it's common for the reported -driver status to show 00000000 or ffffffff - for example: TMC -reports error: DRV_STATUS: ffffffff ... OR TMC reports error: -READRSP@RDSEL2: 00000000 .... Such a failure may be due to an SPI -wiring problem or may be due to a self-reset or failure of the TMC -driver. -Some common errors and tips for diagnosing them: -TMC reports error: ... ot=1(OvertempError!)¶ -This indicates the motor driver disabled itself because it became too -hot. Typical solutions are to decrease the stepper motor current, -increase cooling on the stepper motor driver, and/or increase cooling -on the stepper motor. -TMC reports error: ... ShortToGND OR LowSideShort¶ -This indicates the driver has disabled itself because it detected very -high current passing through the driver. This may indicate a loose or -shorted wire to the stepper motor or within the stepper motor itself. -This error may also occur if using stealthChop mode and the TMC driver -is not able to accurately predict the mechanical load of the motor. -(If the driver makes a poor prediction then it may send too much -current through the motor and trigger its own over-current detection.) -To test this, disable stealthChop mode and check if the errors -continue to occur. -TMC reports error: ... reset=1(Reset) OR CS_ACTUAL=0(Reset?) OR SE=0(Reset?)¶ -This indicates that the driver has reset itself mid-print. This may be -due to voltage or wiring issues. -TMC reports error: ... uv_cp=1(Undervoltage!)¶ -This indicates the driver has detected a low-voltage event and has -disabled itself. This may be due to wiring or power supply issues. -How do I tune spreadCycle/coolStep/etc. mode on my drivers?¶ -The Trinamic website has guides on -configuring the drivers. These guides are often technical, low-level, -and may require specialized hardware. Regardless, they are the best -source of information. - - -
+ + + + + + + +API 伺服器¶ +該文件介紹Klipper的應用開發者介面（API）功能。該介面允許外部應用程式訪問和控制Klipper主機。 +啟用API套接字¶ +要啟用API伺服器，klipper.py執行時應加上 -a 參數。例如： +~/klippy-env/bin/python ~/klipper/klippy/klippy.py ~/printer.cfg -a /tmp/klippy_uds -l /tmp/klippy.log + + +上述操作會使主機建立一個Unix本地套接字。之後，客戶應用程式可以建立一個套接字鏈接，從而給Klipper發送命令。 +請求格式¶ +套接字進出的數據包應使用JSON編碼的字串，並以ASCII字元0x03作為結尾： +<json_object_1><0x03><json_object_2><0x03>... + + +Klipper使用scripts/whconsole.py的程式碼進行上述的數據幀打包。例如： +~/klipper/scripts/whconsole.py /tmp/klippy_uds + + +該工具會從stdin中讀取一系列的JSON命令，發送到Klipper執行，並將結果送出。該工具預設輸入的每條Json命令中不存在換行，並自動地在發送命令時在結尾附上0x03。（Klipper API伺服器沒有換行符要求。） +API協議¶ +套接字的命令協議受 json-rpc 啓發。 +一個請求命令類似： +{"id": 123, "method": "info", "params": {}} +及一個反應將類似： +{"id": 123, "result": {"state_message": "Printer is ready", "klipper_path": "/home/pi/klipper", "config_file": "/home/pi/printer.cfg", "software_version": "v0.8.0-823-g883b1cb6", "hostname": "octopi", "cpu_info": "4 core ARMv7 Processor rev 4 (v7l)", "state": "ready", "python_path": "/home/pi/klippy-env/bin/python", "log_file": "/tmp/klippy.log"}} +每個請求應為一個JSON字典。（本文件使用Python中的術語「字典」描述以{}為邊界的「鍵-值」JSON對象。） +請求字典中必須包含一個」method」欄位，其值應包含一個可用的Klipper端點」endpoint」名稱字串。 +請求字典可能包含」params」參數，並其值應為一個字典型別。」params」提供Klipper」endpoint」處理請求所需的額外數據，其內容依」endpoint」而定。 +請求字典可能包含一個“id”參數，它可以是任何 JSON 類型。如果存在“id”，那麼 Klipper 將使用包含該“id”的響應消息來響應請求。如果省略“id”（或設置為 JSON“null”值），則 Klipper 不會對請求提供任何響應。響應消息是包含“id”和“result”的 JSON 字典。 “結果”始終是一個字典 - 它的內容特定於處理請求的“端點”。 +如果處理的請求造成了錯誤，則響應訊息將包含"error"欄位，而不是"result"欄位。例如，請求： {"id"： 123， "method"： "gcode/script"， "params"： {"script"： "G1 X200"}} 可能會返回錯誤響應，例如： {"id"： 123， "error"： {"message"： "Must home axis first： 200.000 0.000 0.000 [0.000]"， "error"： "WebRequestError"}} +Klipper 會按照收到請求的順序依次處理請求。然而，一些請求可能不會立即完成，這可能會導致相關的響應與其他請求的響應不按順序發送。一個 JSON 請求永遠不會暫停對未來JSON 請求的處理。 +訂閱¶ +一些 Klipper 的"endpoint"可以以 "訂閱" 的形式接收未來的非同步更新訊息。 +例如： +{"id": 123, "method": "gcode/subscribe_output", "params": {"response_template":{"key": 345}}} +可能會返回一個初始迴應： +{"id": 123, "result": {}} +並導致 Klipper 在未來發送類似於以下內容的訊息： +{"params": {"response": "ok B:22.8 /0.0 T0:22.4 /0.0"}, "key": 345} +訂閱請求接受請求的“params”字段中的“response_template”字典。該“response_template”字典用作未來異步消息的模板 - 它可能包含任意鍵/值對。當發送這些未來的異步消息時，Klipper 將在響應模板中添加一個包含具有“端點”特定內容的字典的“參數”字段，然後發送該模板。如果未提供“response_template”字段，則默認為空字典（{}）。 +可用的“端點”¶ +按照慣例，Klipper “端點”的格式為 <module_name>/<some_name>。向“端點”發出請求時，必須在請求字典的“方法”參數中設置全名（例如，{"method"="gcode/restart"}）。 +信息¶ +“info”端點用於從 Klipper 獲取系統和版本信息。它還用於向 Klipper 提供客戶端的版本信息。例如：{"id": 123, "method": "info", "params": { "client_info": { "version": "v1"}}} +如果存在，“client_info”參數必須是字典，但該字典可能具有任意內容。鼓勵客戶端在首次連接到 Klipper API 服務器時提供客戶端名稱及其軟件版本。 +emergency_stop¶ +“emergency_stop”端點用於指示 Klipper 轉換到“關閉”狀態。它的行為類似於 G-Code M112 命令。例如：{"id": 123, "method": "emergency_stop"} +register_remote_method¶ +此端點允許客戶端註冊可以從 klipper 調用的方法。成功後將返回一個空對象。 +例如：{"id": 123, "method": "register_remote_method", "params": {"response_template": {"action": "run_paneldue_beep"}, "remote_method": "paneldue_beep"}} 將返回：{“id”：123，“結果”：{}} +現在可以從 Klipper 調用遠程方法 paneldue_beep。請注意，如果該方法採用參數，則應將它們作為關鍵字參數提供。下面是如何從 gcode_macro 調用它的示例： +[gcode_macro PANELDUE_BEEP] +gcode: + {action_call_remote_method("paneldue_beep", frequency=300, duration=1.0)} + + +當執行 PANELDUE_BEEP gcode 宏時，Klipper 將通過套接字發送類似以下內容：{"action": "run_paneldue_beep", "params": {"frequency": 300, "duration": 1.0}} +objects/list¶ +該端點查詢可以查詢的可用打印機“對象”列表（通過“對象/查詢”端點）。例如：{"id": 123, "method": "objects/list"} 可能會返回：{"id": 123, "result": {"objects": ["webhooks", "configfile" , “加熱器”, “gcode_move”, “query_endstops”, “idle_timeout”, “toolhead”, “extruder”]}} +objects/query¶ +該端點允許從打印機對像中查詢信息。例如：{"id": 123, "method": "objects/query", "params": {"objects": {"toolhead": ["position"], "webhooks": null}}}可能返回：{"id": 123, "result": {"status": {"webhooks": {"state": "ready", "state_message": "Printer is ready"}, "toolhead": { “位置”：[0.0, 0.0, 0.0, 0.0]}}，“事件時間”：3051555.377933684}} +請求中的“objects”參數必須是包含要查詢的打印機對象的字典 - 鍵包含打印機對象名稱，值為“null”（查詢所有字段）或字段名稱列表。 +響應消息將包含一個“狀態”字段，其中包含帶有查詢信息的字典 - 鍵包含打印機對象名稱，值是包含其字段的字典。響應消息還將包含一個“eventtime”字段，其中包含進行查詢時的時間戳。 +可用字段記錄在 Status Reference 文檔中。 +objects/subscribe¶ +該端點允許查詢然後訂閱來自打印機對象的信息。端點請求和響應與“對象/查詢”端點相同。例如：{"id": 123, "method": "objects/subscribe", "params": {"objects":{"toolhead": ["position"], "webhooks": ["state"] }, "response_template":{}}} 可能返回：{"id": 123, "result": {"status": {"webhooks": {"state": "ready"}, "toolhead": {"position": [0.0, 0.0, 0.0, 0.0]}}, "eventtime": 3052153.382083195}} 並導致後續異步消息，例如：{"params": {"status": {"webhooks": {“狀態”：“關機”}}，“事件時間”：3052165.418815847}} +gcode/help¶ +該端點允許查詢已定義幫助字符串的可用 G 代碼命令。例如：{"id": 123, "method": "gcode/help"} 可能會返回：{"id": 123, "result": {"RESTORE_GCODE_STATE": "恢復以前保存的 G-Code state", "PID_CALIBRATE": "運行 PID 校準測試", "QUERY_ADC": "報告模擬引腳的最後值", ...}} +gcode/script¶ +該端點允許運行一系列 G 代碼命令。例如：{"id": 123, "method": "gcode/script", "params": {"script": "G90"}} +如果提供的 G 代碼腳本引發錯誤，則會生成錯誤響應。但是，如果 G 代碼命令產生終端輸出，則該終端輸出不會在響應中提供。 （使用“gcode/subscribe_output”端點獲取 G-Code 終端輸出。） +如果收到此請求時正在處理 G-Code 命令，則提供的腳本將排隊。這種延遲可能很明顯（例如，如果 G 代碼等待溫度命令正在運行）。當腳本處理完全完成時發送 JSON 響應消息。 +gcode/restart¶ +該端點允許請求重新啟動 - 它類似於運行 G 代碼“RESTART”命令。例如：{"id": 123, "method": "gcode/restart"} +與“gcode/script”端點一樣，此端點僅在任何待處理的 G 代碼命令完成後才會完成。 +gcode/firmware_restart¶ +這類似於“gcode/restart”端點——它實現了 G-Code“FIRMWARE_RESTART”命令。例如：{"id": 123, "method": "gcode/firmware_restart"} +與“gcode/script”端點一樣，此端點僅在任何待處理的 G 代碼命令完成後才會完成。 +gcode/subscribe_output¶ +此端點用於訂閱由 Klipper 生成的 G-Code 終端消息。例如：{"id": 123, "method": "gcode/subscribe_output", "params": {"response_template":{}}} 可能稍後會產生異步消息，例如：{"params": { "response": "// Klipper 狀態：關機"}} +該端點旨在通過“終端窗口”界面支持人機交互。不鼓勵從 G 代碼終端輸出解析內容。使用“objects/subscribe”端點獲取 Klipper 狀態的更新。 +motion_report/dump_stepper¶ +此端點用於為步進器訂閱 Klipper 的內部步進器 queue_step 命令流。獲取這些低級運動更新可能對診斷和調試有用。使用此端點可能會增加 Klipper 的系統負載。 +一個請求可能看起來像：{"id": 123, "method":"motion_report/dump_stepper", "params": {"name": "stepper_x", "response_template": {}}} 並且可能返回： {"id": 123, "result": {"header": ["interval", "count", "add"]}} 之後可能會產生異步消息，例如：{"params": {" first_clock”：179601081，“first_time”：8.98，“first_position”：0，“last_clock”：219686097，“last_time”：10.984，“data”：[[179601081, 1, 0], [29573, 2, -8685] , [16230, 4, -1525], [10559, 6, -160], [10000, 976, 0], [10000, 1000, 0], [10000, 1000, 0], [10000, 1000, 0] , [9855, 5, 187], [11632, 4, 1534], [20756, 2, 9442]]}} +初始查詢響應中的“header”字段用於描述在以後的“data”響應中找到的字段。 +motion_report/dump_trapq¶ +該端點用於訂閱 Klipper 的內部“梯形運動隊列”。獲取這些低級運動更新可能對診斷和調試有用。使用此端點可能會增加 Klipper 的系統負載。 +一個請求可能看起來像：{"id": 123, "method": "motion_report/dump_trapq", "params": {"name": "toolhead", "response_template":{}}} 並且可能返回： {"id": 1, "result": {"header": ["time", "duration", "start_velocity", "acceleration", "start_position", "direction"]}} 並且以後可能會產生異步消息，例如：{"params": {"data": [[4.05, 1.0, 0.0, 0.0, [300.0, 0.0, 0.0], [0.0, 0.0, 0.0]], [5.054, 0.001, 0.0, 3000.0 , [300.0, 0.0, 0.0], [-1.0, 0.0, 0.0]]]}} +初始查詢響應中的“header”字段用於描述在以後的“data”響應中找到的字段。 +adxl345/dump_adxl345¶ +該端點用於訂閱 ADXL345 加速度計數據。獲取這些低級運動更新可能對診斷和調試有用。使用此端點可能會增加 Klipper 的系統負載。 +請求可能類似於：{"id": 123, "method":"adxl345/dump_adxl345", "params": {"sensor": "adxl345", "response_template": {}}} 並且可能返回： {"id": 123,"result":{"header":["time","x_acceleration","y_acceleration", "z_acceleration"]}} 並且可能稍後會產生異步消息，例如：{"params ":{"溢出":0,"數據":[[3292.432935,-535.44309,-1529.8374,9561.4], [3292.433256,-382.45935,-1606.32927,9561.48375]}} +初始查詢響應中的“header”字段用於描述在以後的“data”響應中找到的字段。 +pause_resume/cancel¶ +此端點類似於運行“PRINT_CANCEL”G 代碼命令。例如：{"id": 123, "method": "pause_resume/cancel"} +與“gcode/script”端點一樣，此端點僅在任何待處理的 G 代碼命令完成後才會完成。 +pause_resume/pause¶ +此端點類似於運行“PAUSE”G 代碼命令。例如：{"id": 123, "method": "pause_resume/pause"} +與“gcode/script”端點一樣，此端點僅在任何待處理的 G 代碼命令完成後才會完成。 +pause_resume/resume¶ +此端點類似於運行“RESUME”G 代碼命令。例如：{"id": 123, "method": "pause_resume/resume"} +與“gcode/script”端點一樣，此端點僅在任何待處理的 G 代碼命令完成後才會完成。 +query_endstops/status¶ +該端點將查詢活動端點並返回它們的狀態。例如：{"id": 123, "method": "query_endstops/status"} 可能返回：{"id": 123, "result": {"y": "open", "x": “打開”，“z”：“觸發”}} +與“gcode/script”端點一樣，此端點僅在任何待處理的 G 代碼命令完成後才會完成。 + + +
- + BL-Touch¶ -Connecting BL-Touch¶ -A warning before you start: Avoid touching the BL-Touch pin with -your bare fingers, since it is quite sensitive to finger grease. And -if you do touch it, be very gentle, in order to not bend or push -anything. -Hook up the BL-Touch "servo" connector to a control_pin according to -the BL-Touch documentation or your MCU documentation. Using the -original wiring, the yellow wire from the triple is the control_pin -and the white wire from the pair is the sensor_pin. You need to -configure these pins according to your wiring. Most BL-Touch devices -require a pullup on the sensor pin (prefix the pin name with "^"). For -example: +連線到 BL-Touch¶ +警告！：在你開始前請避免用你的手指接觸 BL-Touch 的探針，因為它對手指的油脂相當敏感。如果你真的觸控需要觸碰它，請儘可能小心，以避免彎曲或推動任何東西。 +根據 BL-Touch 文件或你使用的 MCU 的文件，將 BL-TOUCH 的 "servo"引腳連線到 control_pin。使用原裝連線線，三根線中的黃線是control_pin，兩根線中的白線是sensor_pin。你需要根據你的接線來配置這些引腳。大多數 BL-Touch 裝置要求在感測器引腳上有一個上拉電阻（引腳名稱前加"^"）。例如： [bltouch] sensor_pin: ^P1.24 control_pin: P1.26 -If the BL-Touch will be used to home the Z axis then set endstop_pin: -probe:z_virtual_endstop and remove position_endstop in the [stepper_z] config section, -then add a [safe_z_home] config section to raise the z axis, home the xy axes, -move to the center of the bed, and home the z axis. For example: +如果 BL-Touch 將用於 Z 軸歸位，則設定 endstop_pin:probe:z_virtual_endstop 並刪除 [stepper_z] 配置分段中的 position_endstop，然後新增一個 [safe_z_home] 配置分段來先提升 z 軸，並歸位 xy 軸，再移動到床的中心，並歸位 z 軸。例如： [safe_z_home] -home_xy_position: 100, 100 # Change coordinates to the center of your print bed +home_xy_position: 100, 100 # 修改該座標為列印床中心 speed: 50 -z_hop: 10 # Move up 10mm +z_hop: 10 # 向上移動 10mm z_hop_speed: 5 -It's important that the z_hop movement in safe_z_home is high enough -that the probe doesn't hit anything even if the probe pin happens to -be in its lowest state. -Initial tests¶ -Before moving on, verify that the BL-Touch is mounted at the correct -height, the pin should be roughly 2 mm above the nozzle when retracted -When you turn on the printer, the BL-Touch probe should perform a -self-test and move the pin up and down a couple of times. Once the -self-test is completed, the pin should be retracted and the red LED on -the probe should be lit. If there are any errors, for example the -probe is flashing red or the pin is down instead of up, please turn -off the printer and check the wiring and configuration. -If the above is looking good, it's time to test that the control pin -is working correctly. First run BLTOUCH_DEBUG COMMAND=pin_down in -your printer terminal. Verify that the pin moves down and that the red -LED on the probe turns off. If not, check your wiring and -configuration again. Next issue a BLTOUCH_DEBUG COMMAND=pin_up, -verify that the pin moves up, and that the red light turns on -again. If it's flashing then there's some problem. -The next step is to confirm that the sensor pin is working correctly. -Run BLTOUCH_DEBUG COMMAND=pin_down, verify that the pin moves down, -run BLTOUCH_DEBUG COMMAND=touch_mode, run QUERY_PROBE, and verify -that command reports "probe: open". Then while gently pushing the pin -up slightly with the nail of your finger run QUERY_PROBE again. -Verify the command reports "probe: TRIGGERED". If either query does -not report the correct message then it usually indicates an incorrect -wiring or configuration (though some clones may -require special handling). At the completion of this test run -BLTOUCH_DEBUG COMMAND=pin_up and verify that the pin moves up. -After completing the BL-Touch control pin and sensor pin tests, it is -now time to test probing, but with a twist. Instead of letting the -probe pin touch the print bed, let it touch the nail on your finger. -Position the toolhead far from the bed, issue a G28 (or PROBE if -not using probe:z_virtual_endstop), wait until the toolhead starts to -move down, and stop the movement by very gently touching the pin with -your nail. You may have to do it twice, since the default homing -configuration probes twice. Be prepared to turn off the printer if it -doesn't stop when you touch the pin. -If that was successful, do another G28 (or PROBE) but this time -let it touch the bed as it should. -BL-Touch gone bad¶ -Once the BL-Touch is in inconsistent state, it starts blinking red. -You can force it to leave that state by issuing: +重要的是，safe_z_home 中的 z_hop 運動需要足夠高以保證即使探針恰好處於最低狀態，也不會發生碰撞。 +初始測試¶ +在繼續前，請檢查 BL-Touch 是否安裝在正確的高度，探針在收起時應該在噴頭上大約2mm的位置 +啟動印表機時，BL-Touch 探針會執行自檢並上下移動探針幾次。自檢完成後，探針會處於收回狀態，探頭上的紅色 LED 在此時應亮起。如果有錯誤，例如探頭呈紅色閃爍或者探針伸出而不是收回，請關閉印表機並檢查接線和配置。 +如果以上都沒有問題，就可以測試 control 引腳是否正常工作了。首先在印表機終端中執行 BLTOUCH_DEBUG COMMAND=pin_down。確認探針伸出並且探頭上的紅色 LED 熄滅。如果沒有，請再次檢查印表機的接線和配置。接下來在印表機終端輸入 BLTOUCH_DEBUG COMMAND=pin_up，確認探針向上移動了，並且紅燈再次亮起。如果它閃爍，則說明存在問題。 +下一步是確認感測器的探針是否正常工作。執行BLTOUCH_DEBUG COMMAND=pin_down，檢查探針是否向下移動。執行BLTOUCH_DEBUG COMMAND=touch_mode，再執行QUERY_PROBE，並驗證命令報告"probe: open"。然後，在用指甲輕輕推起針頭的同時，再次執行QUERY_PROBE。驗證命令是否報告"probe: TRIGGERED"。如果任何一個查詢都沒有報告正確的資訊，那麼它通常表明接線或配置不正確（儘管一些盜版裝置需要特殊處理）。在這個測試完成後，執行BLTOUCH_DEBUG COMMAND=pin_up並檢查引腳是否向上移動。 +在完成 BL-TOUCH contro 引腳和 sensor 引腳的測試后，現在是測試探針的時候了，但有一個技巧。不要讓探針接觸列印床，而是讓它接觸你手指甲。將列印頭移動到離床面較遠的位置，發送G28（如果不使用probe:z_virtual_endstop，發送PROBE），等待工具頭開始向下移動，然後用手指甲輕輕地觸控針腳來停止移動。你可能要做兩次，因為預設的歸位配置會探測兩次。如果你觸控探針時它沒有停止，請立即關閉印表機電源。 +如果成功了，再做一次G28（或PROBE），但是這次讓它觸碰到熱床。 +BL-Touch 壞了¶ +當 BL-Touch 在不一致狀態時，它就會開始閃爍紅色。可以通過以下命令強制它離開此狀態： BLTOUCH_DEBUG COMMAND=reset -This may happen if its calibration is interrupted by the probe being -blocked from being extracted. -However, the BL-Touch may also not be able to calibrate itself -anymore. This happens if the screw on its top is in the wrong position -or the magnetic core inside the probe pin has moved. If it has moved -up so that it sticks to the screw, it may not be able to lower its pin -anymore. With this behavior you need to open the screw and use a -ball-point pen to push it gently back into place. Re-Insert the pin -into the BL-Touch so that it falls into the extracted position. -Carefully readjust the headless screw into place. You need to find the -right position so it is able to lower and raise the pin and the red -light turns on and of. Use the reset, pin_up and pin_down -commands to achieve this. -BL-Touch "clones"¶ -Many BL-Touch "clone" devices work correctly with Klipper using the -default configuration. However, some "clone" devices may not support -the QUERY_PROBE command and some "clone" devices may require -configuration of pin_up_reports_not_triggered or -pin_up_touch_mode_reports_triggered. -Important! Do not configure pin_up_reports_not_triggered or -pin_up_touch_mode_reports_triggered to False without first following -these directions. Do not configure either of these to False on a -genuine BL-Touch. Incorrectly setting these to False can increase -probing time and can increase the risk of damaging the printer. -Some "clone" devices do not support touch_mode and as a result the -QUERY_PROBE command does not work. Despite this, it may still be -possible to perform probing and homing with these devices. On these -devices the QUERY_PROBE command during the -initial tests will not succeed, however the -subsequent G28 (or PROBE) test does succeed. It may be possible to -use these "clone" devices with Klipper if one does not utilize the -QUERY_PROBE command and one does not enable the -probe_with_touch_mode feature. -Some "clone" devices are unable to perform Klipper's internal sensor -verification test. On these devices, attempts to home or probe can -result in Klipper reporting a "BLTouch failed to verify sensor state" -error. If this occurs, then manually run the steps to confirm the -sensor pin is working as described in the -initial tests section. If the QUERY_PROBE commands -in that test always produce the expected results and "BLTouch failed -to verify sensor state" errors still occur, then it may be necessary -to set pin_up_touch_mode_reports_triggered to False in the Klipper -config file. -A rare number of old "clone" devices are unable to report when they -have successfully raised their probe. On these devices Klipper will -report a "BLTouch failed to raise probe" error after every home or -probe attempt. One can test for these devices - move the head far from -the bed, run BLTOUCH_DEBUG COMMAND=pin_down, verify the pin has -moved down, run QUERY_PROBE, verify that command reports "probe: -open", run BLTOUCH_DEBUG COMMAND=pin_up, verify the pin has moved -up, and run QUERY_PROBE. If the pin remains up, the device does not -enter an error state, and the first query reports "probe: open" while -the second query reports "probe: TRIGGERED" then it indicates that -pin_up_reports_not_triggered should be set to False in the Klipper -config file. +這種情況可能會在校準中被阻止伸出的探針中斷時出現。 +但是，BL-TOUCH 也有可能無法再進行自我校準。這種情況會在它上面的螺絲處於錯誤的位置，或者探針內的磁芯移動之後出現。如果它移動了，以至於卡在了螺絲上，它可能無法再降低其探針。這種情況需要你打開螺絲並用圓珠筆將其輕輕推回原位。將探針重新插入BL-TOUCH，使其落入原來的位置。小心地將無頭螺釘重新調整到位。你需要找到正確的位置，使其能夠降低和提高探針，並且紅燈打開和關閉。使用reset、pin_up和pin_down命令來實現。 +BL-Touch 的克隆（3D-Touch）¶ +Klipper 預設配置支援大多數盜版 BL-Touch。但是，某些盜版裝置可能不支援 QUERY_PROBE 命令，並且一些裝置可能需要配置 pin_up_reports_not_triggered 或 pin_up_touch_mode_reports_triggered。 +注意！在沒有遵循這些指示之前，不要把 pin_up_reports_not_triggered 或 pin_up_touch_mode_reports_triggered 配置為 False。不要在正版 BL-Touch 上把這兩個參數配置為False。錯誤地將這些設定為 "False"會增加探測時間和損壞印表機的風險。 +一些盜版裝置不支援touch_mode，因此QUERY_PROBE命令不能正常執行。儘管如此，仍然有可能用這些裝置進行探測和歸位。這些裝置如果在初始測試期間的QUERY_PROBE命令不成功，但在隨後的G28（或PROBE）測試確實成功，則可以在 Klipper 中不使用QUERY_PROBE命令和不啟用probe_with_touch_mode功能時使用這些盜版裝置。 +一些克隆裝置無法執行 Klipper 的內部感測器驗證測試。在這些裝置上，嘗試歸位或探測會導致 Klipper 報告 "BLTouch failed to verify sensor state" 錯誤。如果發生這種情況，那麼請手動執行這些步驟以確認 sensor 引腳正確，如初次除錯所述。如果該測試中的QUERY_PROBE命令總是產生符合預期的結果，而 "BLTouch failed to verify sensor state "錯誤仍然發生，那麼可能需要在Klipper配置檔案中把pin_up_touch_mode_reports_triggered設為False。 +少數老版本克隆裝置無法報告它們何時成功地抬升了它們的探針。在這些裝置上，Klipper 會在每次歸位或探測嘗試后報告一個 "BLTouch failed to raise probe "的錯誤。可以對這些裝置進行測試--將探針從列印床移開，執行BLTOUCH_DEBUG COMMAND=pin_down，確認探針已經向下移動，執行QUERY_PROBE，確認命令報告 "probe:open"，執行BLTOUCH_DEBUG COMMAND=pin_up，確認探針已經抬升，並執行QUERY_PROBE。如果探針保持抬升，裝置沒有進入錯誤狀態，且第一個查詢報告 "probe: open"，而第二個查詢報告 "probe:TRIGGERED"，那麼它表明pin_up_reports_not_triggered應該在Klipper配置檔案中被設定為False。 BL-Touch v3¶ -Some BL-Touch v3.0 and BL-Touch 3.1 devices may require configuring -probe_with_touch_mode in the printer config file. -If the BL-Touch v3.0 has its signal wire connected to an endstop pin -(with a noise filtering capacitor), then the BL-Touch v3.0 may not be -able to consistently send a signal during homing and probing. If the -QUERY_PROBE commands in the initial tests section -always produce the expected results, but the toolhead does not always -stop during G28/PROBE commands, then it is indicative of this issue. A -workaround is to set probe_with_touch_mode: True in the config file. -The BL-Touch v3.1 may incorrectly enter an error state after a -successful probe attempt. The symptoms are an occasional flashing -light on the BL-Touch v3.1 that lasts for a couple of seconds after it -successfully contacts the bed. Klipper should clear this error -automatically and it is generally harmless. However, one may set -probe_with_touch_mode in the config file to avoid this issue. -Important! Some "clone" devices and the BL-Touch v2.0 (and earlier) -may have reduced accuracy when probe_with_touch_mode is set to True. -Setting this to True also increases the time it takes to deploy the -probe. If configuring this value on a "clone" or older BL-Touch -device, be sure to test the probe accuracy before and after setting -this value (use the PROBE_ACCURACY command to test). -Multi-probing without stowing¶ -By default, Klipper will deploy the probe at the start of each probe -attempt and then stow the probe afterwards. This repetitive deploying -and stowing of the probe may increase the total time of calibration -sequences that involve many probe measurements. Klipper supports -leaving the probe deployed between consecutive probes, which can -reduce the total time of probing. This mode is enabled by configuring -stow_on_each_sample to False in the config file. -Important! Setting stow_on_each_sample to False can lead to Klipper -making horizontal toolhead movements while the probe is deployed. Be -sure to verify all probing operations have sufficient Z clearance -prior to setting this value to False. If there is insufficient -clearance then a horizontal move may cause the pin to catch on an -obstruction and result in damage to the printer. -Important! It is recommended to use probe_with_touch_mode configured -to True when using stow_on_each_sample configured to False. Some -"clone" devices may not detect a subsequent bed contact if -probe_with_touch_mode is not set. On all devices, using the -combination of these two settings simplifies the device signaling, -which can improve overall stability. -Note, however, that some "clone" devices and the BL-Touch v2.0 (and -earlier) may have reduced accuracy when probe_with_touch_mode is set -to True. On these devices it is a good idea to test the probe accuracy -before and after setting probe_with_touch_mode (use the -PROBE_ACCURACY command to test). -Calibrating the BL-Touch offsets¶ -Follow the directions in the Probe Calibrate -guide to set the x_offset, y_offset, and z_offset config parameters. -It's a good idea to verify that the Z offset is close to 1mm. If not, -then you probably want to move the probe up or down to fix this. You -want it to trigger well before the nozzle hits the bed, so that -possible stuck filament or a warped bed doesn't affect any probing -action. But at the same time, you want the retracted position to be as -far above the nozzle as possible to avoid it touching printed parts. -If an adjustment is made to the probe position, then rerun the probe -calibration steps. -BL-Touch output mode¶ +一些 BL-Touch v3.0 和BL-Touch 3.1 裝置可能需要在印表機配置檔案中配置probe_with_touch_mode。 +如果BL-TOUCH v3.0的訊號線連線到一個限位引腳（有一個噪音過濾電容），那麼BL-TOUCH v3.0可能無法在歸位和探測期間持續發送訊號。如果初次除錯中的QUERY_PROBE命令總是產生預期的結果，但在G28/PROBE命令期間，工具頭並不總是停止，那麼就表明有這個問題。一個變通的辦法是在在配置檔案中設定probe_with_touch_mode:True。 +BL-TOUCH v3.1 可能會在嘗試探測成功后錯誤地進入錯誤狀態。其癥狀是 BL-TOUCH v3.1 在成功接觸列印床后，偶爾會有燈光閃爍，持續幾秒鐘。Klipper 應該會自動清除這個錯誤，一般來說是沒有問題的。當然你可以在配置檔案中設定probe_with_touch_mode來避免這個問題。 +注意！當 probe_with_touch_mode 被設定為 True 時，一些 克隆裝置和BL-Touch v2.0（及更早）可能會降低精度。將此設定為 True 也會增加部署探針的時間。如果在 克隆 或更早的BL-Touch裝置上配置這個值，一定要在設定這個值之前和之後測試探針的準確性（使用PROBE_ACCURACY命令進行測試）。 +無收起多次探測¶ +預設情況下，Klipper 會在每次探測嘗試開始時部署探針，然後在之後收起探針。這種重複部署和收起探針的做法可能會增加涉及許多探針測量的校準序列的總耗時。Klipper 支援在連續的探測之間不收起探針，這可以減少探測的總耗時。可以通過在配置檔案中把 stow_on_each_sample 配置為 False 來啟用這個模式。 +注意！將 Stow_on_each_sample 設定為 False 可能導致 Klipper 在探針放下時進行水平的列印頭運動。在將此值設定為 "False"之前，請確保所有探測操作都有足夠的Z間隙。如果沒有足夠的間隙，那麼水平移動可能會導致探針卡在障礙物上並且導致印表機損壞。 +注意！當配置stow_on_each_sample為False時，建議將probe_with_touch_mode配置為 True。如果沒有設定probe_with_touch_mode，一些克隆的裝置可能檢測不到後續和列印床的接觸。在所有的裝置上，使用這兩個設定的組合可以簡化裝置的訊號傳遞，從而提高整體穩定性。 +但是請注意，當probe_with_touch_mode設定為True時，一些克隆裝置和BL-Touch v2.0（以及更早）可能會降低精度。在這些裝置上，最好在設定probe_with_touch_mode之前和之後測試探針的準確性（使用PROBE_ACCURACY命令來測試）。 +校準 BL-Touch 的偏移¶ +按照探針校準指南中的指示來設定x_offset、y_offset和z_offset配置參數。 +最好確認 Z 軸偏移量接近 1 mm。如果不是，那麼你可能希望將探頭向上或向下移動來解決這個問題。你需要讓它在噴嘴碰到床面之前可以很好的觸發，這樣可能出現的殘留耗材或扭曲的床面就不會影響任何探測動作。但與此同時，收回的位置最好儘可能高於噴嘴，以避免它接觸到列印件。如果對探針位置進行了調整，需要在調整後重新執行探針校準步驟。 +BL-Touch 輸出模式¶ -A BL-Touch V3.0 supports setting a 5V or OPEN-DRAIN output mode, - a BL-Touch V3.1 supports this too, but can also store this in its - internal EEPROM. If your controller board needs the fixed 5V high - logic level of the 5V mode you may set the 'set_output_mode' - parameter in the [bltouch] section of the printer config file to - "5V". - Only use the 5V mode if your controller boards input line is -5V tolerant. This is why the default configuration of these BL-Touch -versions is OPEN-DRAIN mode. You could potentially damage your -controller boards CPU -So therefore: -If a controller board NEEDs 5V mode AND it is 5V tolerant on its -input signal line AND if - -you have a BL-Touch Smart V3.0, you need the use 'set_output_mode: 5V' - parameter to ensure this setting at each startup, since the probe - cannot remember the needed setting. -you have a BL-Touch Smart V3.1, you have the choice of using - 'set_output_mode: 5V' or storing the mode once by use of a - 'BLTOUCH_STORE MODE=5V' command manually and NOT using the parameter - 'set_output_mode:'. -you have some other probe: Some probes have a trace on the circuit board - to cut or a jumper to set in order to (permanently) set the output mode. - In that case, omit the 'set_output_mode' parameter completely. - -If you have a V3.1, do not automate or repeat storing the output mode to -avoid wearing out the EEPROM of the probe.The BLTouch EEPROM is good for -about 100.000 updates. 100 stores per day would add up to about 3 years -of operation prior to wearing it out. Thus, storing the output mode in a -V3.1 is designed by the vendor to be a complicated operation (the factory -default being a safe OPEN DRAIN mode) and is not suited to be repeatedly -issued by any slicer, macro or anything else, it is preferably only to be -used when first integrating the probe into a printers electronics. +BL-Touch V3.0支援設定 5V 或 OPEN-DRAIN 輸出模式，BL-TOUCH V3.1也支援，但它也可以在其內部 EEPROM 中儲存這個設定。如果你的控制主板需要 5V 模式的固定 5V 高邏輯電平，你可以把印表機配置檔案[bltouch]部分的 'set_output_mode' 參數設定為 "5V"。 只在你的控制主板的輸入線路可以容忍5V時使用 5V 模式。這就是為什麼這些 BL-Touch 版本的預設配置是OPEN-DRAIN模式。你有可能損壞你的控制主板上的MCU +因此。如果一個控制主板需要 5V 模式，並且它的輸入訊號線是 5V 的，並且如果 + + +你有一個 BL-TOUCH Smart V3.0，你需要使用 'set_output_mode:5V' 參數，以確保每次啟動時的應用這一設定，因為探針不能記住所需的設定。 +如果你有一個 BL-Touch Smart V3.1，你可以選擇使用 'set_output_mode:5V " 或者通過手動使用 "BLTOUCH_STORE MODE=5V "命令，而不是使用參數 "set_output_mode: "來儲存模式。 +如果你有一些其他的探針。有些探針在電路板上有一個需要切除的線路或者需要設定的一個跳線，以便（永久）設定輸出模式。在這種情況下，完全省略 "set_output_mode "參數。 +如果你有一個 V3.1，不要自動或重複儲存輸出模式，以避免磨損探針的 EEPROM。BLTouch 的 EEPROM可用於約100.000次更新。每天儲存100次，在磨損之前，加起來大約可以執行3年。因此，在 V3.1 中儲存輸出模式被供應商設計成一個複雜的操作（出廠預設值是一個 safe OPEN DRAIN 模式），不適合由任何切片軟體、宏或其他東西重複發出，最好僅在首次將探針新增到到印表機電子裝置時使用。 @@ -1554,29 +1424,29 @@ used when first integrating the probe into a printers electronics. - + - + @@ -88,9 +88,9 @@ - + - + @@ -136,6 +136,38 @@ + + + + + + + + + + + + English + + + + + + 简体中文 + + + + + + 繁體中文 + + + + + + + + @@ -144,7 +176,7 @@ - + @@ -167,7 +199,7 @@ - Initializing search + 正在初始化搜尋引擎 @@ -178,7 +210,7 @@ - + @@ -213,16 +245,16 @@ - + - + Klipper documentation - + @@ -244,7 +276,7 @@ - Overview + 概述 @@ -259,7 +291,7 @@ - Features + 功能 @@ -274,7 +306,7 @@ - Frequently Asked Questions + 常見問題 @@ -289,7 +321,7 @@ - Releases + 版本發佈 @@ -304,7 +336,7 @@ - Configuration Changes + 配置變更 @@ -319,7 +351,7 @@ - Contact + 聯繫方式 @@ -360,7 +392,7 @@ - Installation + 安裝 @@ -400,7 +432,7 @@ - Configuration reference + 配置參考 @@ -414,7 +446,7 @@ - Rotation distance + 旋轉距離 @@ -435,7 +467,7 @@ - Configuration checks + 配置檢查 @@ -475,7 +507,7 @@ - Bed leveling + 列印床調平 @@ -489,7 +521,7 @@ - Delta calibration + 三角校正 @@ -503,7 +535,7 @@ - Probe calibration + 探針校準 @@ -531,7 +563,7 @@ - Manual leveling + 手動調平 @@ -545,7 +577,7 @@ - Bed Mesh + 床網 @@ -559,7 +591,7 @@ - Endstop phase + 限位相位 @@ -606,7 +638,7 @@ - Resonance Compensation + 共振補償 @@ -620,7 +652,7 @@ - Measuring Resonances + 共振值測量 @@ -695,7 +727,7 @@ - Commands templates + 命令模板 @@ -709,7 +741,7 @@ - Status reference + 狀態參考 @@ -730,7 +762,7 @@ - TMC drivers + TMC 驅動器 @@ -744,7 +776,7 @@ - Multiple Micro-controller Homing and Probing + 複數微控制器歸零與探高 @@ -758,7 +790,7 @@ - Slicers + 切片軟體 @@ -772,7 +804,7 @@ - Skew correction + 偏斜校正 @@ -786,7 +818,7 @@ - Using PWM tools + 使用 PWM 工具 @@ -834,7 +866,7 @@ - Code overview + 程式碼總覽 @@ -848,7 +880,7 @@ - Kinematics + 運動學 @@ -862,7 +894,7 @@ - Protocol + 協議 @@ -876,7 +908,7 @@ - API server + API 伺服器 @@ -890,7 +922,7 @@ - MCU commands + MCU命令 @@ -904,7 +936,7 @@ - CANBUS protocol + CANBUS 協議 @@ -918,7 +950,7 @@ - Debugging + 除錯 @@ -932,7 +964,7 @@ - Benchmarks + 基準測試 @@ -946,7 +978,7 @@ - Contributing to Klipper + 為 Klipper 做貢獻 @@ -960,7 +992,7 @@ - Packaging Klipper + 打包 Klipper @@ -1010,7 +1042,7 @@ - Example configurations + 配置示例 @@ -1024,7 +1056,7 @@ - SDCard updates + 通過SD卡更新 @@ -1038,7 +1070,7 @@ - RPi microcontroller + RPi 微控制器 @@ -1071,7 +1103,7 @@ - + @@ -1080,41 +1112,41 @@ - Table of contents + 目錄 - - Building an OS image + + 構建一個操作系統映象 - - Install Octoprint + + 安裝 Octoprint - - Building the micro-controller code + + 構建微控制器程式碼 - - Remaining configuration + + 剩餘的配置 - - Printing on the Beaglebone + + 在 Beaglebone 上列印 @@ -1135,7 +1167,7 @@ - Bootloaders + 底層載入程式 @@ -1149,7 +1181,7 @@ - CANBUS + CAN 匯流排 @@ -1163,7 +1195,7 @@ - TSL1401CL filament width sensor + TSL1401CL 耗材寬度感測器 @@ -1177,7 +1209,7 @@ - Hall filament width sensor + 霍爾耗材線徑感測器 @@ -1203,7 +1235,7 @@ - + @@ -1212,41 +1244,41 @@ - Table of contents + 目錄 - - Building an OS image + + 構建一個操作系統映象 - - Install Octoprint + + 安裝 Octoprint - - Building the micro-controller code + + 構建微控制器程式碼 - - Remaining configuration + + 剩餘的配置 - - Printing on the Beaglebone + + 在 Beaglebone 上列印 @@ -1263,91 +1295,70 @@ - + Beaglebone¶ -This document describes the process of running Klipper on a Beaglebone -PRU. -Building an OS image¶ -Start by installing the -Debian 9.9 2019-08-03 4GB SD IoT -image. One may run the image from either a micro-SD card or from -builtin eMMC. If using the eMMC, install it to eMMC now by following -the instructions from the above link. -Then ssh into the Beaglebone machine (ssh debian@beaglebone -- -password is temppwd) and install Klipper by running the following -commands: +本文件描述了在 Beaglebone 可程式設計實時單元上執行 Klipper 的過程。 +構建一個操作系統映象¶ +首先安裝Debian 9.9 2019-08-03 4GB SD IoT映象。可以從micro-SD卡或內建的eMMC中執行該映象。如果使用eMMC，現在需要按照上述鏈接的說明將其安裝到eMMC。 +然後 ssh 進入 Beaglebone 機器（ssh debian@beaglebone -- 密碼是 temppwd），通過執行以下命令安裝 Klipper： git clone https://github.com/Klipper3d/klipper ./klipper/scripts/install-beaglebone.sh -Install Octoprint¶ -One may then install Octoprint: +安裝 Octoprint¶ +然後可以安裝 Octoprint： git clone https://github.com/foosel/OctoPrint.git cd OctoPrint/ virtualenv venv ./venv/bin/python setup.py install -And setup OctoPrint to start at bootup: +和設定 Octoprint 開始啟動： sudo cp ~/OctoPrint/scripts/octoprint.init /etc/init.d/octoprint sudo chmod +x /etc/init.d/octoprint sudo cp ~/OctoPrint/scripts/octoprint.default /etc/default/octoprint sudo update-rc.d octoprint defaults -It is necessary to modify OctoPrint's /etc/default/octoprint -configuration file. One must change the OCTOPRINT_USER user to -debian, change NICELEVEL to 0, uncomment the BASEDIR, CONFIGFILE, -and DAEMON settings and change the references from /home/pi/ to -/home/debian/: +在配置 Klipper 之前，需要先修改OctoPrint的 /etc/default/octoprint 配置檔案。把 OCTOPRINT_USER 使用者改為 debian，把 NICELEVEL 改為 0 ，取消註釋 BASEDIR、CONFIGFILE 和 DAEMON 的設定，並把引用從/home/pi/改為/home/debian/： sudo nano /etc/default/octoprint -Then start the Octoprint service: +然後啟動 Octoprint 服務： sudo systemctl start octoprint -Make sure the OctoPrint web server is accessible - it should be at: -http://beaglebone:5000/ -Building the micro-controller code¶ -To compile the Klipper micro-controller code, start by configuring it -for the "Beaglebone PRU": +需要確定可以訪問 OctoPrint 網路伺服器 - 它應該可以通過這個鏈接訪問： http://beaglebone:5000/ +構建微控制器程式碼¶ +要編譯的 Klipper 微控制器程式碼，需要先將編譯配置設為「Beaglebone PRU」： cd ~/klipper/ make menuconfig -To build and install the new micro-controller code, run: +要構建和安裝新的微控制器程式碼，請執行： sudo service klipper stop make flash sudo service klipper start -It is also necessary to compile and install the micro-controller code -for a Linux host process. Configure it a second time for a "Linux process": +還需要編譯和安裝用於 Linux 主機程序的微控制器程式碼。再次修改編譯配置為"Linux process"： make menuconfig -Then install this micro-controller code as well: +然後也安裝這個微控制器程式碼： sudo service klipper stop make flash sudo service klipper start -Remaining configuration¶ -Complete the installation by configuring Klipper and Octoprint -following the instructions in -the main Installation document. -Printing on the Beaglebone¶ -Unfortunately, the Beaglebone processor can sometimes struggle to run -OctoPrint well. Print stalls have been known to occur on complex -prints (the printer may move faster than OctoPrint can send movement -commands). If this occurs, consider using the "virtual_sdcard" feature -(see Config Reference for -details) to print directly from Klipper. +剩餘的配置¶ +根據安裝文件配置 Klipper 和 Octoprint 以完成安裝。 +在 Beaglebone 上列印¶ +不幸的是，Beaglebone 處理器有時不能流暢地執行 OctoPrint。在複雜的列印中會出現列印停滯（印表機的移動速度可能比 OctoPrint 發送的移動命令快）是一個已知問題。如果發生這種情況，可以嘗試使用 "virtual_sdcard" 功能（詳見配置參考），直接從 Klipper 列印。 @@ -1366,29 +1377,29 @@ details) to print directly from Klipper. - + - +
- + Beaglebone¶ -This document describes the process of running Klipper on a Beaglebone -PRU. -Building an OS image¶ -Start by installing the -Debian 9.9 2019-08-03 4GB SD IoT -image. One may run the image from either a micro-SD card or from -builtin eMMC. If using the eMMC, install it to eMMC now by following -the instructions from the above link. -Then ssh into the Beaglebone machine (ssh debian@beaglebone -- -password is temppwd) and install Klipper by running the following -commands: +本文件描述了在 Beaglebone 可程式設計實時單元上執行 Klipper 的過程。 +構建一個操作系統映象¶ +首先安裝Debian 9.9 2019-08-03 4GB SD IoT映象。可以從micro-SD卡或內建的eMMC中執行該映象。如果使用eMMC，現在需要按照上述鏈接的說明將其安裝到eMMC。 +然後 ssh 進入 Beaglebone 機器（ssh debian@beaglebone -- 密碼是 temppwd），通過執行以下命令安裝 Klipper： git clone https://github.com/Klipper3d/klipper ./klipper/scripts/install-beaglebone.sh -Install Octoprint¶ -One may then install Octoprint: +安裝 Octoprint¶ +然後可以安裝 Octoprint： git clone https://github.com/foosel/OctoPrint.git cd OctoPrint/ virtualenv venv ./venv/bin/python setup.py install -And setup OctoPrint to start at bootup: +和設定 Octoprint 開始啟動： sudo cp ~/OctoPrint/scripts/octoprint.init /etc/init.d/octoprint sudo chmod +x /etc/init.d/octoprint sudo cp ~/OctoPrint/scripts/octoprint.default /etc/default/octoprint sudo update-rc.d octoprint defaults -It is necessary to modify OctoPrint's /etc/default/octoprint -configuration file. One must change the OCTOPRINT_USER user to -debian, change NICELEVEL to 0, uncomment the BASEDIR, CONFIGFILE, -and DAEMON settings and change the references from /home/pi/ to -/home/debian/: +在配置 Klipper 之前，需要先修改OctoPrint的 /etc/default/octoprint 配置檔案。把 OCTOPRINT_USER 使用者改為 debian，把 NICELEVEL 改為 0 ，取消註釋 BASEDIR、CONFIGFILE 和 DAEMON 的設定，並把引用從/home/pi/改為/home/debian/： sudo nano /etc/default/octoprint -Then start the Octoprint service: +然後啟動 Octoprint 服務： sudo systemctl start octoprint -Make sure the OctoPrint web server is accessible - it should be at: -http://beaglebone:5000/ -Building the micro-controller code¶ -To compile the Klipper micro-controller code, start by configuring it -for the "Beaglebone PRU": +需要確定可以訪問 OctoPrint 網路伺服器 - 它應該可以通過這個鏈接訪問： http://beaglebone:5000/ +構建微控制器程式碼¶ +要編譯的 Klipper 微控制器程式碼，需要先將編譯配置設為「Beaglebone PRU」： cd ~/klipper/ make menuconfig -To build and install the new micro-controller code, run: +要構建和安裝新的微控制器程式碼，請執行： sudo service klipper stop make flash sudo service klipper start -It is also necessary to compile and install the micro-controller code -for a Linux host process. Configure it a second time for a "Linux process": +還需要編譯和安裝用於 Linux 主機程序的微控制器程式碼。再次修改編譯配置為"Linux process"： make menuconfig -Then install this micro-controller code as well: +然後也安裝這個微控制器程式碼： sudo service klipper stop make flash sudo service klipper start -Remaining configuration¶ -Complete the installation by configuring Klipper and Octoprint -following the instructions in -the main Installation document. -Printing on the Beaglebone¶ -Unfortunately, the Beaglebone processor can sometimes struggle to run -OctoPrint well. Print stalls have been known to occur on complex -prints (the printer may move faster than OctoPrint can send movement -commands). If this occurs, consider using the "virtual_sdcard" feature -(see Config Reference for -details) to print directly from Klipper. +剩餘的配置¶ +根據安裝文件配置 Klipper 和 Octoprint 以完成安裝。 +在 Beaglebone 上列印¶ +不幸的是，Beaglebone 處理器有時不能流暢地執行 OctoPrint。在複雜的列印中會出現列印停滯（印表機的移動速度可能比 OctoPrint 發送的移動命令快）是一個已知問題。如果發生這種情況，可以嘗試使用 "virtual_sdcard" 功能（詳見配置參考），直接從 Klipper 列印。