Make RFID failure non-fatal (self-test retries, 4MHz clock, diagnostic log), add beginner Wi-Fi guide + RFID troubleshooting to README

2026-09-09 21:52:40 +02:00
parent 7599f0e6b2
commit 96d14c0538
6 changed files with 167 additions and 19 deletions
--- a/README.md
+++ b/README.md
@@ -98,6 +98,10 @@ Verify:
 idf.py --version
 ```

+> **Never used Espressif tools before? Skip ahead to
+> "[Changing the Wi-Fi without the toolchain](#changing-the-wifi-without-the-toolchain)";**
+> the section below is optional.
+
 ### 2. Build

 ```powershell
@@ -124,9 +128,104 @@ idf.py menuconfig        # -> "MTG RFID Companion" -> SSID + password
 #    sdkconfig.defaults.esp32
 ```

-Leaving the SSID empty (or keeping the `YOUR_...` placeholders) disables station
-mode — the SoftAP pairing server still runs, so you can use the device
-without a home network.
+Leaving the SSID empty (or keeping the `YOUR_...` placeholders) **disables
+station mode**. The SoftAP pairing server runs regardless, so the device stays
+usable as a fully standalone scanner — no home network required.
+
+#### What "station mode disabled" actually means
+
+The Wi-Fi radio still turns on, but only as an access point:
+
+1. `wifi_manager_start()` sees the blank/placeholder SSID and returns early —
+   it never calls `esp_wifi_connect()`, so the device won't try to join any
+   router (and won't pretend to be online).
+2. `web_server_start()` starts unconditionally: SoftAP **`MTG-Companion`** at
+   `192.168.4.1` (own DHCP) plus the `/api/last_uid` and `/api/bind` endpoints.
+3. `net_task` skips the 60-second connect wait **and** the boot-time prefetch.
+   Card lookups only run when you explicitly trigger one, and those fail fast
+   (no internet route) with a `scryfall` log line — they never block the UI.
+
+#### What works and what doesn't
+
+| Feature | In AP-only mode | Notes |
+| :--- | :--- | :--- |
+| RFID scanning, life counter, LED/buzzer | ✔ | fully local |
+| Showing **already-cached** cards (art + stats) | ✔ | served from `/spiffs` |
+| Binding a UID to a card name | ✔ | written to `/spiffs/mappings.json` immediately |
+| **Scryfall lookup + art download** | ✘ | the device has no internet here; the fetch fails and is logged. It completes automatically on a later boot **with Wi-Fi configured** — the boot-time prefetch walks `mappings.json` and downloads anything missing |
+| Scryfall autocomplete in the pairing page | ⚠️ | the AP doesn't pass internet through (no NAT). A phone with **cellular data keeps its mobile connection**, so autocomplete works there; on a device with no other internet path, type the exact card name manually |
+
+> **Use case:** AP-only mode is the normal "deck on the table" flow — mid-game
+> you almost never need live Scryfall lookups. When you do (new card, missing
+> art), configure Wi-Fi once, boot briefly, and the binding + art cache update
+> themselves via prefetch.
+
+---
+
+## Changing the Wi-Fi without the toolchain
+
+> **If you're new to this and haven't installed any Espressif software yet,
+> start here.**
+
+The Wi-Fi network the device connects to is **baked into the firmware at
+compile time** — there is no on-device settings menu yet. To change it you
+must edit one text file and produce a new firmware image. Here is the shortest
+ESPRESSIF-FREE path to do that, with zero drivers or toolchains.
+
+### The one file you edit
+
+Open **`sdkconfig.defaults.esp32`** in any text editor (Notepad is fine) and
+find these two lines:
+
+```
+CONFIG_MTG_WIFI_SSID="YOUR_SSID_HERE"
+CONFIG_MTG_WIFI_PASS="YOUR_PASSWORD_HERE"
+```
+
+Replace the placeholders with **your** network name and password, keeping the
+quotes:
+
+```
+CONFIG_MTG_WIFI_SSID="MyHomeWiFi"
+CONFIG_MTG_WIFI_PASS="correct horse battery staple"
+```
+
+- Keep the file **UTF-8 without BOM**, and don't add spaces inside the quotes.
+- If your password has a `"` or `\` in it, this file format can't represent it
+  (rare) — pick that one character out of the password or use the toolchain
+  menu instead.
+- Want to go back to offline-only later? Restore the `YOUR_...` placeholders
+  and rebuild.
+
+### Getting a new firmware image from this file
+
+The repo cannot build firmware without the toolchain. Your options, easiest
+first:
+
+| Path | What's needed | How |
+| :--- | :--- | :--- |
+| **Ask whoever gave you the device** | a minute of their time | Send them the edited file; they run `idf.py build` and hand you a new `.bin` |
+| **One-time toolchain install (~45 min, guided)** | the Espressif installer (free, Windows/macOS/Linux) | Follow the official guide: <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/> then run the 5 commands in [Build](#2-build) |
+| **CI build** (GitHub Actions etc.) | a GitHub account | The repo can build on `ubuntu` in CI; push the edited file and download the built `mtg-rfid-companion.bin` artifact |
+
+### Flashing the new firmware (no toolchain needed)
+
+Flash using **Espressif Flash Download Tool** (graphical, no toolchain):
+<https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-setup-scratch.html#esp32-flash-download-tool>
+or `esptool.py` if you already have Python:
+
+```
+pip install esptool
+esptool.py -p COM3 --chip esp32 --before default_reset write_flash --flash_mode dio --flash_size 4MB 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 mtg-rfid-companion.bin
+```
+
+### TL;DR
+
+1. Edit `sdkconfig.defaults.esp32` → 2. rebuild (yours or someone's toolchain) →
+3. flash the `.bin` → 4. done. If you don't need your home Wi-Fi, **skip the
+   whole thing**: the device works standalone and has its own AP.
+
+---

 ### 4. Flash & watch

@@ -145,6 +244,10 @@ I web:     SoftAP 'MTG-Companion' at 192.168.4.1, web server ready
 I ui:      UI task on core 1
 ```

+> **RFID reader missing / not wired? That's OK.** A reader self-test failure no
+> longer aborts boot — the device logs a warning and continues into the display,
+> SoftAP and web-pairing screens without card scanning:
+
 ---

 ## Usage
@@ -159,11 +262,15 @@ Press the encoder button to toggle **SCANNER ↔ LIFE_COUNTER**. Rotate to adjus
 (20/40 preset or whatever you last set; press again to reset to the preset).

 ### Web pairing (registration mode)
-1. Connect your phone to the `MTG-Companion` access point.
+1. Connect your phone to the `MTG-Companion` access point. A phone with
+   cellular data keeps its mobile internet, so Scryfall autocomplete works;
+   otherwise type the name manually.
 2. Open `http://192.168.4.1`.
 3. Scan an unmapped card — the UID appears in the page.
 4. Type / pick a Scryfall-autocomplete name → **Pair UID with card**.
-5. The mapping persists to `/spiffs/mappings.json` and the card is fetched & cached.
+5. The mapping persists to `/spiffs/mappings.json`. The card data/art fetch
+   runs immediately if the device has Wi-Fi, or is picked up automatically by
+   the boot-time prefetch the next time you boot with Wi-Fi configured.

 ---

@@ -192,7 +299,9 @@ time (`littlefs_create_partition_image`), so a fresh flash already contains
 | Display = black / garbage | Check CS/DC/RST wiring; try toggling `esp_lcd_panel_invert_color` and `LCD_RGB_ELEMENT_ORDER_*` in `display_manager.c` |
 | Colors inverted | Same toggle as above — panel clones differ |
 | No UID printed on scan | Verify MFRC522 wiring, tag type (ISO14443A), antenna positioning; confirm `rfid: RC522 polling task pinned to Core 0` in the log |
+| Boot log: `rc522: FIFO length missmatch` / `RTOS: RFID unavailable` | Reader self-test failed. Check the MFRC522 has 3.3V power (many clones have a separate power pin), CS=GPIO5 / RST=GPIO22, and SCK/MOSI/MISO=18/23/19. Try lowering `RC522_SPI_CLK_HZ` in `rfid_manager.c` (e.g. `2000000`); some clones need a slower clock on a shared bus |
 | Wi-Fi never connects | Re-run `idf.py menuconfig`, confirm you replaced the `YOUR_...` placeholders |
+| Scryfall autocomplete shows nothing | The AP has no internet passthrough — the phone needs its own mobile data connection, or type the card name manually |
 | Can't reach 192.168.4.1 | Ensure your phone joined `MTG-Companion`, not a cached network |
 | Card renders but no art | Card not cached yet — check `scryfall` log lines; art downloads are best-effort |
 | App grows near 2MB | mbedTLS + HTTP pulls are large; if needed, enable `CONFIG_MBEDTLS_CERTIFICATE_BUNDLE` (smaller) |