GITBOOK-180: MCU Protocol error

SUMMARY.md

@@ -70,7 +70,7 @@
 * [Moonraker warnings](faq/moonraker\_warnings/README.md)
   * [PolicyKit Permissions](faq/moonraker\_warnings/policykit-permissions.md)
 * [Klipper errors](faq/klipper\_errors/README.md)
-  * [Command format mismatch](faq/klipper\_errors/command-format-mismatch.md)
+  * [MCU Protocol error](faq/klipper\_errors/command-format-mismatch.md)
 * [Getting Help](faq/getting-help/README.md)
   * [Discord](faq/getting-help/discord.md)
   * [GitHub Discussions](faq/getting-help/github-discussions.md)

faq/klipper_errors/command-format-mismatch.md

@@ -1,36 +1,87 @@
-# Command format mismatch
+---
+description: >-
+  From time to time it happens that there are changes in the Klipper
+  communication between host and MCU. That make it necessary to update all your
+  MCUs to fix the communication error.
+---
 
-You have updated Klipper and now you get this cryptic error message?
+# MCU Protocol error
 
-<figure><img src="../../.gitbook/assets/image (9).png" alt=""><figcaption></figcaption></figure>
+## Description of the error message
+
+<figure><img src="../../.gitbook/assets/klipper-mcu-protocol-error.png" alt=""><figcaption><p>Screenshot of the "MCU Protocol error" message</p></figcaption></figure>
+
+In the middle of the error message, all MCUs are listed with their current version. In my case, you can see the Klipper version on the host is `v0.12.0-75-gc6136bfd`.
+
+Directly below the current Klipper version is a list of all MCUs that still need to be updated. In my case, these are:
+
+* mcu: Current version v0.11.0-225-g38e79dff
+* EBBCan: Current version v0.12.0-61-gb50d6669
+* display: Current version v0.11.0-225-g38e79dff
 
 {% hint style="info" %}
-This is an error and needs to be fixed to make Mainsail and Klipper work again.
+It is also common to have a "Linux MCU". This is mostly used when using an accelerometer (ADXL345, LIS2DW, MPU-6000/9000 series) directly via the GPIO of the Raspberry Pi. This MCU is usually called `rpi`.
 {% endhint %}
 
-## TL;DR <a href="#tldr" id="tldr"></a>
+After the outdated MCUs follows a list of all the MCUs that have already been updated to the latest version. There isn't a single one yet, so it says `<none>` here.
 
-Klipper on your host and on your MCU have different versions. Recompile and flash your MCUs and it will work again. Please also pay attention to the “Linux MCU”, if you had e.g. an adxl345 in use.
+## How to compile a new firmware
 
-The following links should help you to solve the problem:
+You must compile a new firmware to flash it onto the MCU. For this, you need the Klipper firmware settings for the board. These settings can be found in the example file from Klipper:
 
-* [Klipper SD-Card Updates](https://www.klipper3d.org/SDCard\_Updates.html)
-* [Klipper Building and flashing the micro-controller](https://www.klipper3d.org/Installation.html#building-and-flashing-the-micro-controller)
+* [Klipper example configs](https://github.com/Klipper3d/klipper/tree/master/config)
 
-## More detailed <a href="#more-detailed" id="more-detailed"></a>
+To open the Klipper firmware config tool, connect to your printer via SSH and execute the following commands:
 
-Klipper consists of two parts: The software on your host (e.g. Raspberry Pi) and the firmware on your microcontroller (MCU).
+```bash
+cd ~/klipper
+make menuconfig
+```
 
-Under normal circumstances, Klipper (on your host) can simply be updated from Mainsail without any problems and everything will work as expected.
+After you have set all the settings, you can close the menu (press the key `q`). To clear the cache and build the new firmware, execute these commands:
 
-From time to time it happens that there are changes in Klipper that make it necessary to update all your MCUs. Assuming you have run a Klipper update and Klipper on your host now supports commands that your MCUs does not understand. Then you will get the above error message.
+```bash
+make clean
+make
+```
 
-Fortunately, these kind of updates don’t happen very often, but now it has happened to you. ;-)
+The firmware is now compiled and ready for flashing. The file is in `~/klipper/out/klipper.bin`.
 
-In order to solve the problem, you need to update all your MCUs. We are talking about multiple MCUs here, as people tend to forget that they have multiple microcontrollers in use. One of these candidates is the “Linux MCU” that many people install on their Raspberry Pi to measure resonances with an adxl345.
+## Flash the firmware onto the board
 
-Detailed information on how to update the firmware can be found in the Klipper Documentation linked above (under TL;DR).
+The compiled firmware must now be flashed onto the board. There are several ways to do this. Unfortunately, there is no generally valid solution. Most standard boards can be flashed with the following method. At first we have to read the serial by-id path of the MCU:
 
-{% hint style="info" %}
-As far as we know, work is in progress to let Klipper update the firmware on its own.
-{% endhint %}
+```bash
+ls /dev/serial/by-id/*
+```
+
+The output should look like this:
+
+```
+/dev/serial/by-id/usb-Klipper_stm32f042x6_010007000C43565335383320-if00
+```
+
+With this serial path, you can execute the flash command:
+
+```bash
+sudo systemctl stop klipper
+make flash FLASH_DEVICE=<serial path to the board>
+sudo systemctl start klipper
+```
+
+If this command does not work for your board, other options exist. First, you can reread the example configuration to see if your board has another description to flash the board.
+
+There are also these options:
+
+* [Klipper SD-Card Updates](https://www.klipper3d.org/SDCard\_Updates.html)\
+  If a board has already been flashed with Klipper and has a sd card slot, the firmware can be transferred to the sd card in the slot via the board connection and flashed.
+* [Katapult](https://github.com/Arksine/katapult)\
+  Katapult is an alternative bootloader for printer boards. This bootloader is very popular with CAN Toolhead boards. The current board connection can also be used to flash the firmware to the MCU.
+
+## Need help
+
+If, despite these instructions, you still have problems flashing your board or cannot find a config for your board/MCU, please get in touch with your Klipper/Printer Discord/Forum or ask here on the Mainsail communication channels:
+
+{% content-ref url="../getting-help/" %}
+[getting-help](../getting-help/)
+{% endcontent-ref %}