From ecc9bbf52a7dfb69a535b6bb87ad887c6e957387 Mon Sep 17 00:00:00 2001
From: "Aaron B. Haun" <aaron@haun.guru>
Date: Mon, 18 Sep 2023 19:48:42 -0400
Subject: [PATCH] docs: add info about requesting bootloaders

Signed-off-by: Aaron B. Haun <aaron@haun.guru>
---
 docs/Bootloader_Entry.md   | 125 +++++++++++++++++++++++++++++++++++++
 docs/Overview.md           |   1 +
 docs/_klipper3d/mkdocs.yml |   1 +
 3 files changed, 127 insertions(+)
 create mode 100644 docs/Bootloader_Entry.md

diff --git a/docs/Bootloader_Entry.md b/docs/Bootloader_Entry.md
new file mode 100644
index 00000000..f42602bd
--- /dev/null
+++ b/docs/Bootloader_Entry.md
@@ -0,0 +1,125 @@
+# Bootloader Entry
+
+Klipper can be instructed to reboot into a [Bootloader](Bootloaders.md) in one
+of the following ways:
+
+## Requesting the bootloader
+
+### Virtual Serial
+
+If a virtual (USB-ACM) serial port is in use, pulsing DTR while at 1200 baud
+will request the bootloader.
+
+#### Python (with `flash_usb`)
+
+To enter the bootloader using python (using `flash_usb`):
+
+```shell
+> cd klipper/scripts
+> python3 -c 'import flash_usb as u; u.enter_bootloader("<DEVICE>")'
+Entering bootloader on <DEVICE>
+```
+
+Where `<DEVICE>` is your serial device, such as
+`/dev/serial.by-id/usb-Klipper[...]` or `/dev/ttyACM0`
+
+Note that if this fails, no output will be printed, success is indicated by
+printing `Entering bootloader on <DEVICE>`.
+
+#### Picocom
+
+```shell
+picocom -b 1200 <DEVICE>
+<Ctrl-A><Ctrl-P>
+```
+
+Where `<DEVICE>` is your serial device, such as
+`/dev/serial.by-id/usb-Klipper[...]` or `/dev/ttyACM0`
+
+`<Ctrl-A><Ctrl-P>` means
+holding `Ctrl`, pressing and releasing `a`, pressing and releasing `p`, then
+releasing `Ctrl`
+
+### Physical serial
+
+If a physical serial port is being used on the MCU (even if a USB serial adapter
+is being used to connect to it), sending the string
+`<SPACE><FS><SPACE>Request Serial Bootloader!!<SPACE>~`.
+
+`<SPACE>` is an ASCII literal space, 0x20.
+
+`<FS>` is the ASCII File Separator,
+0x1c.
+
+Note that this is not a valid message as per the
+[MCU Protocol](Protocol.md#micro-controller-interface), but sync characters(`~`)
+are still respected.
+
+Because this message must be the only thing in the "block"
+it is received in, prefixing an extra sync character can increase reliability if
+other tools were previously accessing the serial port.
+
+#### Shell
+
+```shell
+stty <BAUD> < /dev/<DEVICE>
+echo $'~ \x1c Request Serial Bootloader!! ~' >> /dev/<DEVICE>
+```
+
+Where `<DEVICE>` is your serial port, such as `/dev/ttyS0`, or
+`/dev/serial/by-id/gpio-serial2`, and
+
+`<BAUD>` is the baud rate of the serial
+port, such as `115200`.
+
+### CANBUS
+
+If CANBUS is in use, a special
+[admin message](CANBUS_protocol.md#admin-messages) will request the bootloader.
+This message will be respected even if the device already has a nodeid, and will
+also be processed if the mcu is shutdown.
+
+This method also applies to devices operating in
+[CANBridge](CANBUS.md#usb-to-can-bus-bridge-mode) mode.
+
+#### Katapult's flashtool.py
+
+```shell
+python3 ./katapult/scripts/flashtool.py -i <CAN_IFACE> -u <UUID> -r
+```
+
+Where `<CAN_IFACE>` is the can interface to use. If using `can0`, both the `-i`
+and `<CAN_IFACE>` may be omitted.
+
+`<UUID>` is the UUID of your CAN device.
+
+See the
+[CANBUS Documentation](CANBUS.md#finding-the-canbus_uuid-for-new-micro-controllers)
+for information on finding the CAN UUID of your devices.
+
+## Entering the bootloader
+
+When klipper receives one of the above bootloader requests:
+
+If Katapult (formerly known as CANBoot) is available, klipper will request that
+Katapult stay active on the next boot, then reset the MCU (therefore entering
+Katapult).
+
+If Katapult is not available, klipper will then try to enter a
+platform-specific bootloader, such as STM32's DFU
+mode([see note](#stm32-dfu-warning)).
+
+In short, Klipper will reboot to Katapult if installed, then a hardware specific
+bootloader if available.
+
+For details about the specific bootloaders on various platforms see
+[Bootloaders](Bootloaders.md)
+
+## Notes
+
+### STM32 DFU Warning
+
+Note that on some boards, like the Octopus Pro v1, entering DFU mode can cause
+undesired actions (such as powering the heater while in DFU mode). It is
+recommended to disconnect heaters, and otherwise prevent undesired operations
+when using DFU mode. Consult the documentation for your board for more details.
diff --git a/docs/Overview.md b/docs/Overview.md
index a387ea81..477bc68b 100644
--- a/docs/Overview.md
+++ b/docs/Overview.md
@@ -93,6 +93,7 @@ communication with the Klipper developers.
   Beaglebone PRU.
 - [Bootloaders](Bootloaders.md): Developer information on
   micro-controller flashing.
+- [Bootloader Entry](Bootloader_Entry.md): Requesting the bootloader.
 - [CAN bus](CANBUS.md): Information on using CAN bus with Klipper.
   - [CAN bus troubleshooting](CANBUS_Troubleshooting.md): Tips for
     troubleshooting CAN bus.
diff --git a/docs/_klipper3d/mkdocs.yml b/docs/_klipper3d/mkdocs.yml
index 6db7fe39..d290a45f 100644
--- a/docs/_klipper3d/mkdocs.yml
+++ b/docs/_klipper3d/mkdocs.yml
@@ -133,6 +133,7 @@ nav:
     - RPi_microcontroller.md
     - Beaglebone.md
     - Bootloaders.md
+    - Bootloader_Entry.md
     - CANBUS.md
     - CANBUS_Troubleshooting.md
     - TSL1401CL_Filament_Width_Sensor.md