From a530bf2421341209a2c8c6fa140c9d2047f1029c Mon Sep 17 00:00:00 2001 From: Donna Whisnant Date: Wed, 17 Aug 2022 23:35:25 -0500 Subject: [PATCH] docs: Add SDIO programming and split verification details to SDCard_Updates Signed-off-by: Donna Whisnant --- docs/SDCard_Updates.md | 120 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 114 insertions(+), 6 deletions(-) diff --git a/docs/SDCard_Updates.md b/docs/SDCard_Updates.md index 09307715..1b94a1e2 100644 --- a/docs/SDCard_Updates.md +++ b/docs/SDCard_Updates.md @@ -48,7 +48,7 @@ All options can be viewed by the help screen: ./scripts/flash-sdcard.sh -h SD Card upload utility for Klipper -usage: flash_sdcard.sh [-h] [-l] [-b ] [-f ] +usage: flash_sdcard.sh [-h] [-l] [-c] [-b ] [-f ] positional arguments: @@ -58,6 +58,7 @@ positional arguments: optional arguments: -h show this message -l list available boards + -c run flash check/verify only (skip upload) -b serial baud rate (default is 250000) -f path to klipper.bin ``` @@ -78,6 +79,14 @@ Note that when upgrading a MKS Robin E3 it is not necessary to manually run `update_mks_robin.py` and supply the resulting binary to `flash-sdcard.sh`. This procedure is automated during the upload process. +The `-c` option is used to perform a check or verify-only operation +to test if the board is running the specified firmware correctly. This +option is primarily intended for cases where a manual power-cycle is +necessary to complete the flashing procedure, such as with bootloaders that +use SDIO mode instead of SPI to access their SD Cards. (See Caveats below) +But, it can also be used anytime to verify if the code flashed into the board +matches the version in your build folder on any supported board. + ## Caveats - As mentioned in the introduction, this method only works for upgrading @@ -89,7 +98,16 @@ This procedure is automated during the upload process. the current version. - Only boards that use SPI for SD Card communication are supported. Boards that use SDIO, such as the Flymaker Flyboard and MKS Robin Nano - V1/V2, will not work. + V1/V2, will not work in SDIO mode. However, it's usually possible to + flash such boards using Software SPI mode instead. But if the board's + bootloader only uses SDIO mode to access the SD Card, a power-cycle of + the board and SD Card will be necessary so that the mode can switch from SPI + back to SDIO to complete reflashing. Such boards should be defined with + `skip_verify` enabled to skip the verify step immediately after flashing. + Then after the manual power-cycle, you can rerun the exact same + `./scripts/flash-sdcard.sh` command, but add the `-c` option to complete + the check/verify operation. See [Flashing Boards that use SDIO](#flashing-boards-that-use-sdio) + for examples. ## Board Definitions @@ -118,17 +136,25 @@ The following fields may be specified: retreived from the board schematic. This field is required. - `firmware_path`: The path on the SD Card where firmware should be transferred. The default is `firmware.bin`. -- `current_firmware_path` The path on the SD Card where the renamed firmware +- `current_firmware_path`: The path on the SD Card where the renamed firmware file is located after a successful flash. The default is `firmware.cur`. +- `skip_verify`: This defines a boolean value which tells the scripts to skip + the firmware verification step during the flashing process. The default + is `False`. It can be set to `True` for boards that require a manual + power-cycle to complete flashing. To verify the firmware afterward, run + the script again with the `-c` option to perform the verification step. + [See caveats with SDIO cards](#caveats) -If software SPI is required the `spi_bus` field should be set to `swspi` +If software SPI is required, the `spi_bus` field should be set to `swspi` and the following additional field should be specified: - `spi_pins`: This should be 3 comma separated pins that are connected to the SD Card in the format of `miso,mosi,sclk`. It should be exceedingly rare that Software SPI is necessary, typically only -boards with design errors will require it. The `btt-skr-pro` board definition -provides an example. +boards with design errors or boards that normally only support SDIO mode for +their SD Card will require it. The `btt-skr-pro` board definition provides an +example of the former, and the `btt-octopus-f446-v1` board definition +provides an example of the latter. Prior to creating a new board definition one should check to see if an existing board definition meets the criteria necessary for the new board. @@ -145,3 +171,85 @@ BOARD_ALIASES = { If you need a new board definition and you are uncomfortable with the procedure outlined above it is recommended that you request one in the [Klipper Community Discord](Contact.md#discord). + +## Flashing Boards that use SDIO + +[As mentioned in the Caveats](#caveats), boards whose bootloader uses +SDIO mode to access their SD Card require a power-cycle of the board, +and specifically the SD Card itself, in order to switch from the SPI Mode +used while writing the file to the SD Card back to SDIO mode for the +bootloader to flash it into the board. These board definitions will +use the `skip_verify` flag, which tells the flashing tool to stop after +writing the firmware to the SD Card so that the board can be manually +power-cycled and the verification step deferred until that's complete. + +There are two scenarios -- one with the RPi Host running on a separate +power supply and the other when the RPi Host is running on the same +power supply as the main board being flashed. The difference is whether +or not it's necessary to also shutdown the RPi and then `ssh` again after +the flashing is complete in order to do the verification step, or if the +verification can be done immediately. Here's examples of the two scenarios: + +### SDIO Programming with RPi on Separate Power Supply + +A typical session with the RPi on a Separate Power Supply looks like the +following. You will, of course, need to use your proper device path and +board name: +``` +sudo service klipper stop +cd ~/klipper +git pull +make clean +make menuconfig +make +./scripts/flash-sdcard.sh /dev/ttyACM0 btt-octopus-f446-v1 +[[[manually power-cycle the printer board here when instructed]]] +./scripts/flash-sdcard.sh -c /dev/ttyACM0 btt-octopus-f446-v1 +sudo service klipper start +``` + +### SDIO Programming with RPi on the Same Power Supply + +A typical session with the RPi on the Same Power Supply looks like the +following. You will, of course, need to use your proper device path and +board name: +``` +sudo service klipper stop +cd ~/klipper +git pull +make clean +make menuconfig +make +./scripts/flash-sdcard.sh /dev/ttyACM0 btt-octopus-f446-v1 +sudo shutdown -h now +[[[wait for the RPi to shutdown, then power-cycle and ssh again to the RPi when it restarts]]] +sudo service klipper stop +cd ~/klipper +./scripts/flash-sdcard.sh -c /dev/ttyACM0 btt-octopus-f446-v1 +sudo service klipper start +``` + +In this case, since the RPi Host is being restarted, which will restart +the `klipper` service, it's necessary to stop `klipper` again before doing +the verification step and restart it after verification is complete. + +### SDIO to SPI Pin Mapping + +If your board's schematic uses SDIO for its SD Card, you can map the pins +as described in the chart below to determine the compatible Software SPI +pins to assign in the `board_defs.py` file: + +| SD Card Pin | Micro SD Card Pin | SDIO Pin Name | SPI Pin Name | +| :---------: | :----------------: | :--------------: | :--------------: | +| 9 | 1 | DATA2 | None (PU)* | +| 1 | 2 | CD/DATA3 | CS | +| 2 | 3 | CMD | MOSI | +| 4 | 4 | +3.3V (VDD) | +3.3V (VDD) | +| 5 | 5 | CLK | SCLK | +| 3 | 6 | GND (VSS) | GND (VSS) | +| 7 | 7 | DATA0 | MISO | +| 8 | 8 | DATA1 | None (PU)* | +| N/A | 9 | Card Detect (CD) | Card Detect (CD) | +| 6 | 10 | GND | GND | + +\* None (PU) indicates an unused pin with a pull-up resistor