From a18a9adb424f53a2487d50827414d1105000f742 Mon Sep 17 00:00:00 2001
From: Slider0007 <jobbelle@gmx.net>
Date: Wed, 9 Oct 2024 15:37:32 +0200
Subject: [PATCH] Add REST API description

---
 .../components/fileserver_ota/server_file.cpp |  7 ++-
 docs/API/REST/_OVERVIEW.md                    |  1 +
 docs/API/REST/config.md                       |  2 +-
 docs/API/REST/coredump.md                     | 51 +++++++++++++++++++
 4 files changed, 59 insertions(+), 2 deletions(-)
 create mode 100644 docs/API/REST/coredump.md

diff --git a/code/components/fileserver_ota/server_file.cpp b/code/components/fileserver_ota/server_file.cpp
index bed7e0c69..7e5f9acb9 100644
--- a/code/components/fileserver_ota/server_file.cpp
+++ b/code/components/fileserver_ota/server_file.cpp
@@ -1039,6 +1039,7 @@ static std::string printCoreDumpBacktraceInfo(const esp_core_dump_summary_t *sum
 
 static esp_err_t coredump_handler(httpd_req_t *req)
 {
+    const char* APIName = "coredump:v1"; // API name and version
     char query[200];
     char valuechar[30];
     std::string task;
@@ -1121,12 +1122,16 @@ static esp_err_t coredump_handler(httpd_req_t *req)
             return ESP_FAIL;
         }
     }
-    else if (task.compare("forceexception") == 0) { // Only for testing purpose, and ESP exception crash can be forced
+    else if (task.compare("force_exception") == 0) { // Only for testing purpose, and ESP exception crash can be forced
         LogFile.writeToFile(ESP_LOG_ERROR, TAG, "coredump_handler: Software exception triggered manually");
         httpd_resp_send_chunk(req, NULL, 0);
         assert(0);
         return ESP_OK;
     }
+    else if (task.compare("api_name") == 0) {
+        httpd_resp_sendstr(req, APIName);
+        return ESP_OK;
+    }
 
     // Default action: Print backtrace summary
     if (coreDumpGetSummaryRetVal == ESP_OK) {
diff --git a/docs/API/REST/_OVERVIEW.md b/docs/API/REST/_OVERVIEW.md
index 122afd740..15342b046 100644
--- a/docs/API/REST/_OVERVIEW.md
+++ b/docs/API/REST/_OVERVIEW.md
@@ -26,6 +26,7 @@ Further details can be found in the respective REST API endpoint description.
 | [/log](log.md)                       | Log of today (last 80kB)                           | HTML        | 
 | [/ota](ota.md)                       | Over The Air Update                                | HTML        | 
 | [/reboot](reboot.md)                 | Trigger Reboot                                     | HTML        | 
+| [/coredump/](coredump.md)            | Handle Core Dumps (Software Exception)             | HTML        | 
 | [/fileserver/](fileserver.md)        | Fileserver                                         | HTML        | 
 | [/upload/](upload.md)                | File Upload (POST)                                 | HTML        | 
 | [/delete/](delete.md)                | File Deletion (POST)                               | HTML        | 
diff --git a/docs/API/REST/config.md b/docs/API/REST/config.md
index dbd66434b..d46475d2e 100644
--- a/docs/API/REST/config.md
+++ b/docs/API/REST/config.md
@@ -13,7 +13,7 @@ WebUI configuration page (question mark symbol next to each parameter).
 - JSON: `/config`
 - HTML: `/config?task=reload`
 
-1. HTML query request to show API name and version:
+1. Get API name and version:
     - Payload:
       - `/config?task=api_name`
     - Response:
diff --git a/docs/API/REST/coredump.md b/docs/API/REST/coredump.md
new file mode 100644
index 000000000..89d73e0f3
--- /dev/null
+++ b/docs/API/REST/coredump.md
@@ -0,0 +1,51 @@
+[Overview](_OVERVIEW.md) 
+
+## REST API endpoint: coredump
+
+`http://IP-ADDRESS/coredump`
+
+
+Handle core dumps for debugging purpose (software exception)<br>
+
+1. Get API name and version:
+    - Payload:
+      - `/coredump?task=api_name`
+    - Response:
+      - Content type: `Plain Text`
+      - Content: Query response, e.g. `coredump:v1`
+
+2. Get core dump summary:
+    - Payload:
+      - No payload needed
+    - Response:
+      - Content type: `Plain Text` (easy to copy)
+      - Content: Query response
+    - Example:<br>
+        ```
+        Backtrace:  0x4008391D 0x40090B9D 0x40097AF5 0x400D9E6F 0x400FA185 0x400F91AC 0x400F973A 0x400F8220 0x401E1AB2 0x400F8430 0x4009145D
+        Depth: 11
+        Corrupted: 0
+        PC: 1074280733
+        Firmware version: Develop: coredump (Commit: b23f061)
+        ```
+
+3. Save core dump file:
+    - Payload:
+      - `/coredump?task=save`
+    - Response:
+      - Content type: `Attachment`
+      - Content: Core dump file (as download)
+
+4. Clear core dump partition:
+    - Payload:
+      - `/coredump?task=clear`
+    - Response:
+      - Content type: `Plain Text`
+      - Content: Query response
+
+5. Force a software exception (Device reboots instantly):
+    - Payload:
+      - `/coredump?task=force_exception`
+    - Response:
+      - Content type: `Plain Text`
+      - Content: None