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

main/main.c

@@ -21,8 +21,13 @@ void app_main(void)
     ESP_ERROR_CHECK(storage_manager_init());
     ESP_ERROR_CHECK(display_manager_init());
 
-    ESP_ERROR_CHECK(rfid_manager_init());
-    ESP_ERROR_CHECK(rfid_manager_start());
+    /* RFID is not fatal: the reader may be unpowered, unwired, or a clone
+     * that needs a slower SPI clock. Continue booting so the display, SoftAP
+     * and web pairing all stay usable; scanning is simply unavailable. */
+    esp_err_t ret = rfid_manager_init();
+    if (ret != ESP_OK || rfid_manager_start() != ESP_OK) {
+        ESP_LOGW(TAG, "RFID unavailable (%s) - continuing without card scanning", esp_err_to_name(ret));
+    }
 
     ESP_ERROR_CHECK(wifi_manager_init());
     ESP_ERROR_CHECK(wifi_manager_start());
@@ -31,7 +36,7 @@ void app_main(void)
 
     ESP_ERROR_CHECK(ui_task_start());
 
-    ESP_LOGI(TAG, "Boot sequence complete. Ready for Phase 7+.");
+    ESP_LOGI(TAG, "Boot sequence complete.");
 
     while (1) {
         vTaskDelay(pdMS_TO_TICKS(1000));

main/rfid_manager.c

@@ -21,6 +21,11 @@ static const char *TAG = "rfid";
 #define RC522_TASK_STACK_SIZE  (6 * 1024)
 #define RC522_TASK_PRIORITY    (4)
 
+/* Conservative clock for MFRC522 clones. If the FIFO self-test still
+ * reports a mismatch at boot, lower this (e.g. 2000000) or check power. */
+#define RC522_SPI_CLK_HZ (4000000)
+#define RC522_START_ATTEMPTS (3)
+
 static rc522_driver_handle_t s_driver;
 static rc522_handle_t s_scanner;
 
@@ -63,6 +68,7 @@ esp_err_t rfid_manager_init(void)
         .bus_config = NULL,
         .dev_config = {
             .spics_io_num = HW_RC522_CS_GPIO,
+            .clock_speed_hz = RC522_SPI_CLK_HZ,
         },
         .dma_chan = SPI_DMA_CH_AUTO,
         .rst_io_num = HW_RC522_RST_GPIO,
@@ -96,9 +102,21 @@ esp_err_t rfid_manager_init(void)
 
 esp_err_t rfid_manager_start(void)
 {
-    esp_err_t ret = rc522_start(s_scanner);
+    esp_err_t ret = ESP_FAIL;
+    for (int attempt = 1; attempt <= RC522_START_ATTEMPTS; attempt++) {
+        ret = rc522_start(s_scanner);
+        if (ret == ESP_OK) {
+            break;
+        }
+        ESP_LOGW(TAG, "rc522_start attempt %d/%d failed: %s",
+                 attempt, RC522_START_ATTEMPTS, esp_err_to_name(ret));
+        vTaskDelay(pdMS_TO_TICKS(250));
+    }
+
     if (ret != ESP_OK) {
-        ESP_LOGE(TAG, "rc522_start failed: %s", esp_err_to_name(ret));
+        ESP_LOGE(TAG, "MFRC522 self-test failed (%s). Check: reader powered "
+                      "(3.3V), SPI wiring (SCK=18/MOSI=23/MISO=19, CS=5, RST=22), "
+                      "and if it is a clone try lowering RC522_SPI_CLK_HZ", esp_err_to_name(ret));
         return ret;
     }
 

main/scryfall_client.c

@@ -360,16 +360,16 @@ static void net_task(void *arg)
 #ifndef CONFIG_MTG_WIFI_SSID
 #error "Missing CONFIG_MTG_WIFI_SSID"
 #endif
-    if (strlen(CONFIG_MTG_WIFI_SSID) > 0) {
+    if (wifi_manager_sta_configured()) {
         if (wifi_manager_wait_connected(pdMS_TO_TICKS(60000)) != ESP_OK) {
             ESP_LOGW(TAG, "Wi-Fi connect timed out, continuing without network");
+        } else {
+#ifdef CONFIG_MTG_SCAN_PREFETCH
+            prefetch_mappings();
+#endif
         }
     }
 
-#ifdef CONFIG_MTG_SCAN_PREFETCH
-    prefetch_mappings();
-#endif
-
     while (1) {
         fetch_request_t req;
         BaseType_t got = xQueueReceive(s_fetch_queue, &req, portMAX_DELAY);

main/wifi_manager.c

@@ -76,22 +76,32 @@ esp_err_t wifi_manager_init(void)
     return ESP_OK;
 }
 
+bool wifi_manager_sta_configured(void)
+{
+#ifndef CONFIG_MTG_WIFI_SSID
+    return false;
+#else
+    const char *ssid = CONFIG_MTG_WIFI_SSID;
+    return strlen(ssid) > 0 && strstr(ssid, "YOUR_") == NULL;
+#endif
+}
+
 esp_err_t wifi_manager_start(void)
 {
 #ifndef CONFIG_MTG_WIFI_SSID
 #error "Missing CONFIG_MTG_WIFI_SSID - run idf.py menuconfig"
 #endif
 
-    const char *ssid = CONFIG_MTG_WIFI_SSID;
-    const char *pass = CONFIG_MTG_WIFI_PASS;
-
     /* Empty SSID, or an untouched sdkconfig.defaults.esp32 placeholder:
      * keep station mode disabled so we don't hammer a bogus AP at boot. */
-    if (strlen(ssid) == 0 || strstr(ssid, "YOUR_") != NULL) {
+    if (!wifi_manager_sta_configured()) {
         ESP_LOGW(TAG, "no SSID configured - Wi-Fi station skipped (set CONFIG_MTG_WIFI_SSID)");
         return ESP_OK;
     }
 
+    const char *ssid = CONFIG_MTG_WIFI_SSID;
+    const char *pass = CONFIG_MTG_WIFI_PASS;
+
     wifi_config_t wifi_config = {
         .sta = {
             .threshold.authmode = WIFI_AUTH_WPA2_PSK,

main/wifi_manager.h

@@ -25,6 +25,12 @@ esp_err_t wifi_manager_init(void);
  */
 esp_err_t wifi_manager_start(void);
 
+/**
+ * @brief True if a real SSID is configured (non-empty, not the
+ *        `YOUR_...` placeholder). Station mode will actually run.
+ */
+bool wifi_manager_sta_configured(void);
+
 /**
  * @brief True if the STA has a valid IP.
  */