diff options
Diffstat (limited to 'docs/Firmware_Commands.md')
| -rw-r--r-- | docs/Firmware_Commands.md | 290 |
1 files changed, 0 insertions, 290 deletions
diff --git a/docs/Firmware_Commands.md b/docs/Firmware_Commands.md deleted file mode 100644 index 6678b3c6..00000000 --- a/docs/Firmware_Commands.md +++ /dev/null @@ -1,290 +0,0 @@ -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. 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 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. |