Add REST API description

Slider0007 · Oct 9, 2024 · a18a9ad · a18a9ad
1 parent b23f061
commit a18a9ad
Show file tree

Hide file tree

Showing 4 changed files with 59 additions and 2 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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