readme
| Supported Targets | ESP32 | ESP32-C3 | ESP32-S2 | ESP32-S3 |
| ----------------- | ----- | -------- | -------- | -------- |
# ESP-Crash Example (`esp-crash-example`)
This example is tied to esp-crash, which can be found at https://esp-crash.wennlund.nu/. It is a free service to monitor and display crashes.
## Using the component
Run the following command in your ESP-IDF project to install this component:
```bash
idf.py add-dependency "jimmyw/esp-crash"
```
## Example
To run the provided example, create it as follows:
```bash
idf.py create-project-from-example "jimmyw/esp-crash:esp-crash-example"
```
Then build as usual:
```bash
cd esp-crash-example
idf.py build
```
And flash it to the board:
```bash
idf.py -p PORT flash monitor
coredump_crash
coredump_upload
```
## License
This component is provided under Apache 2.0 license, see [LICENSE](LICENSE.md) file for details.
## Contributing
Please check [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
## How to use esp-crash
This example uses a coredump partition, named coredump. The built-in crash-handler will write a crash to this partition if you enable CONFIG_ESP_COREDUMP_ENABLE_TO_FLASH=y in your sdkconfig.
To add a coredump partition to your esp-idf partition.csv file, you can use the following example:
```
# Name, Type, SubType, Offset, Size, Flags
nvs, data, nvs, 0x9000, 0x5000,
phy_init, data, phy, 0xe000, 0x2000,
factory, app, factory, 0x10000, 1M,
coredump, data, coredump, , 128K,
```
This will create a 64K coredump partition. If you have a lot of tasks, you need to increase the size to fit all data.
Before you can see your uploaded crashes, you need to access https://esp-crash.wennlund.nu/ with your GitHub account, and register a new unique PROJECT_NAME. After you have registered it, you can add additional team members who can also examine the crashes.
## ESP-Crash Identifier
Using
```
esp_err_t esp_crash_identifier_setup()
```
you can add an identifier to RAM, which will always be included in your crash dump. This identifier is in the format:
```
ESP_CRASH:<PROJECT_NAME>;<PROJECT_VER>;<DEVICE_ID>;
```
Example:
```
ESP_CRASH:esp-crash-example;8e8e8df-5.1;6941729232066;
```
This is critical for our backend to pick up, just make it available to your registered project, and know what build file to match up.
## Uploading coredumps
Use
```
esp_err_t upload_coredump(const char *url, const char *filename)
```
to upload the coredump directly from a partition to a server. This will read the flash partition and send it as raw data. Upload your crashes to "https://esp-crash.wennlund.nu/dump" if you like to have a free store for your crashes.
## Downloading coredumps
Use
```
esp_err_t esp_crash_webserver_start(httpd_handle_t handle)
```
to register the /crash.dmp webserver endpoint. Curling this address will download the last crash if available. After downloading this crash, you can upload it again to "https://esp-crash.wennlund.nu/dump" if you like.
## Interval crash upload
Use
```
esp_err_t esp_crash_upload_timer_init()
```
to enable a 60s interval timer, that will try to find an existing core dump, and upload if possible. On success, the coredump partition will be erased.
## Uploading build files
To be able to examine your crashes, you also need to upload the elf binary, with debugging symbols. This can be done with this one-liner:
```
curl "https://esp-crash.wennlund.nu/upload_elf?project_name=esp-crash-example&project_ver=$VERSION" -F file=@build/esp-crash-example.elf
```
Ensure $VERSION matches the same PROJECT_VER in your build. This command can easily be added to your CI system.
### CLI commands
```
coredump_crash
Crash the esp32
coredump_erase
Erase coredump partition
coredump_upload [-e] [url] [filename]
Upload core dump to server
url Url to send to
filename Filename
-e, --erase Erase after successful upload
```
## Example Output
## What's upcoming?
Im working on an interactive in browser gdb debug session. Its going to be awsome!