diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 2bf6847..7348c91 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -25,6 +25,6 @@ - [Simulating](./tooling/simulating/index.md) - [Wokwi](./tooling/simulating/wokwi.md) - [QEMU](tooling/simulating/qemu.md) ---- - -[Appendix A: Troubleshooting](./misc/troubleshooting.md) +- [Troubleshooting](./troubleshooting/index.md) + - [`esp-idf-hal` based projects](./troubleshooting/std.md) + - [`espflash`](./troubleshooting/espflash.md) \ No newline at end of file diff --git a/src/installation/riscv-and-xtensa.md b/src/installation/riscv-and-xtensa.md index 6644f83..ab825c2 100644 --- a/src/installation/riscv-and-xtensa.md +++ b/src/installation/riscv-and-xtensa.md @@ -69,7 +69,7 @@ If you run into an error, please, check the [Troubleshooting][troubleshooting] c [gcc-toolchain-github-fork]: https://github.com/espressif/crosstool-NG/ [rustup-overrides]: https://rust-lang.github.io/rustup/overrides.html [llvm-github-fork-upstream issue]: https://github.com/espressif/llvm-project/issues/4 -[troubleshooting]: ../misc/troubleshooting.md +[troubleshooting]: ../troubleshooting/index.md ### Other Installation Methods for `Xtensa` Targets diff --git a/src/troubleshooting/espflash.md b/src/troubleshooting/espflash.md new file mode 100644 index 0000000..dab50cd --- /dev/null +++ b/src/troubleshooting/espflash.md @@ -0,0 +1,32 @@ +# `espflash` + +## `rtc_clk_init: Possibly invalid CONFIG_XTAL_FREQ setting` + +This issue is reported by users using an ESP32 module with a 26MHz crystal oscillator. The root +cause of the issue is that the default bootloader flashed by espflash expects a 40MHz crystal. + +### If you are building an `esp-idf-sys` based project + +Make sure your [`sdkconfig`](https://github.com/esp-rs/esp-idf-sys/blob/master/BUILD-OPTIONS.md#sdkconfig) +is set up properly to use a 26MHz crystal. It needs to contain the following configuration option: + +``` +CONFIG_XTAL_FREQ_26=y +``` + +You should also prefer using `cargo-espflash` over `espflash`. `cargo-espflash` integrates with your +project and it will flash the bootloader that is built next to your project instead of the default +one. + +If you want to use `espflash`, you need to specify an appropriate bootloader image using +`--bootloader`. You can find the bootloader in `target///build/esp-idf-sys-*/build/bootloader/bootloader.bin` + +### If you are building an `esp-hal` based project + +Make sure your HAL ([ESP32](https://docs.rs/esp32-hal/latest/esp32_hal/), [ESP32-C2](https://docs.rs/esp32c2-hal/latest/esp32c2_hal/)) +is configured to the correct crystal frequency. To do this, you must disable the default features +and enable `xtal-26mhz` (besides the other default features). + +When flashing, you need to specify an appropriate bootloader image using `--bootloader`. Currently, +you will need to build this bootloader using an `esp-idf` based project (Rust or C based should work +equally, we recommend a project set up with [esp-idf-template](https://github.com/esp-rs/esp-idf-template)). diff --git a/src/misc/troubleshooting.md b/src/troubleshooting/index.md similarity index 55% rename from src/misc/troubleshooting.md rename to src/troubleshooting/index.md index 436af74..047819d 100644 --- a/src/misc/troubleshooting.md +++ b/src/troubleshooting/index.md @@ -1,35 +1,6 @@ # Troubleshooting -Here, we will present a list of common errors that may appear when building a project alongside the reason and a solution to them. - -## Environment Variable `LIBCLANG_PATH` Not Set - -```text -thread 'main' panicked at 'Unable to find libclang: "couldn't find any valid shared libraries matching: ['libclang.so', 'libclang-*.so', 'libclang.so.*', 'libclang-*.so.*'], set the `LIBCLANG_PATH` environment variable to a path where one of these files can be found (invalid: [])"', /home/esp/.cargo/registry/src/github.com-1ecc6299db9ec823/bindgen-0.60.1/src/lib.rs:2172:31 -``` - -We need `libclang` for [`bindgen`] to generate the Rust bindings to the ESP-IDF C headers. -Make sure you have sourced the export file generated by `espup`, see [Set up the environment variables][set-up-the-environment-variables]. - -[`bindgen`]: https://github.com/rust-lang/rust-bindgen -[set-up-the-environment-variables]: ./../installation/riscv-and-xtensa.md#3-set-up-the-environment-variables - -## Missing `ldproxy` - -```shell -error: linker `ldproxy` not found - | - = note: No such file or directory (os error 2) -``` - -If you are trying to build a `std` application [`ldproxy`][ldproxy] must be installed. See [`std` Development Requirements][rust-esp-book-std-requirements] - -```shell -cargo install ldproxy -``` - -[ldproxy]: https://github.com/esp-rs/embuild/tree/master/ldproxy -[rust-esp-book-std-requirements]: ./../installation/std-requirements.md +This chapter lists certain questions and common problems we have encountered over the time, along with their solutions. This page collects common issues independent of the chosen ESP ecosystem. ## Using the Wrong Rust Toolchain @@ -101,51 +72,3 @@ If using GNU ABI, install [MinGW/MSYS2 toolchain]. [Compile-time Requirements]: https://github.com/rust-lang/cc-rs#compile-time-requirements [Visual Studio 2013 (or later) or the Visual C++ Build Tools 2019]: https://rust-lang.github.io/rustup/installation/windows.html [MinGW/MSYS2 toolchain]: https://www.msys2.org/ - -## FAQ - -### `sdkconfig.defaults` File is Updated but it Doesn't Appear to Have Had Any Effect - -You must clean your project and rebuild for changes in the `sdkconfig.defaults` to take effect: - -```shell -cargo clean -cargo build -``` - -### The Documentation for the Crates Mentioned on This Page is out of Date or Missing - -Due to the [resource limits] imposed by [docs.rs], internet access is blocked while building documentation. For this reason, we are unable to build the documentation for `esp-idf-sys` or any crate depending on it. - -Instead, we are building the documentation and hosting it ourselves on GitHub Pages: - -- [`esp-idf-hal` Documentation] -- [`esp-idf-svc` Documentation] -- [`esp-idf-sys` Documentation] - -[resource limits]: https://docs.rs/about/builds#hitting-resource-limits -[docs.rs]: https://docs.rs -[`esp-idf-hal` documentation]: https://esp-rs.github.io/esp-idf-hal/esp_idf_hal/ -[`esp-idf-svc` documentation]: https://esp-rs.github.io/esp-idf-svc/esp_idf_svc/ -[`esp-idf-sys` documentation]: https://esp-rs.github.io/esp-idf-sys/esp_idf_sys/ - -### A Stack Overflow in Task `main` has Been Detected - -If the second-stage bootloader reports this error, you likely need to increase the stack size for the main task. This can be accomplished by adding the following to the `sdkconfig.defaults` file: - -```text -CONFIG_ESP_MAIN_TASK_STACK_SIZE=7000 -``` - -In this example, we are allocating 7 kB for the main task's stack. - -### How to Disable Watchdog Timer(s)? - -Add to your `sdkconfig.defaults` file: - -```text -CONFIG_INT_WDT=n -CONFIG_ESP_TASK_WDT=n -``` - -Recall that you must clean your project before rebuilding when modifying these configuration files. diff --git a/src/troubleshooting/std.md b/src/troubleshooting/std.md new file mode 100644 index 0000000..dd5d827 --- /dev/null +++ b/src/troubleshooting/std.md @@ -0,0 +1,76 @@ +# `esp-idf-hal` based projects + +## Environment Variable `LIBCLANG_PATH` Not Set + +```text +thread 'main' panicked at 'Unable to find libclang: "couldn't find any valid shared libraries matching: ['libclang.so', 'libclang-*.so', 'libclang.so.*', 'libclang-*.so.*'], set the `LIBCLANG_PATH` environment variable to a path where one of these files can be found (invalid: [])"', /home/esp/.cargo/registry/src/github.com-1ecc6299db9ec823/bindgen-0.60.1/src/lib.rs:2172:31 +``` + +We need `libclang` for [`bindgen`] to generate the Rust bindings to the ESP-IDF C headers. +Make sure you have sourced the export file generated by `espup`, see [Set up the environment variables][set-up-the-environment-variables]. + +[`bindgen`]: https://github.com/rust-lang/rust-bindgen +[set-up-the-environment-variables]: ./../installation/riscv-and-xtensa.md#3-set-up-the-environment-variables + +## Missing `ldproxy` + +```shell +error: linker `ldproxy` not found + | + = note: No such file or directory (os error 2) +``` + +If you are trying to build a `std` application [`ldproxy`][ldproxy] must be installed. See [`std` Development Requirements][rust-esp-book-std-requirements] + +```shell +cargo install ldproxy +``` + +[ldproxy]: https://github.com/esp-rs/embuild/tree/master/ldproxy +[rust-esp-book-std-requirements]: ./../installation/std-requirements.md + +## `sdkconfig.defaults` File is Updated but it Doesn't Appear to Have Had Any Effect + +You must clean your project and rebuild for changes in the `sdkconfig.defaults` to take effect: + +```shell +cargo clean +cargo build +``` + +## The Documentation for the Crates Mentioned on This Page is out of Date or Missing + +Due to the [resource limits] imposed by [docs.rs], internet access is blocked while building documentation. For this reason, we are unable to build the documentation for `esp-idf-sys` or any crate depending on it. + +Instead, we are building the documentation and hosting it ourselves on GitHub Pages: + +- [`esp-idf-hal` Documentation] +- [`esp-idf-svc` Documentation] +- [`esp-idf-sys` Documentation] + +[resource limits]: https://docs.rs/about/builds#hitting-resource-limits +[docs.rs]: https://docs.rs +[`esp-idf-hal` documentation]: https://esp-rs.github.io/esp-idf-hal/esp_idf_hal/ +[`esp-idf-svc` documentation]: https://esp-rs.github.io/esp-idf-svc/esp_idf_svc/ +[`esp-idf-sys` documentation]: https://esp-rs.github.io/esp-idf-sys/esp_idf_sys/ + +## A Stack Overflow in Task `main` has Been Detected + +If the second-stage bootloader reports this error, you likely need to increase the stack size for the main task. This can be accomplished by adding the following to the `sdkconfig.defaults` file: + +```text +CONFIG_ESP_MAIN_TASK_STACK_SIZE=7000 +``` + +In this example, we are allocating 7 kB for the main task's stack. + +## How to Disable Watchdog Timer(s)? + +Add to your `sdkconfig.defaults` file: + +```text +CONFIG_INT_WDT=n +CONFIG_ESP_TASK_WDT=n +``` + +Recall that you must clean your project before rebuilding when modifying these configuration files. diff --git a/src/writing-your-own-application/generate-project/esp-idf-template.md b/src/writing-your-own-application/generate-project/esp-idf-template.md index c55d19d..34c69e2 100644 --- a/src/writing-your-own-application/generate-project/esp-idf-template.md +++ b/src/writing-your-own-application/generate-project/esp-idf-template.md @@ -129,4 +129,4 @@ If you encounter any issues while building the project, please, see the [Trouble [espflash]: https://github.com/esp-rs/espflash/tree/main/espflash [runner-config]: https://doc.rust-lang.org/cargo/reference/config.html#targettriplerunner -[troubleshooting]: ../../misc/troubleshooting.md +[troubleshooting]: ../../troubleshooting/index.md diff --git a/src/writing-your-own-application/generate-project/esp-template.md b/src/writing-your-own-application/generate-project/esp-template.md index 08aeaaa..bf59239 100644 --- a/src/writing-your-own-application/generate-project/esp-template.md +++ b/src/writing-your-own-application/generate-project/esp-template.md @@ -182,4 +182,4 @@ If you encounter any issues while building the project, please, see the [Trouble [espflash]: https://github.com/esp-rs/espflash/tree/main/espflash [runner-config]: https://doc.rust-lang.org/cargo/reference/config.html#targettriplerunner -[troubleshooting]: ../../misc/troubleshooting.md +[troubleshooting]: ../../troubleshooting/index.md