{"id":31686598,"url":"https://github.com/abd-01/esp32-guru-upload","last_synced_at":"2026-02-17T05:02:07.644Z","repository":{"id":314242352,"uuid":"1054680485","full_name":"ABD-01/esp32-guru-upload","owner":"ABD-01","description":"POST Guru Meditation crashdump from ESP32 to a server endpoint ","archived":false,"fork":false,"pushed_at":"2025-09-22T10:29:02.000Z","size":73,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-12T05:14:48.718Z","etag":null,"topics":["esp32","flask-application","guru-meditation","hardfault","panic-handler","qemu"],"latest_commit_sha":null,"homepage":"https://abd-01.github.io/esp32-guru-upload/coredump/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ABD-01.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-11T07:22:56.000Z","updated_at":"2025-09-22T10:29:05.000Z","dependencies_parsed_at":"2025-09-15T03:01:50.813Z","dependency_job_id":null,"html_url":"https://github.com/ABD-01/esp32-guru-upload","commit_stats":null,"previous_names":["abd-01/esp32-guru-upload"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ABD-01/esp32-guru-upload","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ABD-01%2Fesp32-guru-upload","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ABD-01%2Fesp32-guru-upload/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ABD-01%2Fesp32-guru-upload/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ABD-01%2Fesp32-guru-upload/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ABD-01","download_url":"https://codeload.github.com/ABD-01/esp32-guru-upload/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ABD-01%2Fesp32-guru-upload/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29534452,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T05:00:25.817Z","status":"ssl_error","status_checked_at":"2026-02-17T04:57:16.126Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esp32","flask-application","guru-meditation","hardfault","panic-handler","qemu"],"created_at":"2025-10-08T09:28:51.070Z","updated_at":"2026-02-17T05:02:07.638Z","avatar_url":"https://github.com/ABD-01.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# esp32-guru-upload\n\nUpload Guru Meditation crashdumps from an ESP32 to a Flask server endpoint.\n\nESP32 firmware captures crashdumps from the dedicated coredump partition.\n\nCrashdumps are uploaded via HTTP POST to a [Flask server](https://abd-01.github.io/esp32-guru-upload/coredump/)\n\n\n## How To\n\n### 1. Open in Codespaces\n\nThis repository is preconfigured with a development container.\n\nOpen it in GitHub Codespaces to get the ESP-IDF and Python environment ready.\n\n### 2. Start ESP32 Firmware in QEMU\n\nLaunch the emulated ESP32 firmware with port forwarding:\n\n```bash\ncd esp32-guru-upload\nget_idf   # setup ESP-IDF environment\nidf.py qemu --qemu-extra-args \"-nic user,hostfwd=tcp::8081-:8080\"\n```\n\nFor more insight on QEMU visit my [Blog](https://abd-01.github.io/posts/2025-07-15-QEMU/).\n\n### 3. Start the Flask Server\n\nIn another terminal:\n\n```bash\ncd esp32-guru-upload\npython endpoint_app.py\n```\n\n* Flask server will run at [`http://localhost:8080/`](https://abd-01.github.io/esp32-guru-upload/coredump/).\n\n***Demo view of the server: [abd-01.github.io/esp32-guru-upload](https://abd-01.github.io/esp32-guru-upload/coredump/)***\n\n### 4. Access the Web UI\n\nVisit:\n[http://localhost:8080/](https://abd-01.github.io/esp32-guru-upload/coredump/) or the GitHub Codespaces-provided URL.\n\n## Overview\n\n### ESP32 Firmware\n\nRuns on real hardware or in QEMU. It intentionally triggers crashes, captures crashdumps from the dedicated coredump partition, and uploads them over HTTP.\n\n### Flask Server\n\nReceives crashdumps via POST `/upload`, stores them as `.elf` files, and provides a simple web interface to browse and analyze dumps using ESP-IDF tools.\n\n### Development Container\n\nPreconfigured for GitHub Codespaces or VS Code Dev Containers. Includes the ESP-IDF toolchain, QEMU emulator, and Python environment.\n\n### Project Structure\n\n```\nabd-01-esp32-guru-upload/\n├── .devcontainer/         # Devcontainer setup (ESP-IDF, QEMU, Flask)\n├── main/                  # ESP32 firmware sources\n│   ├── crash_app.c        # Crash simulation\n│   ├── dummy_app.c        # Random dummy tasks\n│   ├── guru-upload.c      # Main app, Wi-Fi \u0026 tasks\n│   ├── upload_coredump_app.c # Upload task\n│   └── http_service/      # HTTP client helpers\n├── templates/             # Flask HTML templates\n├── endpoint_app.py        # Flask server entrypoint\n└── README.md\n```\n\n## Explanation\n\n### Background\n\nI was recently working on Hardfault Diagnostics for ARM Cortex-M, which could create crashlogs in the event of a Hardfault.\n\nMy work is in progress and can be viewed [here](https://github.com/ABD-01/hardfault-coredump-arm-cortex-m).\n\nI would have eventually looked into ESP32, however, this gave me the chance to get into the [Guru Meditation](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-guides/fatal-errors.html) earlier.\n\n### Software\n\n[QEMU](https://www.qemu.org/docs/master/) has been an integral part of my work for the last couple of months, as it allowed me to get into different machines without needing the actual hardware. (I also use QEMU as my go-to virtual machine emulator instead of VMware or other software.) You can check out my [blog](https://abd-01.github.io/posts/2025-07-15-QEMU/) on QEMU if you like.\n\nThe official [`qemu-system-xtensa`](https://www.qemu.org/docs/master/system/target-xtensa.html) does not support ESP32 targets. Thankfully, [Espressif maintains a fork of QEMU](https://github.com/espressif/esp-toolchain-docs/blob/main/qemu/README.md) with patches that support these chips.\n\nFork of QEMU with Espressif patches: [github.com/espressif/qemu](https://github.com/espressif/qemu)\n\nBuild this version from source, and if everything works correctly, we have `esp32` in the supported machines list:\n\n```\n$ qemu-system-xtensa -M help\nSupported machines are:\nesp32                Espressif ESP32 machine\nesp32s3              Espressif ESP32S3 machine\nkc705                kc705 EVB (dc232b)\nkc705-nommu          kc705 noMMU EVB (de212)\nlx200                lx200 EVB (dc232b)\nlx200-nommu          lx200 noMMU EVB (de212)\nlx60                 lx60 EVB (dc232b)\nlx60-nommu           lx60 noMMU EVB (de212)\nml605                ml605 EVB (dc232b)\nml605-nommu          ml605 noMMU EVB (de212)\nnone                 empty machine\nsim                  sim machine (dc232b) (default)\nvirt                 virt machine (dc232b)\n```\n\nThe next thing used is the [ESP-IDF (Espressif IoT Development Framework)](https://github.com/espressif/esp-idf). Just follow the manual for installation.\n\nI have set up all the installation into the devcontainer so you don't have to worry about installing any prerequisite software.\n\n### Implementation\n\nFor a Guru Meditation to be triggered, there has to be a piece of notorious code.\n\nI have written [crash\\_app.c](https://github.com/ABD-01/esp32-guru-upload/blob/master/main/crash_app.c), which just calls a few functions (to showcase stack depth) and writes to a prohibited location:\n\n```c\n==================== THREAD 1 (TCB: 0x3ffb94b0, name: 'CrashTask') =====================\n#0  0x400da38f in baz (val=99) at esp32-guru-upload/main/crash_app.c:49\n#1  bar (val=67) at esp32-guru-upload/main/crash_app.c:36\n#2  foo (val=67) at esp32-guru-upload/main/crash_app.c:28\n#3  CrashTask (pvParameters=\u003coptimized out\u003e) at esp32-guru-upload/main/crash_app.c:20\n#4  0x40085f54 in vPortTaskWrapper (pxCode=0x400da2f0 \u003cCrashTask\u003e, pvParameters=0x0) at esp-idf/components/freertos/FreeRTOS-Kernel/portable/xtensa/port.c:139\n```\n\n***Visit [abd-01.github.io/esp32-guru-upload/device_log](https://abd-01.github.io/esp32-guru-upload/device_log/) for complete logs.***\n\n[ESP-IDF (Espressif IoT Development Framework)](https://github.com/espressif/esp-idf) through its `menuconfig` provides an option for coredumps to be sent over UART or saved in Flash. See [sdkconfig](https://github.com/ABD-01/esp32-guru-upload/blob/master/sdkconfig) or run `idf.py menuconfig`:\n\n```\n# Core dump\n\nCONFIG_ESP_COREDUMP_ENABLE_TO_FLASH=y\nCONFIG_ESP_COREDUMP_ENABLE_TO_UART=n\nCONFIG_ESP_COREDUMP_ENABLE_TO_NONE=n\nCONFIG_ESP_COREDUMP_DATA_FORMAT_BIN=n\nCONFIG_ESP_COREDUMP_DATA_FORMAT_ELF=y\nCONFIG_ESP_COREDUMP_CHECKSUM_CRC32=y\nCONFIG_ESP_COREDUMP_CHECK_BOOT=y\nCONFIG_ESP_COREDUMP_ENABLE=y\nCONFIG_ESP_COREDUMP_LOGS=y\nCONFIG_ESP_COREDUMP_MAX_TASKS_NUM=64\n```\n\nCoredump-related public APIs can be used by including [esp\\_core\\_dump.h](https://github.com/espressif/esp-idf/blob/master/components/espcoredump/include/esp_core_dump.h).\n\n[guru\\_upload.c](https://github.com/ABD-01/esp32-guru-upload/blob/master/main/guru-upload.c) is the main file of the project implementing `app_main`, and the first thing it does is check if a coredump exists in flash:\n\n```c\nesp_err_t err = esp_core_dump_image_get(\u0026addr, \u0026size);\n```\n\nIf a coredump is found, `UploadCoredumpTask` is invoked as a separate RTOS task (implementation in [upload\\_coredump\\_app.c](https://github.com/ABD-01/esp32-guru-upload/blob/master/main/upload_coredump_app.c)).\n\nOther than that, [guru\\_upload.c](https://github.com/ABD-01/esp32-guru-upload/blob/master/main/guru-upload.c) starts a dummy application (which just prints logs based on a pseudorandom number) and an HTTP webserver that responds with *\"Hello from ESP32\"*.\n\n***The project, instead of being created from scratch, was created using the [HTTP Request Example](https://github.com/espressif/esp-idf/tree/master/examples/protocols/http_request) template.***\n\nThe HTTP client operations are also inspired by the provided examples.\nSee [esp\\_http\\_client\\_example.c#http\\_native\\_request](https://github.com/espressif/esp-idf/blob/f38b8fec92a0e389b733cb4fbf49be86e5144333/examples/protocols/esp_http_client/main/esp_http_client_example.c#L763-L792).\n\n[upload\\_coredump\\_app.c](https://github.com/ABD-01/esp32-guru-upload/blob/master/main/upload_coredump_app.c) reads the coredump saved in flash and posts it chunk by chunk to the server:\n\n```c\ncoredump = esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_DATA_COREDUMP, NULL);\nesp_err_t err = esp_partition_read(coredump, offset, buffer, buffer_size);\nhttp_upload_send_chunk(client, buffer, buffer_size);\n```\n\n### Server\n\nI had a fair share of experience with Flask, and having worked with connected vehicle protocols and protobuf, I also put together a Flask-based server where I can upload the coredump data. See [endpoint\\_app.py](https://github.com/ABD-01/esp32-guru-upload/blob/master/endpoint_app.py) for internal details.\n\n[http://localhost:8080/](https://abd-01.github.io/esp32-guru-upload/coredump/) displays the list of coredumps received.\n[http://localhost:8080/coredump/coredump-\\\u003ctimestamp\u003e.elf](https://abd-01.github.io/esp32-guru-upload/coredump/coredump-1758023059.elf/) will run `esp_coredump` on the file and display the results.\n\n***For demo visit: [abd-01.github.io/esp32-guru-upload/coredump/coredump-1758023059.elf](https://abd-01.github.io/esp32-guru-upload/coredump/coredump-1758023059.elf)***\n\n[http://localhost:8080/upload](https://abd-01.github.io/esp32-guru-upload/coredump/) is the endpoint that receives the coredump via POST method.\n\nThe ESP32 is also running an HTTP server which can be viewed at [http://localhost:8080/esp_server](https://abd-01.github.io/esp32-guru-upload/esp_server/)\n\n## License\n\nGNU Affero General Public License v3.0 (AGPL-3.0). See [LICENSE](https://github.com/ABD-01/esp32-guru-upload/blob/master/LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabd-01%2Fesp32-guru-upload","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabd-01%2Fesp32-guru-upload","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabd-01%2Fesp32-guru-upload/lists"}