mirror of
				https://github.com/Klipper3d/klipper.git
				synced 2025-10-31 10:25:57 +01:00 
			
		
		
		
	
		
			
				
	
	
		
			294 lines
		
	
	
		
			15 KiB
		
	
	
	
		
			Markdown
		
	
	
	
	
	
			
		
		
	
	
			294 lines
		
	
	
		
			15 KiB
		
	
	
	
		
			Markdown
		
	
	
	
	
	
| # MCU commands
 | |
| 
 | |
| This document provides information on the low-level micro-controller
 | |
| commands that are sent from the Klipper "host" software and processed
 | |
| by the Klipper micro-controller software. This document is not an
 | |
| authoritative reference for these commands, nor is it an exclusive
 | |
| list of all available commands.
 | |
| 
 | |
| This document may be useful for developers interested in understanding
 | |
| the low-level micro-controller commands.
 | |
| 
 | |
| See the [protocol](Protocol.md) document for more information on the
 | |
| format of commands and their transmission. The commands here are
 | |
| described using their "printf" style syntax - for those unfamiliar
 | |
| with that format, just note that where a '%...' sequence is seen it
 | |
| should be replaced with an actual integer. For example, a description
 | |
| with "count=%c" could be replaced with the text "count=10". Note that
 | |
| parameters that are considered "enumerations" (see the above protocol
 | |
| document) take a string value which is automatically converted to an
 | |
| integer value for the micro-controller. This is common with parameters
 | |
| named "pin" (or that have a suffix of "_pin").
 | |
| 
 | |
| ## Startup Commands
 | |
| 
 | |
| It may be necessary to take certain one-time actions to configure the
 | |
| micro-controller and its peripherals. This section lists common
 | |
| commands available for that purpose. Unlike most micro-controller
 | |
| commands, these commands run as soon as they are received and they do
 | |
| not require any particular setup.
 | |
| 
 | |
| Common startup commands:
 | |
| 
 | |
| * `set_digital_out pin=%u value=%c` : This command immediately
 | |
|   configures the given pin as a digital out GPIO and it sets it to
 | |
|   either a low level (value=0) or a high level (value=1). This command
 | |
|   may be useful for configuring the initial value of LEDs and for
 | |
|   configuring the initial value of stepper driver micro-stepping pins.
 | |
| 
 | |
| * `set_pwm_out pin=%u cycle_ticks=%u value=%hu` : This command will
 | |
|   immediately configure the given pin to use hardware based
 | |
|   pulse-width-modulation (PWM) with the given number of
 | |
|   cycle_ticks. The "cycle_ticks" is the number of MCU clock ticks each
 | |
|   power on and power off cycle should last. A cycle_ticks value of 1
 | |
|   can be used to request the fastest possible cycle time. The "value"
 | |
|   parameter is between 0 and 255 with 0 indicating a full off state
 | |
|   and 255 indicating a full on state. This command may be useful for
 | |
|   enabling CPU and nozzle cooling fans.
 | |
| 
 | |
| ## Low-level micro-controller configuration
 | |
| 
 | |
| Most commands in the micro-controller require an initial setup before
 | |
| they can be successfully invoked. This section provides an overview of
 | |
| the configuration process. This section and the following sections are
 | |
| likely only of interest to developers interested in the internal
 | |
| details of Klipper.
 | |
| 
 | |
| When the host first connects to the micro-controller it always starts
 | |
| by obtaining a data dictionary (see [protocol](Protocol.md) for more
 | |
| information). After the data dictionary is obtained the host will
 | |
| check if the micro-controller is in a "configured" state and configure
 | |
| it if not. Configuration involves the following phases:
 | |
| 
 | |
| * `get_config` : The host starts by checking if the micro-controller
 | |
|   is already configured. The micro-controller responds to this command
 | |
|   with a "config" response message. The micro-controller software
 | |
|   always starts in an unconfigured state at power-on. It remains in
 | |
|   this state until the host completes the configuration processes (by
 | |
|   issuing a finalize_config command). If the micro-controller is
 | |
|   already configured from a previous session (and is configured with
 | |
|   the desired settings) then no further action is needed by the host
 | |
|   and the configuration process ends successfully.
 | |
| 
 | |
| * `allocate_oids count=%c` : This command is issued to inform the
 | |
|   micro-controller of the maximum number of object-ids (oid) that the
 | |
|   host requires. It is only valid to issue this command once. An oid
 | |
|   is an integer identifier allocated to each stepper, each endstop,
 | |
|   and each schedulable gpio pin. The host determines in advance the
 | |
|   number of oids it will require to operate the hardware and passes
 | |
|   this to the micro-controller so that it may allocate sufficient
 | |
|   memory to store a mapping from oid to internal object.
 | |
| 
 | |
| * `config_XXX oid=%c ...` : By convention any command starting with
 | |
|   the "config_" prefix creates a new micro-controller object and
 | |
|   assigns the given oid to it. For example, the config_digital_out
 | |
|   command will configure the specified pin as a digital output GPIO
 | |
|   and create an internal object that the host can use to schedule
 | |
|   changes to the given GPIO. The oid parameter passed into the config
 | |
|   command is selected by the host and must be between zero and the
 | |
|   maximum count supplied in the allocate_oids command. The config
 | |
|   commands may only be run when the micro-controller is not in a
 | |
|   configured state (ie, prior to the host sending finalize_config) and
 | |
|   after the allocate_oids command has been sent.
 | |
| 
 | |
| * `finalize_config crc=%u` : The finalize_config command transitions
 | |
|   the micro-controller from an unconfigured state to a configured
 | |
|   state. The crc parameter passed to the micro-controller is stored
 | |
|   and provided back to the host in "config" response messages. By
 | |
|   convention, the host takes a 32bit CRC of the configuration it will
 | |
|   request and at the start of subsequent communication sessions it
 | |
|   checks that the CRC stored in the micro-controller exactly matches
 | |
|   its desired CRC. If the CRC does not match then the host knows the
 | |
|   micro-controller has not been configured in the state desired by the
 | |
|   host.
 | |
| 
 | |
| ### Common micro-controller objects
 | |
| 
 | |
| This section lists some commonly used config commands.
 | |
| 
 | |
| * `config_digital_out oid=%c pin=%u value=%c default_value=%c
 | |
|   max_duration=%u` : This command creates an internal micro-controller
 | |
|   object for the given GPIO 'pin'. The pin will be configured in
 | |
|   digital output mode and set to an initial value as specified by
 | |
|   'value' (0 for low, 1 for high). Creating a digital_out object
 | |
|   allows the host to schedule GPIO updates for the given pin at
 | |
|   specified times (see the queue_digital_out command described below).
 | |
|   Should the micro-controller software go into shutdown mode then all
 | |
|   configured digital_out objects will be set to 'default_value'. The
 | |
|   'max_duration' parameter is used to implement a safety check - if it
 | |
|   is non-zero then it is the maximum number of clock ticks that the
 | |
|   host may set the given GPIO to a non-default value without further
 | |
|   updates. For example, if the default_value is zero and the
 | |
|   max_duration is 16000 then if the host sets the gpio to a value of
 | |
|   one then it must schedule another update to the gpio pin (to either
 | |
|   zero or one) within 16000 clock ticks. This safety feature can be
 | |
|   used with heater pins to ensure the host does not enable the heater
 | |
|   and then go off-line.
 | |
| 
 | |
| * `config_pwm_out oid=%c pin=%u cycle_ticks=%u value=%hu
 | |
|   default_value=%hu max_duration=%u` : This command creates an
 | |
|   internal object for hardware based PWM pins that the host may
 | |
|   schedule updates for. Its usage is analogous to config_digital_out -
 | |
|   see the description of the 'set_pwm_out' and 'config_digital_out'
 | |
|   commands for parameter description.
 | |
| 
 | |
| * `config_analog_in oid=%c pin=%u` : This command is used to configure
 | |
|   a pin in analog input sampling mode. Once configured, the pin can be
 | |
|   sampled at regular interval using the query_analog_in command (see
 | |
|   below).
 | |
| 
 | |
| * `config_stepper oid=%c step_pin=%c dir_pin=%c invert_step=%c
 | |
|   step_pulse_ticks=%u` : This command creates an internal stepper
 | |
|   object. The 'step_pin' and 'dir_pin' parameters specify the step and
 | |
|   direction pins respectively; this command will configure them in
 | |
|   digital output mode. The 'invert_step' parameter specifies whether a
 | |
|   step occurs on a rising edge (invert_step=0) or falling edge
 | |
|   (invert_step=1). The 'step_pulse_ticks' parameter specifies the
 | |
|   minimum duration of the step pulse. If the mcu exports the constant
 | |
|   'STEPPER_BOTH_EDGE=1' then setting step_pulse_ticks=0 and
 | |
|   invert_step=-1 will setup for stepping on both the rising and
 | |
|   falling edges of the step pin.
 | |
| 
 | |
| * `config_endstop oid=%c pin=%c pull_up=%c stepper_count=%c` : This
 | |
|   command creates an internal "endstop" object. It is used to specify
 | |
|   the endstop pins and to enable "homing" operations (see the
 | |
|   endstop_home command below). The command will configure the
 | |
|   specified pin in digital input mode. The 'pull_up' parameter
 | |
|   determines whether hardware provided pullup resistors for the pin
 | |
|   (if available) will be enabled. The 'stepper_count' parameter
 | |
|   specifies the maximum number of steppers that this endstop may need
 | |
|   to halt during a homing operation (see endstop_home below).
 | |
| 
 | |
| * `config_spi oid=%c bus=%u pin=%u mode=%u rate=%u shutdown_msg=%*s` :
 | |
|   This command creates an internal SPI object. It is used with
 | |
|   spi_transfer and spi_send commands (see below).  The "bus"
 | |
|   identifies the SPI bus to use (if the micro-controller has more than
 | |
|   one SPI bus available). The "pin" specifies the chip select (CS) pin
 | |
|   for the device. The "mode" is the SPI mode (should be between 0 and
 | |
|   3). The "rate" parameter specifies the SPI bus rate (in cycles per
 | |
|   second). Finally, the "shutdown_msg" is an SPI command to send to
 | |
|   the given device should the micro-controller go into a shutdown
 | |
|   state.
 | |
| 
 | |
| * `config_spi_without_cs oid=%c bus=%u mode=%u rate=%u
 | |
|   shutdown_msg=%*s` : This command is similar to config_spi, but
 | |
|   without a CS pin definition. It is useful for SPI devices that do
 | |
|   not have a chip select line.
 | |
| 
 | |
| ## Common commands
 | |
| 
 | |
| This section lists some commonly used run-time commands. It is likely
 | |
| only of interest to developers looking to gain insight into Klipper.
 | |
| 
 | |
| * `set_digital_out_pwm_cycle oid=%c cycle_ticks=%u` : This command
 | |
|   configures a digital output pin (as created by config_digital_out)
 | |
|   to use "software PWM". The 'cycle_ticks' is the number of clock
 | |
|   ticks for the PWM cycle. Because the output switching is implemented
 | |
|   in the micro-controller software, it is recommended that
 | |
|   'cycle_ticks' correspond to a time of 10ms or greater.
 | |
| 
 | |
| * `queue_digital_out oid=%c clock=%u on_ticks=%u` : This command will
 | |
|   schedule a change to a digital output GPIO pin at the given clock
 | |
|   time. To use this command a 'config_digital_out' command with the
 | |
|   same 'oid' parameter must have been issued during micro-controller
 | |
|   configuration. If 'set_digital_out_pwm_cycle' has been called then
 | |
|   'on_ticks' is the on duration (in clock ticks) for the pwm cycle.
 | |
|   Otherwise, 'on_ticks' should be either 0 (for low voltage) or 1 (for
 | |
|   high voltage).
 | |
| 
 | |
| * `queue_pwm_out oid=%c clock=%u value=%hu` : Schedules a change to a
 | |
|   hardware PWM output pin. See the 'queue_digital_out' and
 | |
|   'config_pwm_out' commands for more info.
 | |
| 
 | |
| * `query_analog_in oid=%c clock=%u sample_ticks=%u sample_count=%c
 | |
|   rest_ticks=%u min_value=%hu max_value=%hu` : This command sets up a
 | |
|   recurring schedule of analog input samples. To use this command a
 | |
|   'config_analog_in' command with the same 'oid' parameter must have
 | |
|   been issued during micro-controller configuration. The samples will
 | |
|   start as of 'clock' time, it will report on the obtained value every
 | |
|   'rest_ticks' clock ticks, it will over-sample 'sample_count' number
 | |
|   of times, and it will pause 'sample_ticks' number of clock ticks
 | |
|   between over-sample samples. The 'min_value' and 'max_value'
 | |
|   parameters implement a safety feature - the micro-controller
 | |
|   software will verify the sampled value (after any oversampling) is
 | |
|   always between the supplied range. This is intended for use with
 | |
|   pins attached to thermistors controlling heaters - it can be used to
 | |
|   check that a heater is within a temperature range.
 | |
| 
 | |
| * `get_clock` : This command causes the micro-controller to generate a
 | |
|   "clock" response message. The host sends this command once a second
 | |
|   to obtain the value of the micro-controller clock and to estimate
 | |
|   the drift between host and micro-controller clocks. It enables the
 | |
|   host to accurately estimate the micro-controller clock.
 | |
| 
 | |
| ### Stepper commands
 | |
| 
 | |
| * `queue_step oid=%c interval=%u count=%hu add=%hi` : This command
 | |
|   schedules 'count' number of steps for the given stepper, with
 | |
|   'interval' number of clock ticks between each step. The first step
 | |
|   will be 'interval' number of clock ticks since the last scheduled
 | |
|   step for the given stepper. If 'add' is non-zero then the interval
 | |
|   will be adjusted by 'add' amount after each step. This command
 | |
|   appends the given interval/count/add sequence to a per-stepper
 | |
|   queue. There may be hundreds of these sequences queued during normal
 | |
|   operation. New sequence are appended to the end of the queue and as
 | |
|   each sequence completes its 'count' number of steps it is popped
 | |
|   from the front of the queue. This system allows the micro-controller
 | |
|   to queue potentially hundreds of thousands of steps - all with
 | |
|   reliable and predictable schedule times.
 | |
| 
 | |
| * `set_next_step_dir oid=%c dir=%c` : This command specifies the value
 | |
|   of the dir_pin that the next queue_step command will use.
 | |
| 
 | |
| * `reset_step_clock oid=%c clock=%u` : Normally, step timing is
 | |
|   relative to the last step for a given stepper. This command resets
 | |
|   the clock so that the next step is relative to the supplied 'clock'
 | |
|   time. The host usually only sends this command at the start of a
 | |
|   print.
 | |
| 
 | |
| * `stepper_get_position oid=%c` : This command causes the
 | |
|   micro-controller to generate a "stepper_position" response message
 | |
|   with the stepper's current position. The position is the total
 | |
|   number of steps generated with dir=1 minus the total number of steps
 | |
|   generated with dir=0.
 | |
| 
 | |
| * `endstop_home oid=%c clock=%u sample_ticks=%u sample_count=%c
 | |
|   rest_ticks=%u pin_value=%c` : This command is used during stepper
 | |
|   "homing" operations. To use this command a 'config_endstop' command
 | |
|   with the same 'oid' parameter must have been issued during
 | |
|   micro-controller configuration. When this command is invoked, the
 | |
|   micro-controller will sample the endstop pin every 'rest_ticks'
 | |
|   clock ticks and check if it has a value equal to 'pin_value'. If the
 | |
|   value matches (and it continues to match for 'sample_count'
 | |
|   additional samples spread 'sample_ticks' apart) then the movement
 | |
|   queue for the associated stepper will be cleared and the stepper
 | |
|   will come to an immediate halt. The host uses this command to
 | |
|   implement homing - the host instructs the endstop to sample for the
 | |
|   endstop trigger and then it issues a series of queue_step commands
 | |
|   to move a stepper towards the endstop. Once the stepper hits the
 | |
|   endstop, the trigger will be detected, the movement halted, and the
 | |
|   host notified.
 | |
| 
 | |
| ### Move queue
 | |
| 
 | |
| Each queue_step command utilizes an entry in the micro-controller
 | |
| "move queue". This queue is allocated when it receives the
 | |
| "finalize_config" command, and it reports the number of available
 | |
| queue entries in "config" response messages.
 | |
| 
 | |
| It is the responsibility of the host to ensure that there is available
 | |
| space in the queue before sending a queue_step command. The host does
 | |
| this by calculating when each queue_step command completes and
 | |
| scheduling new queue_step commands accordingly.
 | |
| 
 | |
| ### SPI Commands
 | |
| 
 | |
| * `spi_transfer oid=%c data=%*s` : This command causes the
 | |
|   micro-controller to send 'data' to the spi device specified by 'oid'
 | |
|   and it generates a "spi_transfer_response" response message with the
 | |
|   data returned during the transmission.
 | |
| 
 | |
| * `spi_send oid=%c data=%*s` : This command is similar to
 | |
|   "spi_transfer", but it does not generate a "spi_transfer_response"
 | |
|   message.
 |