Issues flashing the printer board

[Sineos]

Background

Some printer boards are seemingly unwilling to accept flashing the Klipper firmware. Typically, this results in:

• No board serial output with the command ls /dev/serial/by-id/*
• Mcu: Serial connection closed / Timeout on connect / Wait for identify_response errors in the klippy.log

Common reasons and potential solutions are listed in the following.

make menuconfig Settings

• Using the correct settings during building the firmware is of utmost importance. For common boards, Klipper lists the needed settings on top of the example files
  • Processor Model: Visually inspect the MCU and note the respective type. For some boards, multiple revisions / flavors are existing with different types of MCUs and are requiring different settings.
    Especially during the chip crisis, some manufactures (e.g. Creality) switched to different MCU chips without changing the board’s name, so it is crucial to identify the correct type and follow the respective instructions in the example configurations.
  • Bootloader offset: Choosing the wrong offset might destroy the bootloader, necessitating to reflash the bootloader before Klipper can be successfully flashed
  • Clock Reference: Getting the clock reference wrong will lead to all sorts of unwanted behavior that can be very hard to diagnose
  • Communication interface: This section determines the pins that the board uses to communicate with the SBC. Selecting the incorrect pins will result in the board not being recognized by Klipper.
  • Disable SWD at startup: Some MCU chips require this setting. See the Processor Model point above and note if the instructions call for its usage.
• If unsure whether the make menuconfig settings may have been messed up, the command make distclean will revert all settings back to default

Flashing the board

• Flashing the board is done either via the make flash FLASH_DEVICE= command or more often by copying the klipper.bin to the SD card. Also here, the example configs provide information on the correct procedure
• Certain boards may require that the filename follows a specific convention or is changed each time the board is flashed. The name change is required to prevent the board from entering a boot-loop, where it continuously tries to flash with each reset.
• Some boards will rename the firmware file on the SD card after the flashing process. For example, the filename firmware.bin will be renamed to fimrware.cur. This also is a boot-loop protection.

The SD Card used for flashing

• Some boards are very picky about the SD card during the flashing process
• A good quality SD below 8GB is recommended
• The SD card needs to be formatted as FAT32 with default settings. One option is the SD Memory Card Formatter that is available for different operating systems
• To troubleshoot, it is recommended to try different SD cards, brands, and formatting methods.

USB Cable / Connection

• A good quality USB cable is recommended
• Some combinations of USB cable and USB port on the board only have a very loose fit that might impact connection quality
• Some combinations of USB cables and ports on the board have poorly matching tolerances, causing the plug to never fully enter the connector and leading to failures.
• If connection issues arise, it is recommended to remove all other USB devices from the SBC
• To troubleshoot, it is recommended to try different USB cables and also to try different ports on the SBC side

Linux Issues

• Before Klipper can start talking to a printer board, it needs to be successfully enumerated by the Linux Operating System (OS)
• Any failure or issue already on the OS level will inevitably spoil a successful connection later
• Diagnosing issues on this level can be done with the dmesg command
• There are some known issues regarding the Linux OS:
  • Debian 11 (Bullseye) udev bug - No board or serial found
  • BRLtty / ModemManager - Services Interfering with Klipper
• Update the Linux OS, e.g. sudo apt update && sudo apt upgrade -y, and reboot the SBC

Obtaining the board’s serial

• The command ls /dev/serial/by-id/* will return the path to the connected board in the form:

  /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0
  

• This entire path is used to define the connection in the [mcu] block of the printer.cfg and can also be used as target for flashing the board, e.g.

  make flash FLASH_DEVICE=/dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0
  

• Depending on the board and the used hardware, some boards either change their serial after correctly flashing with Klipper or it might stay invariant
  • If a board was selected to use Communication Interface: USB during make menuconfig then it’s /dev/serial/by-id will change after first flashing Klipper. Boards that selected Serial (on USARTn PAx/PAy) during make menuconfig will not report a different /dev/serial/by-id/ name.
  • Changing serial example

    # Serial of a board that is flashed with Marlin
    /dev/serial/by-id/usb-STMicroelectronics_MARLIN_FYSETC_S6_CDC_in_FS_Mode_3852347 A3038-if00
    # Serial of an unflashed board
    /dev/serial/by-id/usb-STMicroelectronics_GENERICSTM32F407VGT6_CDC_in_FS_Mode_207237875746-if00
    # Serial of the board flashed with Klipper
    /dev/serial/by-id/usb-klipper_stm32f407xx_35001D001950314D35313220-if00      
    

  • Invariant serial example

    # Serial of a board that is flashed with Marlin or not yet flashed
    /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0
    # Same serial when Klipper is flashed: No possibility to distinguish
    /dev/serial/by-id/usb-1a86_USB2.0-Serial-if00-port0