klipper/docs/MCU_Commands.md

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 schedule_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_soft_pwm_out oid=%c pin=%u value=%c
  default_value=%c max_duration=%u` : This command creates an internal
  micro-controller 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).  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 micro-controller 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_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.

* `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 micro-controller
  configuration.

* `schedule_pwm_out oid=%c clock=%u value=%hu` : 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 on_ticks=%u off_ticks=%u` : Schedules a
  change to a software PWM output pin. The parameters 'on_ticks' and 'off_ticks'
  define for how many ticks the pin will be on and off, respectively.
  Because the output switching is implemented in the micro-controller software,
  it is recommended that the sum of on_ticks and off_ticks parameters
  corresponds to a time of 10ms or greater. 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 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.