Add espflash troubleshooting page and 26MHz crystal issue (esp-rs#129)

* Reorganize Troubleshooting * Add FAQ entry for the 26MHz error Co-authored-by: Sergio Gasquez Arcos <sergio.gasquez@gmail.com> --------- Co-authored-by: Sergio Gasquez Arcos <sergio.gasquez@gmail.com>
kubo39 · Nov 30, 2023 · 5ebdcce · 5ebdcce
1 parent fee396b
commit 5ebdcce
Show file tree

Hide file tree

Showing 7 changed files with 115 additions and 84 deletions.
diff --git 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)
diff --git 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
@@ -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/<your MCU's target folder>/<debug or release depending on your build>/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 → src/troubleshooting/index.md b/src/misc/troubleshooting.md → 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
@@ -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
@@ -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
@@ -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