From ac9edd6fbc92c67f9a8dea9bcebf124849c1c560 Mon Sep 17 00:00:00 2001
From: Eric Callahan <arksine.code@gmail.com>
Date: Mon, 14 Oct 2024 05:42:57 -0400
Subject: [PATCH] docs: add status request documentation

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>
---
 README.md   | 35 ++++++++++++++++++++++++++++++++--
 protocol.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 88 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index de64edc..aa087e9 100644
--- a/README.md
+++ b/README.md
@@ -149,10 +149,11 @@ options:
                         Path to Klipper firmware file
   -u <uuid>, --uuid <uuid>
                         Can device uuid
-  -q, --query           Query Bootloader Device IDs
+  -q, --query           Query Bootloader Device IDs (CANBus only)
   -v, --verbose         Enable verbose responses
   -r, --request-bootloader
                         Requests the bootloader and exits
+  -s, --status          Connect to bootloader and print status
 ```
 
 ### Can Programming
@@ -205,7 +206,8 @@ and if detected it will begin writing.  If a `status led` is configured it
 will blink rapidly during the programming procedure.  After successful completion
 Katapult will rename the firmware file's extension to `.cur`, reset the MCU,
 and jump to the application.  If Katapult encounters an error during programming
-it will exit and attempt to rename the firmware file with a `.err` extension.
+it will attempt to rename the firmware file with a `.err` extension, then drop
+to command mode.
 
 If the `firmware file` does not exist or if there is an error initializing the
 SD Card, Katapult will enter command mode.  In this mode the `status led`
@@ -240,6 +242,35 @@ is `CANBus` and `Long File Name Support` is enabled.  This will result in a bina
 larger than 16 KiB.  It should be noted that `Klipper` currently only supports a
 16 KiB bootloader offset for the `RP2040`.
 
+### Troubleshooting
+
+As mentioned above, Katapult will enter command mode if it encounters an error
+during initialization or programming.  When in command mode it is possible
+to use the flashtool's  `-s` option to query Katapult's status which includes
+SD Card status:
+
+```
+./scripts/flashtool.py -s -u aabbccddeeff
+Connecting to CAN UUID aabbccddeeff on interface can0
+Resetting all bootloader node IDs...
+Detected Klipper binary version v0.12.0-302-g87ac69363, MCU: stm32f103xe
+Attempting to connect to bootloader
+Katapult Connected
+Software Version: v0.0.1-95-g2d7bd0c
+Protocol Version: 1.1.0
+Block Size: 64 bytes
+Application Start: 0x8004000
+MCU type: stm32f103xe
+Verifying canbus connection
+
+*** SD Card Status ***
+Detected SD Card Interface: HARDWARE_SPI
+Last SD Flash State: NO_DISK
+SD Flags: DEINITIALIZED
+Last Error: NO_IDLE_STATE
+Status Request Complete
+```
+
 
 ## Katapult Deployer
 
diff --git a/protocol.md b/protocol.md
index b5a3808..831e09b 100644
--- a/protocol.md
+++ b/protocol.md
@@ -158,6 +158,61 @@ payload in the following format:
 <4 byte orig_command><6 byte UUID><0x00><0x00>
 ```
 
+#### Get SD Card Status: `0x17`
+
+Returns SD Card information.  Only available when SD Card programming is enabled.
+
+```
+<0x01><0x88><0x17><0x00><CRC><0x99><0x03>
+```
+
+Responds with [acknowledged](#acknowledged-0xa0) containing a 8 byte
+payload in the following format:
+
+```
+<4 byte orig_command><1 byte SD Card Interface><1 byte SD Card State><1 byte SD Card Flags><1 byte SD Card Error>
+```
+
+- `SD Card Interface`: An enumeration detailing the configured SD Card interface.
+  Can be one of the following values:
+  - `HARDWARE_SPI = 0`
+  - `SOFTWARE_SPI = 1`
+  - `SDIO = 2`
+- `SD Card State`: An enumeration detailing the last SD Card Programming state.
+  Can be one of the following values:
+  - `DISABLED = 0`
+  - `PENDING TRANSFER = 1`
+  - `UPLOADING = 2`
+  - `VERIFYING = 3`
+  - `FINISHED = 4`
+  - `ERROR = 5`
+  - `NO FILE FOUND = 6`
+  - `NO DISK FOUND = 7`
+- `SD Card Flags`:  A flag containing specific state detected during the
+  SD Card operation.  Can be a bitwise OR of any of the following:
+  - `INITIALIZED = 1`
+  - `TRANSFER MODE = 2`
+  - `HIGH CAPACITY = 4`
+  - `WRITE PROTECTION ENABLED = 8`
+  - `CARD DETECT PULLUP DISABLED = 16`
+  - `DEINITIALIZED = 32`
+- `SD Card Error`:  An enumeration containing the last error detected. Can be one
+  of the following values:
+  - `NO ERROR = 0`
+  - `RESET ERROR (NO IDLE STATE) = 1`
+  - `SEND IF COND ERROR = 2`
+  - `SEND OP COND ERROR = 3`
+  - `READ OCR ERROR = 4`
+  - `READ BLOCK ERROR = 5`
+  - `WRITE BLOCK ERROR = 6`
+  - `SEND CID ERROR = 7`
+  - `SEND REL ADDR ERROR = 8`
+  - `SEND CSD ERROR = 9`
+  - `SEL DESEL ERROR = 10`
+  - `SET CARD DETECT ERROR = 11`
+  - `SET BLOCKLEN ERROR = 12`
+  - `CRC ON/OFF ERROR = 13`
+
 ### Responses
 
 #### Acknowledged: `0xa0`