Installing the latest (v0.12.0+) version of Klipper on a Neptune 4 Max

Contents

  1. Project description
  2. Install from stock firmware
  3. Revert to stock firmware
  4. Upgrade to new Elegoo firmware version of S&M Makers Klipper
  5. Upgrade S&M Makers Klipper on the same stock firmware version
  6. Known issues
  7. Recovery STM32F401 MCU images

Project description

Release tags use the following format: sandmmakers-ElegooNeptune4Max-v<STOCK_FIRMWARE_VERSION>-v<KLIPPER_VERSION>-<KLIPPER_COMMIT>-<FIRMWARE_VERSION>.

FieldMeaningExample
<STOCK_FIRMWARE_VERSION> Stock firmware version installed on the printer 1.2.3.4
<KLIPPER_VERSION> Version of Klipper 0.13.0
<KLIPPER_COMMIT_COUNT> Number of official commits since Klipper version was released 51
<FIRMWARE_VERSION> Version of S&M Makers Klipper with the given stock and Klipper versions 1

Install from stock firmware:

  1. Update printer to the stock firmware version that matches the desired S&M Makers Klipper version
  2. SSH into printer (default user: mks default password: makerbase)
    Replace <IP_ADDRESS> with the IP address of your printer.
    ssh mks@<IP_ADDRESS>
  3. Stop running services
    1. Stop the klipper service sudo systemctl stop klipper
    2. Stop the klipper_mcu service sudo systemctl stop klipper_mcu
    3. Stop the znp_tjc_klipper and io services sudo systemctl stop makerbase-client
  4. Backup stock files
    1. Backup Klipper
      In the command below, replace <STOCK_FIRMWARE_VERSION> with the stock firmware version installed on the printer (e.g., 1.2.3.4).
      mv ~/klipper ~/klipper.stock.v<STOCK_FIRMWARE_VERSION>
    2. Backup the Linux MCU firmware
      In the command below, replace <STOCK_FIRMWARE_VERSION> with the stock firmware version installed on the printer (e.g., 1.2.3.4).
      sudo mv /usr/local/bin/klipper_mcu /usr/local/bin/klipper_mcu.stock.v<STOCK_FIRMWARE_VERSION>
  5. Update the printer.cfg file
    Currently, using symlinks to maintain printer.cfg files does not work correctly.
    1. Backup the ~/klipper_config/klipper.cfg file
      In the command below, replace <STOCK_FIRMWARE_VERSION> with the stock firmware version installed on the printer (e.g., 1.2.3.4).
      cp ~/klipper_config/printer.cfg ~/klipper_config/printer.cfg.stock.v<STOCK_FIRMWARE_VERSION>
    2. Remove or comment out the max_accel_to_decel field in the [printer] section
    3. Update the [gcode_macro PRINT_END] section
      1. Remove the line {% set RUN_DECEL = printer.configfile.settings['printer'].max_accel_to_decel|float %}
      2. Remove ACCEL_TO_DECEL={RUN_DECEL} from the line SET_VELOCITY_LIMIT VELOCITY={RUN_VELOCITY} ACCEL={RUN_ACCEL} ACCEL_TO_DECEL={RUN_DECEL}
    4. Update the [gcode_macro CANCEL_PRINT] section
      1. Remove the line {% set RUN_DECEL = printer.configfile.settings['printer'].max_accel_to_decel|float %}
      2. Remove ACCEL_TO_DECEL={RUN_DECEL} from the line SET_VELOCITY_LIMIT VELOCITY={RUN_VELOCITY} ACCEL={RUN_ACCEL} ACCEL_TO_DECEL={RUN_DECEL}
  6. Clone the S&M Makers Klipper repo git clone https://github.com/sandmmakers/klipper.git klipper.sandmmakers
  7. Create a klipper symlink ln -s ~/klipper.sandmmakers ~/klipper
  8. Enter the klipper directory cd ~/klipper
  9. Checkout the desired firmware version
    Checking out a tag is recommended as checking out a branch is only intended for developers.
  10. Build Klipper
    Every time the znp_tjc_klipper process starts, it will check if ~/klipper/klippy/chelper/c_helper.so exists. If it doesn't, znp_tjc_klipper will copy an incompatible version to that location. This incompatible version will cause the newly installed version of Klipper to fail to start with the error message:
    Internal error during connect: function/symbol 'extruder_stepper_free' not found in library '/home/mks/klipper.hybrid/klippy/chelper/c_helper.so': /home/mks/klipper.hybrid/klippy/chelper/c_helper.so: undefined symbol: extruder_stepper_free Once the underlying issue is corrected, use the "RESTART" command to reload the config and restart the host software. Printer is halted
    1. Ensure klippy/chelper/c_helper.so doesn't exist sudo rm -f klippy/chelper/c_helper.so
    2. Build klippy/chelper/c_helper.so ~/klippy-env/bin/python2 klippy/chelper/__init__.py
    3. (Optional) Prebuild all Klipper byte code ~/klippy-env/bin/python2 -m compileall klippy
  11. Build the Linux MCU firmware
    1. Delete any stale files make clean
    2. Configure the Linux MCU firmware
      1. Launch the configuration utility make menuconfig
      2. Select Linux process
      3. Press ESC to save and exit
    3. Delete any stale files make clean
    4. Build the firmware make
    5. Copy and rename the generated binary to /usr/local/bin/klipper_mcu sudo mv out/klipper.elf /usr/local/bin/klipper_mcu.sandmmakers
    6. Create symlink so new binary is used sudo ln -s /usr/local/bin/klipper_mcu.sandmmakers /usr/local/bin/klipper_mcu
  12. (Optional) Create the STM32F401 MCU firmware
    Building and flashing a new STM32F401 MCU firmware is optional and not required for correct operation. While there are two known methods for flashing a new STM32F401 MCU firmware, both require partially disassembling the printer. The first involves removing the front plastic cover to expose the SD card connector on the main board. Using this method, the flash binary file is given a particular name, placed on an SD card (which is inserted into the printer), and then the printer is powered on, causing the update process to begin. The other known method involves shorting two locations on the printer's mainboard while pressing the reset button (also on the mainboard). This places the printer in the STM32 bootloader mode, allowing for printer host-based utilities to read and write to the STM32F401 MCU's flash memory. Both of these approaches are cumbersome, error-prone, and dangerous. Since the stock version of the firmware is known to work, flashing the STM32F401 MCU is not recommended.
    1. Delete any stale files make clean
    2. Configure the STM32F401 MCU firmware
      1. Launch the configuration utility make menuconfig
      2. Select Enable extra low-level configuration options
      3. Set the Micro-controller Architecture field to STMicroelectronics STM32
      4. Set the Processor model field to STM32F401
      5. Ensure the Bootloader offset field is set to 32KiB bootloader
      6. Ensure the Clock Reference field to 8 MHz crystal
      7. Set the Communication interface to USART1 PA10/PA9
      8. Ensure the Baud rate for serial port field is set to 250000
      9. Ensure the GPIO pins to set at micro-controller startup field is blank
      10. Press ESC to save and exit
    3. Delete any stale files make clean
    4. Build the firmware make
    5. Copy out/klipper.bin to a PC
      The following command is performed on a PC, NOT the printer. Replace <IP_ADDRESS> with the IP address of your printer.
      scp mks@<IP_ADDRESS>:klipper/out/klipper.bin .
    6. Rename klipper.bin to elegoo_k1.bin
    7. Copy elegoo_k1.bin to the SD card included with the printer
    8. Insert into printer
      1. TBD (A non-printer partial disassembly method is currently under investigation)
    9. Restart printer
    10. Wait at least two minutes
    11. Turn off printer
    12. Insert the SD card back into the PC
    13. Verify the elegoo_k1.bin file has been replaced with elegoo_k1.CUR
  13. Reboot the computer
    If the printer currently off, just turn it on instead of rebooting.

    While the previously stopped services could be manually restarted, it is generally easier and safer to just reboot the printer.
    sudo reboot now

Revert to stock firmware

  1. SSH into printer (default user: mks default password: makerbase)
    Replace <IP_ADDRESS> with the IP address of your printer.
    ssh mks@<IP_ADDRESS>
  2. Stop running services
    1. Stop the klipper service sudo systemctl stop klipper
    2. Stop the klipper_mcu service sudo systemctl stop klipper_mcu
    3. Stop the znp_tjc_klipper and io services sudo systemctl stop makerbase-client
  3. Restore the stock firmware printer.cfg file
    1. Rename or delete the current printer.cfg file
      The current printer.cfg file can be renamed if you plan on reinstalling S&M Makers Klipper in the future, otherwise you can just delete the file. Select one of the options below:
      • The following command will rename the printer.cfg file and append the year, month, and day onto the file name mv ~/klipper_config/printer.cfg ~/klipper_config/printer.cfg.sandmmakers.$(date -I)
      • The following command will rename the printer.cfg file and append the year, month, day, hour, minutes, and seconds onto the file name mv ~/klipper_config/printer.cfg ~/klipper_config/printer.cfg.sandmmakers.$(date +"%Y-%m-%dT%H-%M-%S")
      • The following command will delete the printer.cfg file rm ~/klipper.cfg
    2. Restore stock firmware printer.cfg file
      In the command below, replace <STOCK_FIRMWARE_VERSION> with the stock firmware version being restored (e.g., 1.2.3.4).
      cp ~/klipper_config/printer.cfg.stock.<STOCK_FIRMWARE_VERSION> ~/klipper_config/printer.cfg
  4. Restore the stock klipper application
    1. Remove the klipper symbolic link rm ~/klipper
    2. Restore the stock klipper directory
      In the command below, replace <STOCK_FIRMWARE_VERSION> with the stock firmware version being restored (e.g., 1.2.3.4).
      mv ~/klipper.stock.v<STOCK_FIRMWARE_VERSION> ~/klipper
    3. (Optional) Remove the klipper.sandmmakers directory
      This step is optional, but recommended for anyone planning on staying with stock firmware because it restores extra disk space on the printer.
      rm ~/klipper.sandmmakers
  5. Restore klipper_mcu
    1. Remove the klipper_mcu symbolic link sudo rm /usr/local/bin/klipper_mcu
    2. Restore the stock firmware klipper_mcu
      In the command below, replace <STOCK_FIRMWARE_VERSION> with the stock firmware version being restored (e.g., 1.2.3.4).
      sudo mv /usr/local/bin/klipper_mcu.stock.v<SOTCK_FIRMWARE_VERSION> /usr/local/bin/klipper_mcu
    3. Remove the klipper_mcu.sandmmakers sudo rm /usr/local/bin/klipper_mcu.sandmmakers
  6. Reboot sudo reboot now

Upgrade to new Elegoo firmware version of S&M Makers Klipper

  1. Follow the steps for reverting back to stock firmware, but making sure to save the printer.cfg
  2. Upgrade to new stock Elegoo firmware
    The Elegoo firmware update process might overwrite the printer.cfg file. Make sure you have a backup before proceeding.
    The Elegoo firmware update process might force the bed leveling mode to Standard Mode (6x6 grid). If you were using the Professional Mode, you might need to set it back after the update process has completed.
    1. Download the new stock firmware from https://www.elegoo.com/pages/download
    2. Extract the downloaded archive
    3. Update the mainboard firmware
      1. Insert an empty flash drive into the computer
      2. Copy the ELEGOO_UPDATE_DIR directory from the directory whose name started with Firmware pack-4MAX_ to the root of an empty USB flash drive
      3. Safely eject the flash drive
      4. Insert the flash drive into the printer
      5. On the printer's LCD screen, navigate to Settings->About Machine
      6. Click the arrow at the botton of the LCD screen to start the update process
      7. Click Confirm to confirm the new firmware files are in the root of the flash drive
      8. Wait while the firmware is updated and the printer is rebooted (this can take 1-2 minutes)
      9. Use Fluidd, Mainsail, or SSH to safely turn off the printer
      10. Remove the USB flash drive from the printer
    4. Update the LCD firmware
      1. Insert the SD card that came with the printer (8GB fat32-formatted) into the computer
      2. Ensure there are no existing files on the SD card
      3. Copy the .tft file in the directory whose name starts with Screen firmware(UI)- to the root of the SD card
      4. Safely eject the SD card from the computer
      5. Disconnect the LCD screen from the printer
      6. Remove the back cover from the LCD screen, using a 2mm hex wrench
      7. Insert the SD card into the circuit board in the LCD screen
      8. Reattach the back cover from the LCD screen, using a 2mm hex wrench
      9. Reconnect the LCD screen to the printer
      10. Turn on the printer
      11. Wait until the LCD screen firmware update process has completed
      12. Use Fluidd, Mainsail, or SSH to safely turn off the printer
      13. Disconnect the LCD screen from the printer
      14. Remove the back cover from the LCD screen, using a 2mm hex wrench
      15. Remove the SD card from the LCD screen circuit board, pushing in before pulling it out
      16. Reattach the back cover from the LCD screen, using a 2mm hex wrench
      17. Reconnect the LCD screen to the printer
    5. Verify the update completed successfully
      1. Turn on the printer
      2. On the printer's LCD screen, navigate to Settings->About Machine
      3. Verify the displayed firmware versions match the downloaded firmware versions
    6. Copy any Klipper configuation changes from the previous printer.cfg to the new printer.cfg file
    7. Using Fluidd, Mainsail, or SSH restart Klipper
    8. Perform auto bed leveling
    9. Set the Z-offset
  3. Follow the directions for installing S&M Makers Klipper from stock

Upgrade S&M Makers Klipper on the same stock firmware version

  1. SSH into printer (default user: mks default password: makerbase)
    Replace <IP_ADDRESS> with the IP address of your printer.
    ssh mks@<IP_ADDRESS>
  2. Stop running services
    1. Stop the klipper service sudo systemctl stop klipper
    2. Stop the klipper_mcu service sudo systemctl stop klipper_mcu
    3. Stop the znp_tjc_klipper and io services sudo systemctl stop makerbase-client
  3. Enter the klipper directory cd ~/klipper
  4. Fetch changes from GitHub git fetch
  5. Checkout the desired firmware version
    Checking out a tag is recommended as checking out a branch is only intended for developers.
  6. Build Klipper
    1. Ensure klippy/chelper/c_helper.so doesn't exist sudo rm -f klippy/chelper/c_helper.so
    2. Build klippy/chelper/c_helper.so ~/klippy-env/bin/python2 klippy/chelper/__init__.py
    3. (Optional) Prebuild all Klipper byte code ~/klippy-env/bin/python2 -m compileall klippy
  7. Build the Linux MCU firmware
    1. Delete any stale files make clean
    2. Configure the Linux MCU firmware
      1. Launch the configuration utility make menuconfig
      2. Select Linux process
      3. Press ESC to save and exit
    3. Delete any stale files make clean
    4. Build the firmware make
    5. Copy and rename the generated binary to /usr/local/bin/klipper_mcu sudo mv out/klipper.elf /usr/local/bin/klipper_mcu.sandmmakers
  8. Reboot sudo reboot now

Known issues

The following issues are known to affect this customized version of Kipper:
  1. There is a timing issue affecting the ability to save automatic bed leveling data. After using the LCD to perform an automatic bed level and then pressing the save button, a timing related error message may appear in the Fluidd/Mainsail console. Performing a FIRMWARE_RESTART, restarting Klipper or restarting the printer will fix the error. The automatic bed leveling data will be saved and used when Klipper restarts.
  2. On 2024-03-13, the feature max_accel_to_decel was deprecated in Klipper and replaced with a new minimum_cruise_ratio feature. The Neptune 4 Max supports a number of "performance modes", selectable with the LCD controller, which set a number of Klipper configuration values as determined by the file /home/mks/Desktop/myfile/znp/znp_tjc_klipper/elegoo_conf.ini. The updated version of Klipper ignores any attempts to set max_accel_to_decelminimum_cruise_ratio does not get set when the "performance mode" is set or changed, resulting in the default value (unless manually changed) always being used.

Recovery STM32F401 MCU images

These recovery images are only intended for recovering a system if something goes horribly wrong. They are not required during the normal installation process.