docs: Avoid using "firmware" in the documentation

The term "firmware" is ambiguous - it could refer to the entire
project (host and micro-controller software) or to just the
micro-controller software.  Avoid the term in the documentation.

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>

1 files changed, 294 insertions, 0 deletions

diff --git a/docs/MCU_Commands.md b/docs/MCU_Commands.md
new file mode 100644
index 00000000..c1544d2a
--- /dev/null
+++ b/docs/MCU_Commands.md
@@ -0,0 +1,294 @@
+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 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 low-level 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".
+
+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.
+
+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 micro-controller software 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.
+
+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 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
+  '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 micro-controller software 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
+  enable the heater 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 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). Because the output switching is implemented in the
+  micro-controller software, 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 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_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 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=%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 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_status` : This command causes the micro-controller 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 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.
+
+* `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 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 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.