klipper/docs/Firmware_Commands.md

289 lines
15 KiB
Markdown

This document provides high-level information on common firmware
commands. It is not an authoritative reference for these commands, nor
is it an exclusive list of all available firmware commands.
This document may be useful for users needing to configure a set of
hardware actions that their printer may require at startup (via the
"custom" field in the printer config file), and it may be useful for
developers wishing to obtain a high-level feel for available firmware
commands.
See the [protocol](Protocol.md) document for more information on the
format of commands and their low-level 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.
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 other firmware commands,
these commands run as soon as they are received by the firmware and
they do not require any particular setup.
These commands are most useful in the "custom" block of the "mcu"
section of the printer configuration file. This feature is typically
used to configure the initial settings of LEDs, to configure
micro-stepping pins, to configure a digipot, etc.
Several of these commands will take a "pin=%u" parameter. The
low-level firmware uses integer encodings of the hardware pin numbers,
but to make things more readable the host will translate human
readable pin names (eg, "PA3") to their equivalent integer
encodings. By convention, any parameter named "pin" or that has a
"_pin" suffix will use pin name translation by the host. Similarly,
several commands take time parameters specified in clock ticks. One
can specify a value for these parameters in seconds using the
"TICKS()" macro - for example "cycle_ticks=TICKS(0.001)" would result
in "cycle_ticks=16000" on a micro-controller with a 16Mhz clock.
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=%c : 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.
* send_spi_message pin=%u msg=%*s : This command can be used to
transmit messages to a serial-peripheral-interface (SPI) component
connected to the micro-controller. It has been used to configure the
startup settings of AD5206 digipots. The 'pin' parameter specifies
the chip select line to use during the transmission. The 'msg'
indicates the binary message to transmit to the given chip.
Firmware configuration
======================
Most commands in the firmware require an initial setup before they can
be successfully invoked. This section provides a high-level overview
of the micro-controller 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 firmware it always starts by
obtaining the firmware's data dictionary (see [protocol](Protocol.md)
for more information). After the data dictionary is obtained the host
will check if the firmware is in a "configured" state and configure it
if not. Configuration involves the following phases:
* get_config : The host starts by checking if the firmware is already
configured. The firmware responds to this command with a "config"
response message. At micro-controller power-on the firmware always
starts in an unconfigured state. It remains in this state until the
host completes the configuration processes (by issuing a
finalize_config command). If the firmware is already configured (and
is configured with the desired settings) from a previous
host/firmware session 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
firmware 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
firmware so that the firmware may allocate sufficient memory to
store a mapping from oid to internal firmware object.
* config_XXX oid=%c ... : By convention any command starting with the
"config_" prefix creates a new firmware 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 firmware 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
firmware from an unconfigured state to a configured state. The crc
parameter passed to the firmware is stored in the firmware and
provided back to the host in "config" response messages. By
convention, the host takes a 32bit CRC of the firmware configuration
it will request and at the start of subsequent host/firmware
communication sessions it checks that the CRC stored in the firmware
exactly matches its desired CRC. If the CRC does not match then the
host knows the firmware has not been configured in the state desired
by the host.
Common firmware objects
-----------------------
This section lists some commonly used config commands.
* config_digital_out oid=%c pin=%u default_value=%c max_duration=%u :
This command creates an internal firmware object for the given GPIO
'pin'. The pin will be configured in digital output mode and set to
an initial value as specified by 'default_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
schedule_digital_out command described below). Should the firmware
go into shutdown mode then all configured digital_out objects will
be set back to their default values. 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 set the heater to a value of one and then go
off-line.
* config_pwm_out oid=%c pin=%u cycle_ticks=%u default_value=%c
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_soft_pwm_out oid=%c pin=%u cycle_ticks=%u default_value=%c
max_duration=%u : This command creates an internal firmware object
for software implemented PWM. Unlike hardware pwm pins, a software
pwm object does not require any special hardware support (other than
the ability to configure the pin as a digital output GPIO). Because
the output switching is implemented in the software of the firmware,
it is recommended that the cycle_ticks parameter correspond to a
time of 10ms or greater. 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 min_stop_interval=%u
invert_step=%c : 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 'min_stop_interval' implements a safety
feature - it is checked when the firmware finishes all moves for a
stepper - if it is non-zero it specifies the minimum number of clock
ticks since the last step. It is used as a check on the maximum
stepper velocity that a stepper may have before stopping.
* config_end_stop 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
end_stop_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 end_stop_home below).
Common commands
===============
This section lists some commonly used run-time commands. It is likely
only of interest to developers looking to gain insight into Klippy.
* schedule_digital_out oid=%c clock=%u value=%c : 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 firmware
configuration.
* schedule_pwm_out oid=%c clock=%u value=%c : Schedules a change to a
hardware PWM output pin. See the 'schedule_digital_out' and
'config_pwm_out' commands for more info.
* schedule_soft_pwm_out oid=%c clock=%u value=%c : Schedules a change
to a software PWM output pin. See the 'schedule_digital_out' and
'config_soft_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 firmware 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 firmware 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_status : This command causes the firmware to generate a "status"
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 firmware 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 firmware 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.
* end_stop_home oid=%c clock=%u rest_ticks=%u pin_value=%c : This
command is used during stepper "homing" operations. To use this
command a 'config_end_stop' command with the same 'oid' parameter
must have been issued during firmware configuration. When invoked,
the firmware 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 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 the stepper to move it 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 firmware "move
queue". The firmware allocates this queue 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.