docs: add Troubleshooting & FAQ section to README#131
Open
pangerlkr wants to merge 1 commit into
Open
Conversation
Added a troubleshooting and FAQ section with common issues and solutions.Adds a comprehensive Troubleshooting & FAQ section addressing the most common issues reported in the GitHub issues tracker, including: - Wi-Fi Scanner crashes and Deauth attack edge cases - On-screen keyboard / touch calibration fixes - Battery type, capacity, and IP5306 power management tips - Flashing failures and Arduino IDE setup guidance - Sub-GHz / NRF24 / CC1101 hardware seating issues - RFID / NFC card read range troubleshooting Closes common questions from issues cifertech#124, cifertech#125, cifertech#126, cifertech#127.
There was a problem hiding this comment.
Pull request overview
This PR adds a new “Troubleshooting & FAQ” section to the project README to document common community-reported issues and recommended fixes/workarounds.
Changes:
- Added Wi‑Fi troubleshooting entries (scanner crashes, deauth limitations, beacon spammer visibility).
- Added UI/input, power/battery, flashing, RF module seating, and RFID/NFC troubleshooting guidance.
- Added SD/Web update and Arduino IDE setup pointers.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### 📡 Wi-Fi | ||
|
|
||
| **Q: Wi-Fi Scanner shows no networks or crashes on v1.53+** | ||
| > This is a known issue related to the NVS partition becoming full after repeated scans. Flash the latest pre-compiled binary from the `Pre-compiled Bin/` folder, or perform a full chip erase before re-flashing: `esptool.py erase_flash`. Then re-flash the firmware. |
Comment on lines
+278
to
+282
| ### ⌨️ Keyboard / Input | ||
|
|
||
| **Q: The on-screen keyboard is unresponsive or registers wrong characters** | ||
| > This is usually a touchscreen calibration issue. Go to **Device & System → Touch Calibrate** and run the four-corner calibration routine. Save the result and restart the device. | ||
|
|
Comment on lines
+290
to
+292
| **Q: What battery type and capacity should I use?** | ||
| > The IP5306 charging IC supports a single-cell **3.7V Li-Ion / LiPo** battery. A capacity of **1000–2000 mAh** is recommended for several hours of operation. Do **not** use Li-Ion cells rated above 4.2V or flat-top cells without a protection circuit. | ||
|
|
There was a problem hiding this comment.
Yes, this info is still missing ! @cifertech
| > The firmware is built with the **Arduino IDE** (not Android Studio). Install the **ESP32 board package** by Espressif via Board Manager, then install all libraries listed in the `Libraries/` folder. Set the board to **ESP32S3 Dev Module**, partition scheme to **16MB Flash (3MB APP/9.9MB FATFS)**. | ||
|
|
||
| **Q: Firmware update from SD card fails or gets stuck** | ||
| > Ensure the `.bin` file is placed in the **root** of the SD card and is named exactly as expected by the OTA routine. Use a FAT32-formatted card with a capacity of 32 GB or less. |
| **Q: Sub-GHz Jammer / Replay shows no received signals** | ||
| > Verify the CC1101 module is firmly seated on the shield header. Check SPI connections and confirm the correct frequency band is selected in settings (433 MHz, 868 MHz, or 915 MHz depending on your region). | ||
|
|
||
| **Q: 2.4GHz Scanner or Protokill has no effect** |
Owner
|
Hey @pangerlkr, thanks for putting this together. the content is really useful! I'd prefer to keep the README clean and minimal though. Would you be ok if I take your content and add it to the wiki? |
Contributor
Author
|
@cifertech , sure! As you see fit. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Added a troubleshooting and FAQ section with common issues and solutions.Adds a comprehensive Troubleshooting & FAQ section addressing the most common issues reported in the GitHub issues tracker, including:
Closes common questions from issues #124, #125, #126, #127.