Reworking example config files to have pin aliases at top of file

A year or so ago I put together an experimental branch with some example configs reorganized so that there is a “board_pins” section at the top of the file. This topic is for discussing that potential change to the Klipper example configs.

For example - the top of the generic-rambo.cfg file:

# Add human-readable names for pins on "rambo" style boards
[board_pins rambo]
aliases:
    # Stepper motor pins
    X_STEP=PC0, X_DIR=PL1, X_ENABLE=PA7,
    Y_STEP=PC1, Y_DIR=PL0, Y_ENABLE=PA6,
    Z_STEP=PC2, Z_DIR=PL2, Z_ENABLE=PA5,
    E_STEP=PC3, E_DIR=PL6, E_ENABLE=PA4,
    E1_STEP=PC4, E1_DIR=PL7, E1_ENABLE=PA3,
    # Endstop pins
    X_MIN=PB6, X_MAX=PA2, Y_MIN=PB5, Y_MAX=PA1, Z_MIN=PB4, Z_MAX=PC7,
    # Heater and fan pins
    E_HEATER=PH6, E_THERMISTOR=PF0,
    E1_HEATER=PH4, E1_THERMISTOR=PF1,
    BED_HEATER=PE5, BED_THERMISTOR=PF2,
    RAMBO_FAN0=PH5, RAMBO_FAN1=PH3,
    # Rambo board specific pins
    RAMBO_LED=PB7,
    RAMBO_DIGIPOT_CS=PD7,
    RAMBO_X_MS1=PG1, RAMBO_X_MS2=PG0,
    RAMBO_Y_MS1=PK7, RAMBO_Y_MS2=PG2,
    RAMBO_Z_MS1=PK6, RAMBO_Z_MS2=PK5,
    RAMBO_E_MS1=PK3, RAMBO_E_MS2=PK4,
    RAMBO_E1_MS1=PK1, RAMBO_E1_MS2=PK2,
    # EXP1 header pins (see sample-lcd.cfg file for common LCD displays)
    EXP1_1=PE6, EXP1_3=PG3, EXP1_5=PJ2, EXP1_7=PJ7, EXP1_9=<GND>,
    EXP1_2=PE2, EXP1_4=PG4, EXP1_6=PJ3, EXP1_8=PJ4, EXP1_10=<5V>,
    # EXP2 header
    EXP2_1=PB3, EXP2_3=PJ5, EXP2_5=PJ6, EXP2_7=PD4, EXP2_9=<GND>,
    EXP2_2=PB1, EXP2_4=PB0, EXP2_6=PB2, EXP2_8=PE7, EXP2_10=PH2
    # Pins EXP2_1, EXP2_6, EXP2_2 are also MISO, MOSI, SCK of bus "spi"

The code with this change is at https://github.com/KevinOConnor/klipper-dev/tree/work-pins-20201222.

I do think doing this could improve the example configs. However, it didn’t seem that there was much of a preference one way or another on this change, so it has never moved forward. The advantage of defining the aliases is that it can make the pin assignments later in the config a little more transparent to users and it can make it a little easier to define all the pins in one area when translating a schematic. A possible disadvantage is that it introduces some complexity and may make the config less transparent.

There was a previous discussion on this topic at https://github.com/Klipper3d/klipper/pull/3671.

-Kevin

Previous post was far too much of a rant and has been deleted.

If there’s no appetite for using the aliases they shouldn’t be a requirement.

I think it would be really helpful to document all the available pins in the config files, and where they correspond to dedicated hardware plugs like the BL-touch and runout “plug and play” sockets on a board there should be a commented out section that defines the pins. This is then enough to get a feature up and running without having to look for “hidden” knowledge like pinout diagrams or plunder the marlin source.

I’m prepared to do this for popular boards, likely in response to support requests on r/klippers if there is an appetite for this.

I made this PR earlier, matching the style of the 4.2.10 board config in the master branch Add dedicated hardware pins on generic-bigtreetech-skr-mini-e3-v2.cfg by strayr · Pull Request #5119 · Klipper3d/klipper · GitHub

Personally I would vote for a minimal invasive approach:

  • Aliases only for unused / generic / multipurpose pins
  • Adding optional pins / additional periphery as commented example
Example for BTT SKR1.4
# This file contains common pin mappings for the BIGTREETECH SKR V1.4
# board. To use this config, the firmware should be compiled for the
# LPC1768 or LPC1769(Turbo).

# See docs/Config_Reference.md for a description of parameters.

[stepper_x]
step_pin: P2.2
dir_pin: P2.6
enable_pin: !P2.1
microsteps: 16
rotation_distance: 40
endstop_pin: !P1.29
position_endstop: 0
position_max: 235
homing_speed: 50

[stepper_y]
step_pin: P0.19
dir_pin: P0.20
enable_pin: !P2.8
microsteps: 16
rotation_distance: 40
endstop_pin: !P1.28
position_endstop: 0
position_max: 235
homing_speed: 50

[stepper_z]
step_pin: P0.22
dir_pin: !P2.11
enable_pin: !P0.21
microsteps: 16
rotation_distance: 8
endstop_pin: !P1.27
position_endstop: 0.0
position_max: 300

[extruder]
step_pin: P2.13
dir_pin: !P0.11
enable_pin: !P2.12
microsteps: 16
rotation_distance: 33.500
nozzle_diameter: 0.400
filament_diameter: 1.750
heater_pin: P2.7
sensor_type: EPCOS 100K B57560G104F
sensor_pin: P0.24
control: pid
pid_Kp: 22.2
pid_Ki: 1.08
pid_Kd: 114
min_temp: 0
max_temp: 260

#[extruder1]
#step_pin: P1.15
#dir_pin: P1.14
#enable_pin: !P1.16
#heater_pin: P2.4
#sensor_pin: P0.23
#...

[heater_bed]
heater_pin: P2.5
sensor_type: EPCOS 100K B57560G104F
sensor_pin: P0.25
control: pid
pid_Kp: 54.027
pid_Ki: 0.770
pid_Kd: 948.182
min_temp: 0
max_temp: 130

[fan]
pin: P2.3

[mcu]
serial: /dev/serial/by-id/usb-Klipper_Klipper_firmware_12345-if00

[printer]
kinematics: cartesian
max_velocity: 400
max_accel: 500
max_z_velocity: 10
max_z_accel: 100


########################################
# TMC2208 configuration
########################################

#[tmc2208 stepper_x]
#uart_pin: P1.10
#run_current: 0.800
#stealthchop_threshold: 999999
#
#[tmc2208 stepper_y]
#uart_pin: P1.9
#run_current: 0.800
#stealthchop_threshold: 999999
#
#[tmc2208 stepper_z]
#uart_pin: P1.8
#run_current: 0.650
#stealthchop_threshold: 999999
#
#[tmc2208 extruder]
#uart_pin: P1.4
#run_current: 0.800
#stealthchop_threshold: 999999
#
#[tmc2208 extruder1]
#uart_pin: P1.1
#run_current: 0.800
#stealthchop_threshold: 999999


########################################
# TMC2130 configuration
########################################

#[tmc2130 stepper_x]
#cs_pin: P1.10
#spi_software_miso_pin: P0.5
#spi_software_mosi_pin: P1.17
#spi_software_sclk_pin: P0.4
#run_current: 0.800
#stealthchop_threshold: 999999
#diag1_pin: P1.29

#[tmc2130 stepper_y]
#cs_pin: P1.9
#spi_software_miso_pin: P0.5
#spi_software_mosi_pin: P1.17
#spi_software_sclk_pin: P0.4
#run_current: 0.800
#stealthchop_threshold: 999999
#diag1_pin: P1.28

#[tmc2130 stepper_z]
#cs_pin: P1.8
#spi_software_miso_pin: P0.5
#spi_software_mosi_pin: P1.17
#spi_software_sclk_pin: P0.4
#run_current: 0.650
#stealthchop_threshold: 999999
#diag1_pin: P1.27

#[tmc2130 extruder]
#cs_pin: P1.4
#spi_software_miso_pin: P0.5
#spi_software_mosi_pin: P1.17
#spi_software_sclk_pin: P0.4
#run_current: 0.800
#stealthchop_threshold: 999999
#diag1_pin: P1.26

#[tmc2130 extruder1]
#cs_pin: P1.1
#spi_software_miso_pin: P0.5
#spi_software_mosi_pin: P1.17
#spi_software_sclk_pin: P0.4
#run_current: 0.800
#stealthchop_threshold: 999999
#diag1_pin: P1.25


########################################
# EXP1 / EXP2 (display) pins
########################################

[board_pins]
aliases:
    # EXP1 header
    EXP1_1=P1.30, EXP1_3=P1.18, EXP1_5=P1.20, EXP1_7=P1.22, EXP1_9=<GND>,
    EXP1_2=P0.28, EXP1_4=P1.19, EXP1_6=P1.21, EXP1_8=P1.23, EXP1_10=<5V>,
    # EXP2 header
    EXP2_1=P0.17, EXP2_3=P3.26, EXP2_5=P3.25, EXP2_7=P1.31, EXP2_9=<GND>,
    EXP2_2=P0.15, EXP2_4=P0.16, EXP2_6=P0.18, EXP2_8=<RST>, EXP2_10=<NC>
    # Pins EXP2_1, EXP2_6, EXP2_2 are also MISO, MOSI, SCK of bus "ssp0"

# See the sample-lcd.cfg file for definitions of common LCD displays.

########################################
# Optional pins / periphery
########################################

# BL-touch
#[bltouch]
#sensor_pin: ^P0.10
#control_pin: P2.0

# Neopixel LED support
# [neopixel led_neopixel]
# pin: P1.24

# Unused or generic pins
[board_pins]
aliases:
    # Switch Pins for filament, runout, power detection etc.
    SwitchPin0=P1.0, SwitchPin1=P1.25, SwitchPin2=P1.26

Whereas the section

# Unused or generic pins
[board_pins]
aliases:
    # Switch Pins for filament, runout, power detection etc.
    SwitchPin0=P1.0, SwitchPin1=P1.25, SwitchPin2=P1.26

already is problematic because the user will have to consult the pin document / schematic anyway to identify their location.

There doesn’t seem much enthusiasm for anything more than minimal changes.

Aliases work well when there is a set of pins on the board with clear labels, the bigtreetech example i’ve been working with has silkscreen labels on the accessory ports.

My primary goal is to get enough information into the configs so that BLTouch and runout additions don’t generate difficult support requests and repeated effort when there’s clearly labeled ports on the controller board, well publicised instructions for the hardware connections and marlin firmware builds from the manufacturer or third parties that expect the accessory hardware in this location.

Generally, I like and support this idea.
In order to avoid chaotic board definition it needs some agreed and documented conventions:

Extend:

  • To which extend shall the pins be added?
  • Only bltouch and potentially runout switch?
  • Neopixel?
  • Big boards like Fysetc S6 and above (3 or more controlled fans, 4+ temperature ports etc)
  • Example BTT SKR1.4: It has 3 switch pins. Which one is the run-out? Always the first?
  • etc

Naming convention:

  • Defined and harmonized across all boards? → Something I’d prefer
  • According to the (maybe existing) silkscreen? → The slik-screen on my BTT boards is hardly readable

Personally, I do not like the idea of adding aliases for each and every pin. For me this just adds a lot of clutter to the config without any real added value: Nobody cares if a stepper UART pin is defined as uart_pin: P1.10 or as uart_pin: StepperX.

I propose:

  • To which extend shall the pins be added?

Ideally all physical sockets on the board that aren’t used by the base config and are available for use should be documented

  • Only bltouch and potentially runout switch?

If the board has labelled sockets for accessories, they shoud be documented

  • Neopixel?

Some skr boards have a dedicated neopixel socket with power and a control pin, maybe others do to, I don’t know. Likely more popular than ever amongs klipper userbase as voron’s new toolhead has built in neopixel mounts.

  • Big boards like Fysetc S6 and above (3 or more controlled fans, 4+ temperature ports etc)

Yes, list these items, users buy big big boards in order to use this functionality.

  • Example BTT SKR1.4: It has 3 switch pins. Which one is the run-out? Always the first?

Don’t confiugure switch pins as named accessories unless they are suggested by the board silkscreen, just document that there are available switches.

Just my 2 cents, but I’d lean towards adding aliases for all pins defined in the board schematic. (As is done in the example cited above: klipper-dev/generic-rambo.cfg at work-pins-20201222 · KevinOConnor/klipper-dev · GitHub )

One reason I think defining the base pins is useful is that I think it is easier to convert the board pin documentation (eg, https://raw.githubusercontent.com/bigtreetech/BIGTREETECH-SKR-mini-E3/master/hardware/BTT%20SKR%20MINI%20E3%20V3.0/Hardware/BTT%20E3%20SKR%20MINI%20V3.0_PIN.pdf ) into an alias block and then be able to put that document away and work on the rest of the config. Otherwise, having to go back and forth between schematics and config is painful.

So, I agree that uart_pin: P1.10 is no more or less helpful than uart_pin: X_TMC_UART, but if you don’t know any of X_STEP, X_DIR, X_ENABLE, X_TMC_UART, Y_STEP, Y_DIR, Y_ENABLE, Y_TMC_UART, etc. then it is a pain going back-and-forth to map or audit them.

In my opinion, board_pins is useful for documenting the names on the board, not the functions they happen to be used for.

So, I’d say if the board has a socket labelled “neopixel” then it may be useful to have NEOPIXEL_XXX aliases.

This is a tough one. I’d probably lean towards using standardized names where there is a well established standard - for example, X_STEP, X_DIR, X_ENABLE, EXP1_1, etc. . However, where there is no well established standard then using the board label (or label in the schematic) would seem appropriate.

Although this is true, there are often labels in the board’s documentation.

Again, just my 2 cents. I’m not set on anything.
-Kevin

This definitively is an advantage. For the first time creation of the mapping yes, but the “clutter” (not meant harsh) will remain there for ever. Not my personal preference, but equally no strong feelings as well. Additional disadvantage is more work in converting the existing boards.

Just to get working thinking correct:

  • A dedicated hardware / function pin(s) will be named according to the function, e.g. NEOPIXEL_XXX
  • General pin(s) , e.g. switch type pins, that could be used for endstops, run-out sensors, filament-sensors, etc, will get a generic mapping like SWITCH_1, SWITCH_2, etc

Goes hand in hand with the paragraph just above. We would need to define, what is “well established” and what will be according to the silkscreen / documentation. Example for this are these BTT SKR 1.4 switch pins. Documentation calls them E0DET, E1DET, PWRDET. Function-wise they are just digital-in pins.

This is what I was trying to coney two posts above: The naming itself usually makes no sense without the documentation.
This means from a user perspective it will not allow to simply “connect anything” there without knowing what this pin is, e.g. WRT to pull-ups etc.

Overall, I’m willing to contribute to this with the boards I’m using (SKR1.3, SKR1.4, Fysetc S6, soon a Fysetc Spider)

I agree there is a trade-off. Some simplification in other parts of the config at the cost of additional complexity to define the mappings.

Well, I’m not really sure it matters if one example config uses an alias E0DET and another config uses E0_STOP. As I mentioned in another forum, I think we should try to keep the configs similar; but I don’t think we need to take that to an extreme.

FWIW, if I was doing the mapping for those pins on the SKR v1.4 ( https://raw.githubusercontent.com/bigtreetech/BIGTREETECH-SKR-V1.3/master/BTT%20SKR%20V1.4/Hardware/BTT%20SKR%20V1.4PIN.pdf ) I’d probably define “standardized” aliases for X_STOP, Y_STOP, Z_STOP, E0_STOP, E1_STOP, and use a board specific alias PWRDET. That is, endstops are mostly a standard (so use a “standardized” _STOP suffix in this example) while PWRDET isn’t particularly standardized and can use the board’s label. YMMV.

This is a very good point - if the user has to lookup the documentation to find what port is PWRDET then what difference does it make if they copy PWRDET or P1.0 from that document?

The reason I see the value in the board aliases is that many (probably most) board schematics are terrible. The SRK 1.4 documents are better than average, but they are still not great. Consider the TFT port - there are two valid general-purpose pins on that port (defined in the documentation as RX0 and TX0), but it takes a lot of low-level knowledge to find the pin names for them (P0.3 and P0.2). Worse, it takes a lot of low-level knowledge to even know those pins can be mapped while the other seemingly similar names (eg, RST and NPWR) can’t be mapped.

The Duet boards are an example of truly horrific documentation. For example consider the Duet2 Maestro’s pin document: https://raw.githubusercontent.com/Duet3D/Duet-2-Hardware/master/Duet2/Duet2Maestro_v1.0/Duet2Maestro_Wiring_V1.0_drawing_v1.3.svg . Sure, it shows where every plug is - but try to find the corresponding micro-controller pin names and it’s nearly impossible. If you’re curious, the next step is the schematic ( https://raw.githubusercontent.com/Duet3D/Duet-2-Hardware/master/Duet2/Duet2Maestro_v1.0/Duet2Maestro_Schematic_v1.0.pdf ), but unfortunately that doesn’t provide the necessary information either. To get to the pins, one has to cross-index the pin document, the schematic, and the micro-controller documentation ( https://ww1.microchip.com/downloads/aemDocuments/documents/OTH/ProductDocuments/DataSheets/Atmel-11100-32-bitCortex-M4-Microcontroller-SAM4S_Datasheet.pdf ). This work is realistically outside the reach of most users (and it’s incredibly time consuming and error prone even for experts).

I agree that there is other pertinent information besides the pin names that a board defines - for example, pullup resistors, tmc2209 uart addresses, sense resistors, etc. . I suppose free form text comments could be used to indicate this information (where known and relevant).

Again, just my 2 cents. I’m not set on anything.
-Kevin

1 Like

This is a very good point - if the user has to lookup the documentation to find what port is PWRDET then what difference does it make if they copy PWRDET or P1.0 from that document?

There’s quite often “friendly” documentation out there for budget printers, and asking “do you have the pin out diagram for the board” gets just something like this linked in Creality Melzi Board Connections (CR-10/Ender 3/Ender 5) - TH3D Studio LLC or really helpful wiki pages like this that don’t have the pinouts GT2560A/GT2560A+ - Geeetech Wiki

It’s important to remember that klipper contributors are likely to have a level of technical knowledge that newcomers to klipper are less likely to have.

I’ve been using the SKR mini e3 v2 as an example becasue it has lots of accessory ports that are configured to fit aftermarket hardware, I don’t think klipper supports the power loss protection daughterboard, but the ports are there, but neopixel, bltouch and runout are all labelled in the docs.

Where there’s instructions for other firmware out there for addons, especially from the manufacturer, I think it’s important that klipper behaves in a helpful way, maybe not with complete configurations, but in having enough information to work out how to get additional hardware to work we add a lot of value and user simplify support.

My “new to klipper” experience was setting up a prusa clone with a GT2560A board. It’s not exactly new, it was on the dirt cheap donor printer. Repurposing the second extruder stepper driver was pretty easy as all the pins were there, but adding a bed probe, well the only docs on the extra endstops and the servo pin I could find was the pins header files in the marlin source. No big for me as I was already elbow deep in the build systemtrying to solve an issue with another board, but I think one of the draws klipper has is in how easy it is to configure it for specific hardware, whereas it’s quite painful getting marlin right on a very custom printer, particularly if you want all the luxuary functionality klipper does with user macros.

I don’t think we should be asking users to go on a deep dive in manufacturer’s specs just to get the Z-max endstop working or add a bltouch, but If we’re adding or maintaining configs, we already have that knowledge or know where to get it.

And havingcome back to the discorse, I found this GT2560 A+ BLTouch pin is PB5 wherein my adventures with the GT2560A was answered with a support request for a CR10 that nobody answered. And this is exactly what i’m trying to tackle.

This is what I have been using on my Spider

[board_pins spider]
aliases:
    # Stepper motor pins
    X_STEP=PE11, X_DIR=PE10, X_ENABLE=PE9,
	Y_STEP=PD8, Y_DIR=PB12, Y_ENABLE=PD9,
	Z_STEP=PD14, Z_DIR=PD13, Z_ENABLE=PD15,
	E0_STEP=PD5, E0_DIR=PD6, E0_ENABLE=PD4,
	E1_STEP=PE6, E1_DIR=PC13, E1_ENABLE=PE5,
	E2_STEP=PE2, E2_DIR=PE4, E2_ENABLE=PE3,
	E3_STEP=PD12, E3_DIR=PC4, E3_ENABLE=PE8,
	E4_STEP=PE1, E4_DIR=PE0, E4_ENABLE=PC5,
	# Endstop pins
	X_MIN=PB14, X_MAX=PA1,
	Y_MIN=PB13, Y_MAX=PA2,
	Z_MIN=PA0, Z_MAX=PA3,
	# UART pins
	X_UART=PE7, Y_UART=PE15, Z_UART=PD10,
	E0_UART=PD7, E1_UART=PC14, E2_UART=PC15,
	E3_UART=PA15, E4_UART=PD11,
    # Heater and fan pins
	E_HEATER=PB15, E_THERMISTOR=PC0,
	E1_HEATER=PC8, E1_THERMISTOR=PC1,
	E2_HEATER=PB3, E2_THERMISTOR=PC2,
	BED_HEATER=PB4, BED_THERMISTOR=PC3,
	FAN0=PB0, FAN1=PB1, FAN2=PB2,
    # Led pins 
    LED-R=PB6, LED-G=PB5, LED-B=PB7,
	# EXP1 header pins (see sample-lcd.cfg file for common LCD displays)
    EXP1_1=PC9, EXP1_3=PC11, EXP1_5=PC10, EXP1_7=PD0, EXP1_9=<GND>,
    EXP1_2=PA8, EXP1_4=PD2, EXP1_6=PC12, EXP1_8=PD1, EXP1_10=<5V>,
    # EXP2 header
    EXP2_1=PA6, EXP2_3=PC6, EXP2_5=PC7, EXP2_7=PB10, EXP2_9=<GND>,
    EXP2_2=PA5, EXP2_4=PA4, EXP2_6=PA7, EXP2_8=<RST>, EXP2_10=<5V>
1 Like

To get this going and to have a discussion basis, following proposal:

General specification:

  • All available pins shall be mapped with matching aliases
  • If the board can use SPI and UART TMC stepper driver, then commented examples for both options shall be provided
  • Common / standard pins shall follow the below naming scheme
  • Board specific pins, which are not among the listed standard pins, shall be named according to the documentation, silk-screen or function
  • If only a single pin exists, do not add a number, if multiple pins for a function are existing (e.g. E0, E1 etc.) start numbering with 0
  • Additional relevant information shall be added as comment (if applicable), e.g.
    • Pin is PWM capable
    • Pin has pull-up / pull-down
    • Pin is also MISO, MOSI, CLK of SPI Bus x
  • If the board has multiple hardware SPI buses this information shall be added to the header information

Common / standard pins

# Stepper Motor Pins
# If more then one Z or E then start at Z0 / E0
STEP_(X/Y/Z/Zn/E/En)
DIR_(X/Y/Z/Zn/E/En)
ENABLE_(X/Y/Z/Zn/E/En)

# Stepper Motor UART Pins
# If more then one Z or E then start at Z0 / E0
UART_(X/Y/Z/Zn/E/En)

# Stepper Motor SPI
# If more then one Z or E then start at Z0 / E0
CS_(X/Y/Z/Zn/E/En)
SOFT_MISO
SOFT_MOSI
SOFT_CLK
DIAG_(X/Y/Z/Zn) # Only if different from the respective endstop pins, otherwise use endstop pins

# Endstop Pins
# If more then one Z then start at Z0
MIN_STOP_(X/Y/Z/Zn)
MAX_STOP_(X/Y/Z/Zn)

# Thermistor pins (E or general purpose)
# If more then one Thermistor  then start at 0
THERMISTOR
THERMISTORn

# Thermistor pins (Bed)
THERMISTOR_BED
THERMISTOR_BEDn

# Heater pins  (E or general purpose)
# If more then one Heater then start at 0
HEATER
HEATERn

# Heater pins  (Bed)
# If more then one Bed Heater then start at 0
HEATER_BED
HEATER_BEDn

# Fan Pins
# If more then one fan start with 0
FAN
FANn

# EXP1
EXP1_[1-10]

# EXP2
EXP2_[1-10]

# Z-Probes
Z_PROBE_CONTROL
Z_PROBE_SERVO
1 Like

Thanks.

FWIW, I’d prefer aliases with the device first and then the sub-function as a suffix - X_STEP and not STEP_X.

I’m also not sure we can realistically specify the device names or if they start with zero or not. For example, the duet3 doesn’t use X, Y, Z, E labels for their drivers ( Duet 3 Mini 5plus Wiring - Duet3D ) and I don’t see how we could either. (So, I’d probably do something like DRIVER0_STEP, DRIVER1_STEP, etc. for that board.) Similarly, if a board has FAN1 and FAN2 ports then I think the aliases would need to be that (and not FAN0 and FAN1) as otherwise it could lead to notable confusion.

I think it would be good for the TMC pins to include TMC in the name (eg, X_TMCUART) as otherwise there could be confusion between “diag” and “uart” functions unrelated to stepper motor drivers.

So, maybe some guidance like:

The following pin alias suffixes should only be used as described (and should be preferred where applicable):
<driver>_STEP : A stepper motor step pin.
<driver>_DIR : A stepper motor direction pin.
<driver>_ENABLE : A stepper motor enable pin.
<driver>_TMCUART : A Trinamic stepper motor UART pin.
<name>_STOP : An endstop pin. Prefer using the driver name if associated with a stepper. If both min and max endstops are associated with a stepper than prefer <driver>_MAX_STOP and <driver>_MIN_STOP.
<name>_HEATER : The power control pin for a heater. If the heater is associated with an extruder stepper motor then prefer using the stepper motor name (eg, E_HEATER).
<name>_TEMPERATURE: An analog temperature sensing pin, typically used with thermistors.  If the pin is associated with a heater than prefer using the same name for both heater and temperature.
<port>_<integer> : Integer suffixes are used to indicate a pin number in a port containing multiple pins (typically starting at 0). For example MYPORT_0 would be pin 0 of "myport".

Just some ideas.
-Kevin

1 Like

I like this layout

The following pin alias suffixes should only be used as described (and should be preferred where applicable):
<driver>_STEP : A stepper motor step pin.
<driver>_DIR : A stepper motor direction pin.
<driver>_ENABLE : A stepper motor enable pin.
<driver>_TMCUART : A Trinamic stepper motor UART pin.
<name>_STOP : An endstop pin. Prefer using the driver name if associated with a stepper. If both min and max endstops are associated with a stepper than prefer <driver>_MAX_STOP and <driver>_MIN_STOP.
<name>_HEATER : The power control pin for a heater. If the heater is associated with an extruder stepper motor then prefer using the stepper motor name (eg, E_HEATER).
<name>_TEMPERATURE: An analog temperature sensing pin, typically used with thermistors.  If the pin is associated with a heater than prefer using the same name for both heater and temperature.
<port>_<integer> : Integer suffixes are used to indicate a pin number in a port containing multiple pins (typically starting at 0). For example MYPORT_0 would be pin 0 of "myport".

I think this is conmpatibe with the above <thing>_<function> spec?

# Z-Probes
Z_PROBE_CONTROL
Z_PROBE_SERVO

Maybe:

  • All available pins shall be mapped with matching aliases
  • If the board can use SPI and UART TMC stepper driver, then commented examples for both options shall be provided
  • Common / standard pins shall follow the below naming scheme and commented with the board’s labelling where ambiguous
  • Repeated items (drivers etc) shall be labelled to match the board’s labelling so X_STEP, Y_STEP ... or DRIVER0_STEP, DRIVER_1_STEP
  • Board specific pins, which are not among the listed standard pins, shall be named according to the documentation, silk-screen or function
  • If only a single pin exists, do not add a number, if multiple pins for a function are existing (e.g. E0, E1 etc.) start numbering to match the board labelling
  • Additional relevant information shall be added as comment (if applicable), e.g.
    • Pin is PWM capable
    • Pin has pull-up / pull-down
    • Pin is also MISO, MOSI, CLK of SPI Bus x
  • If the board has multiple hardware SPI buses this information shall be added to the header information

Duet is a great example of what this should solve. When I was setting up my klipper config for the duet I was cross referencing the wiring diagram, the reprapfirmware code, and the schematic. I found out that I was on the wrong branch of reprapfirmware code.

Three way cross reference was painful. Oh, and I still ended up typing out the wrong pin :slight_smile:

+1 make the names match the board as close as possible.

A couple points here, rather than mirroring the silkscreen of each board in the aliases, a generic alias might be more useful like Driver0_step and then make board pinout images that identify each generic location. Less chasing though multiple files, easier to make a printer specific printer.cfg and just [include boardx_pins.cfg] to connect to different board types, or paste into printer.cfg, your choice.

As an additional request, can aliases work with secondary MCUs such as klipper expander such as Alias
LED1=mcu2:PB1 for example?

I was given the answer for secondary MCUs in klipper discord. I’m currently in the process of creating a set of pin aliases for the range of 8 stepper controllers to be used with Voron 2.4 and Trident printers, using the following format. Once it’s been tested, I can offer the pin files for others to use. I didn’t want to use “X/Y/Z/E0-E4” for extruder labeling as that’s confusing to new users who don’t use 5 extruders.

#####################################################################
#   <controller> Pin Aliases
#####################################################################

[board_pins]
aliases:
	# Stepper drivers
	DRIVER0_EN=P,  DRIVER0_STEP=P,  DRIVER0_DIR=P,  DRIVER0_CS=P,
	DRIVER1_EN=P,  DRIVER1_STEP=P,  DRIVER1_DIR=P,  DRIVER1_CS=P,
	DRIVER2_EN=P,  DRIVER2_STEP=P,  DRIVER2_DIR=P,  DRIVER2_CS=P,
	DRIVER3_EN=P,  DRIVER3_STEP=P,  DRIVER3_DIR=P,  DRIVER3_CS=P,
	DRIVER4_EN=P,  DRIVER4_STEP=P,  DRIVER4_DIR=P,  DRIVER4_CS=P,
	DRIVER5_EN=P,  DRIVER5_STEP=P,  DRIVER5_DIR=P,  DRIVER5_CS=P,
	DRIVER6_EN=P,  DRIVER6_STEP=P,  DRIVER6_DIR=P,  DRIVER6_CS=P,
	DRIVER7_EN=P,  DRIVER7_STEP=P,  DRIVER7_DIR=P,  DRIVER7_CS=P,

	# Stepper Driver SPI
	DRIVER_SPI_MOSI=P, DRIVER_SPI_MISO=P, DRIVER_SPI_SCK=P,
		
	# Heaters
    HEATER_BED=P, HEATER0=P, HEATER1=P, HEATER2=P, HEATER3=P, 
	
    # Thermistors
    TEMP_BED=P, TEMP0=P, TEMP1=P, TEMP2=P, TEMP3=P, PT100=P,

    # Fans
    FAN0=P, FAN1=P, FAN2=P, FAN3=P, FAN4=P, FAN5=P, 

    # End stops
    ENDSTOP0=P,  ENDSTOP1=P,  ENDSTOP2=P,  ENDSTOP3=P,
    ENDSTOP4=P,  ENDSTOP5=P,  ENDSTOP6=P,  ENDSTOP7=P,  PROBE=P,

    # EXP1
    EXP1_1=P,   EXP1_2=P,
    EXP1_3=P,   EXP1_4=P,
    EXP1_5=P,   EXP1_6=P,    # Slot in the socket by EXP1_
    EXP1_7=P,   EXP1_8=P,
    EXP1_9=<GND>, EXP1_10=<5V>,

    # EXP2
    EXP2_1=P,   EXP2_2=P,
    EXP2_3=P,   EXP2_4=P,
    EXP2_5=P,   EXP2_6=P,     # Slot in the socket by EXP2_
    EXP2_7=P,   EXP2_8=<RST>,
    EXP2_9=<GND>, EXP2_10=,

    # TFT
    TFT1=<5V>,
    TFT2=<GND>,
    TFT3=P,
    TFT4=P,
    TFT5=<RST>,


    # Touch Probe Port
    TOUCH1=P,  # BL Touch end stop pin
    TOUCH2=<GND>,
    TOUCH3=P,   # BL Touch servo pin
    TOUCH4=<5V>,
    TOUCH5=<GND>,
	
	#RGB LEDs
	RGB0=P

type or paste code here

I definitely agree, Duet is the perfect example for this. Their documentation is the worst I’ve ever seen for any kind of “open source” product.

I’m currently converting my Ender 5 to Klipper with a Duet 2 Maestro and it’s horrible. I’m doing exactly what you outlined in your example.