jimmyw/esp-crash

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!