From 86a6fce5255cb07aab634614c4f78698d466a4e8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?D=C3=A1niel=20Buga?= <bugadani@gmail.com>
Date: Tue, 28 Nov 2023 19:43:35 +0100
Subject: [PATCH] Add FAQ entry for the 26MHz error

---
 src/SUMMARY.md                  |  3 ++-
 src/troubleshooting/espflash.md | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+), 1 deletion(-)
 create mode 100644 src/troubleshooting/espflash.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 76b06af..7348c91 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -26,4 +26,5 @@
     - [Wokwi](./tooling/simulating/wokwi.md)
     - [QEMU](tooling/simulating/qemu.md)
 - [Troubleshooting](./troubleshooting/index.md)
-  - [`esp-idf-hal` based projects](./troubleshooting/std.md)
\ No newline at end of file
+  - [`esp-idf-hal` based projects](./troubleshooting/std.md)
+  - [`espflash`](./troubleshooting/espflash.md)
\ No newline at end of file
diff --git a/src/troubleshooting/espflash.md b/src/troubleshooting/espflash.md
new file mode 100644
index 0000000..ab61e1c
--- /dev/null
+++ b/src/troubleshooting/espflash.md
@@ -0,0 +1,32 @@
+# espflash
+
+## Error when trying to use 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` 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)).