diff --git a/KitchenSyncTouch/KitchenSyncTouch.ino b/KitchenSyncTouch/KitchenSyncTouch.ino index 7df9bee..d04a171 100644 --- a/KitchenSyncTouch/KitchenSyncTouch.ino +++ b/KitchenSyncTouch/KitchenSyncTouch.ino @@ -32,8 +32,15 @@ bool g_ap_mode = false; // true when serving the setup SoftAP static void start_ap(void) { g_ap_mode = true; WiFi.mode(WIFI_AP); - WiFi.softAP("KSTouch-Config"); + // ESP-044: the setup SSID was invisible a few feet from a Super Mini even though + // softAP() returned true. Two causes, both fixed here: AP-mode modem sleep can gate + // the beacon, and the Super Mini's PCB antenna is weak, so the radio must run at full + // power. Harmless on the Touch product board (better beacon there too). + WiFi.setSleep(false); + bool ok = WiFi.softAP("KSTouch-Config"); + WiFi.setTxPower(WIFI_POWER_19_5dBm); // max strlcpy(g_ks_host, "192.168.4.1", sizeof(g_ks_host)); // display shows this + if (!ok) Serial.println("[KSTouch] SoftAP start FAILED"); Serial.println("[KSTouch] SoftAP 'KSTouch-Config' @ 192.168.4.1 for setup"); } diff --git a/tasks/ESP-044.md b/tasks/ESP-044.md new file mode 100644 index 0000000..ccbe17c --- /dev/null +++ b/tasks/ESP-044.md @@ -0,0 +1,69 @@ +--- +id: ESP-044 +title: "Headless Super Mini: setup SoftAP invisible — force full TX power + no modem sleep" +status: done +assignee: null +priority: high +tags: + - kitchensynctouch + - wifi + - onboarding + - hardware +depends_on: + - ESP-042 +created_at: 2026-07-16 +updated_at: 2026-07-16 +--- + +## Why (the setup path was dead on the Super Mini) + +First-run provisioning depends on the device raising its `KSTouch-Config` SoftAP so the phone +can join it and the app can POST WiFi creds (T-026). On a headless S3 **Super Mini**, the AP was +**invisible to the phone even from a foot away** — the network never appeared in the WiFi list, +so onboarding could not start at all. + +The trap: **`WiFi.softAP()` returned `true`.** Boot logged the AP up at `192.168.4.1`, the board +was stable (no crash loop), and a diagnostic confirmed `start=1 ip=192.168.4.1 ch=1`. Everything +the firmware could see said "AP is up" — yet nothing radiated usably. + +Two compounding causes, neither visible from the API return value: + +1. **AP-mode modem sleep.** The STA path already sets `WiFi.setSleep(false)` (ESP notes: modem + sleep drops buffered multicast so Link never receives). The AP path did **not**, and modem + sleep can gate the beacon. +2. **The Super Mini's PCB antenna is weak.** These clones are known for a detuned/marginal + onboard antenna. At the default TX power the beacon didn't carry to a phone in the same room. + +Marginal USB power made it look worse (a thin cable browned the radio out on key-up and also +knocked the USB-CDC serial link down mid-session — `esptool` reported "serial TX path seems to +be down"). A solid data cable direct to the host removed that confound, but the AP was still +invisible until the two fixes below. + +## The fix + +In `start_ap()` (`KitchenSyncTouch.ino`): + +- `WiFi.setSleep(false)` before `softAP()` — no AP-mode modem sleep gating the beacon. +- `WiFi.setTxPower(WIFI_POWER_19_5dBm)` — run the radio at max; the weak clone antenna needs it. +- Keep a `softAP() == false` failure log (the old code logged success unconditionally, which is + exactly what hid this — the return value lies about *radiated* reachability, but a hard `false` + is still worth surfacing). + +`start_ap()` is shared with the **Touch product board**; both changes are harmless there (a +stronger, always-awake beacon), so the fix is unconditional rather than board-gated. + +## Verification + +- Reflashed the bench Super Mini (MAC `3c:0f:02:e2:b0:d4`), NVS erased + compile-time WiFi seed + blanked so it falls to `start_ap()`. Serial: `start=1 ... ch=1`, board stable. +- **`KSTouch-Config` now appears on the phone** after a WiFi rescan; onboarding proceeds. This + was confirmed on hardware — the previous behaviour (invisible) is gone. + +## Notes / follow-ups + +- This is a bring-up-only path (no saved WiFi). Shipped units still configure through the same + SoftAP + web/app form, so the fix is on the exact path a new buyer hits first. +- The invisible-AP-with-`start=1` symptom is worth remembering: `softAP()` truthiness ≠ the SSID + being reachable. TX power and modem sleep sit underneath it. +- Weak-antenna variance across Super Mini clones is real; if a unit is invisible even at full + power, treat the board's antenna as defective and swap it (bench stock exists).