From a27e82aef365078ef814b897e404f942a71c1333 Mon Sep 17 00:00:00 2001 From: Kevin O'Connor <kevin@koconnor.net> Date: Fri, 24 Aug 2018 21:36:37 -0400 Subject: [PATCH] docs: Add a section to the FAQ on translating Marlin pin numbers Signed-off-by: Kevin O'Connor <kevin@koconnor.net> --- docs/FAQ.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index b9c1cd238..16728e7a2 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -14,7 +14,8 @@ Frequently asked questions 11. [My TMC motor driver turns off in the middle of a print](#my-tmc-motor-driver-turns-off-in-the-middle-of-a-print) 12. [When I set "restart_method=command" my AVR device just hangs on a restart](#when-i-set-restart_methodcommand-my-avr-device-just-hangs-on-a-restart) 13. [Will the heaters be left on if the Raspberry Pi crashes?](#will-the-heaters-be-left-on-if-the-raspberry-pi-crashes) -14. [How do I upgrade to the latest software?](#how-do-i-upgrade-to-the-latest-software) +14. [How do I convert a Marlin pin number to a Klipper pin name?](#how-do-i-convert-a-marlin-pin-number-to-a-klipper-pin-name) +15. [How do I upgrade to the latest software?](#how-do-i-upgrade-to-the-latest-software) ### How can I donate to the project? @@ -263,6 +264,54 @@ heaters and temperature sensors are functioning correctly. See the [example-extras.cfg](../config/example-extras.cfg) for further details. +### How do I convert a Marlin pin number to a Klipper pin name? + +Short answer: There isn't an easy way to do that reliably. In some +cases one can use Klipper's `pin_map: arduino` feature. Otherwise, for +"digital" pins, one method is to search for the requested pin in +Marlin's fastio header files. The Atmega2560 and Atmega1280 chips use +[fastio_1280.h](https://github.com/MarlinFirmware/Marlin/blob/1.1.9/Marlin/fastio_1280.h), +while the Atmega644p and Atmega1284p chips use +[fastio_644.h](https://github.com/MarlinFirmware/Marlin/blob/1.1.9/Marlin/fastio_644.h). +For example, if you are looking to translate Marlin's digital pin +number 23 on an atmega2560 then one could find the following line in +Marlin's fastio_1280.h file: +``` +#define DIO23_PIN PINA1 +``` +The `DIO23` indicates the line is for Marlin's pin 23 and the `PINA1` +indicates the pin uses the hardware name of `PA1`. Klipper uses the +hardware names (eg, `PA1`). + +Long answer: Klipper uses the standard pin names defined by the +micro-controller. On the Atmega chips these hardware pins have names +like `PA4`, `PC7`, or `PD2`. + +Long ago, the Arduino project decided to avoid using the standard +hardware names in favor of pin names based on incrementing numbers - +these Arduino names generally look like `D23` or `A14`. This was an +unfortunate choice that has lead to great deal of confusion. In +particular the Arduino pin numbers frequently don't translate to the +same hardware names. For example, `D21` is `PD0` on one common Arduino +board, but is `PC7` on another common Arduino board. + +In order to support 3d printers based on real Arduino boards, Klipper +supports the Arduino pin aliases. This feature is enabled by adding +`pin_map: arduino` to the [mcu] section of the config file. When these +aliases are enabled, Klipper understands pin names that start with the +prefix "ar" (eg, Arduino pin `D23` is Klipper alias `ar23`) and the +prefix "analog" (eg, Arduino pin `A14` is Klipper alias `analog14`). +Klipper does not use the Arduino names directly because we feel a name +like D7 is too easily confused with the hardware name PD7. + +Marlin primarily follows the Arduino pin numbering scheme. However, +Marlin supports a few chips that Arduino does not support and in some +cases it supports pins that Arduino boards do not expose. In these +cases, Marlin chose their own pin numbering scheme. Klipper does not +support these custom pin numbers - see the "short answer" section +above for information on translating these pin numbers to their +standard hardware names. + ### How do I upgrade to the latest software? The general way to upgrade is to ssh into the Raspberry Pi and run: