3diy
/
klipper
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Add SDIO programming and split verification details to SDCard_Updates 

Signed-off-by: Donna Whisnant <dewhisna@dewtronics.com>
This commit is contained in:
Donna Whisnant 2022-08-17 23:35:25 -05:00 committed by KevinOConnor
parent 773f9ac56c
commit a530bf2421
1 changed files with 114 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

120
docs/SDCard_Updates.md
View File

@ -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 <baud>] [-f <firmware>]
usage: flash_sdcard.sh [-h] [-l] [-c] [-b <baud>] [-f <firmware>]
<device> <board>
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 <baud> serial baud rate (default is 250000)
-f <firmware> 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