From a0675e66bcb25cec9e70cdb415805a028b29108b Mon Sep 17 00:00:00 2001 From: Terastar-Paperclip Date: Mon, 11 May 2026 00:18:56 -0400 Subject: [PATCH 01/14] Lift boards canonical pin into a tier-based reference page Rewrite src/content/docs/nodes.md as a Diataxis-mode reference: dry, table-shaped, lookup-grade. Tier-1 picks (M5 Atom S3 Lite and M5 Stamp C3 Mate) surface at the top for first-time-buyer information scent; remaining branded boards land under chip-family subheads; "works with caveats" and "steer away" sections name the failure modes (including @maxi1134's 40-50% WiFi retry rate on generic dev boards) and cite the canonical pin #2334 plus the underlying source threads rather than re-aggregating them. Header notes the firmware version (v4.0.6) and verification date so the reference stays auditable. Co-Authored-By: Claude Opus 4.7 (1M context) --- src/content/docs/nodes.md | 146 ++++++++++++++++++++++++++------------ 1 file changed, 99 insertions(+), 47 deletions(-) diff --git a/src/content/docs/nodes.md b/src/content/docs/nodes.md index 85a7bc8b..4fb536d4 100644 --- a/src/content/docs/nodes.md +++ b/src/content/docs/nodes.md @@ -1,80 +1,132 @@ --- title: Nodes +description: Reference list of ESP32 boards that run ESPresense, organised by tier from first-time-buyer pick to steer-away. sidebar: order: 4 --- +> **Last verified against firmware v4.0.6** — 2026-05-11. Community-voiced board data and quotes are lifted from the canonical pin: [discussion #2334 — Boards: what works, what's flaky, what to avoid](https://github.com/ESPresense/ESPresense/discussions/2334). If a board you've run isn't listed, comment on that thread and we'll fold it in. -The firmware is currently compatible with the original ESP32, ESP32-C3, and the ESP32-S3. Generally C3 or S3 is recommended for new deployments. The C3 is nice and cheap and the RISC-V is fast! The S3 has better bluetooth range but is a bit more pricey. +## First-time buyer (tier 1) -It is not compatible with the ESP32-S2 (doesn't have bluetooth), ESP32-C6 (too new no support in our dev environment), or ESP8266 (old, no bluetooth). +If you've never deployed ESPresense before, buy one of these. Both are branded, enclosed (or stamp-form, not a bare clone PCB), ship with a 3D antenna, and the [browser installer](/firmware) picks the right firmware flavour automatically. :::note[Affiliate disclosure] Some store links on this page (Amazon, AliExpress) are affiliate links. As an Amazon Associate, ESPresense earns from qualifying purchases, at no extra cost to you. Affiliate revenue helps fund the project — see [Credits](/credits) for other ways to support. ::: -## ESP32-C3 +| Board | Chip | Why it's tier 1 | Stores | +|:------|:-----|:--------------------|:-------| +| **M5 Atom S3 Lite** | ESP32-S3 | First-timer pick: ~$15, enclosed, USB-C, status LED, 8 MB flash, noticeably better BT range than original ESP32 [^cdc] | [m5stack](https://docs.m5stack.com/en/core/AtomS3%20Lite) [ali](https://s.click.aliexpress.com/e/_oFSxCND) [amz/us](https://amzn.to/4v3qPFm) | +| **M5 Stamp C3 Mate** | ESP32-C3 | Cost-conscious pick: stamp form, RISC-V, runs cool, 4 MB flash, 3D antenna, RGB LED | [m5stack](https://shop.m5stack.com/products/m5stamp-c3-mate-with-pin-headers) [ali](https://s.click.aliexpress.com/e/_omweFp9) | -| Name | Stores | Notes | -|:--------------------|:------------:|-------| -| M5 Stamp C3 Mate | [m5stack](https://shop.m5stack.com/products/m5stamp-c3-mate-with-pin-headers) [ali](https://s.click.aliexpress.com/e/_omweFp9) | Stamp form factor w/ 4MB flash memory, built-in 3D antenna, RGB LED and button | -| M5 Stamp C3U Mate | [ali](https://s.click.aliexpress.com/e/_onkgbFp) | Stamp form factor w/ 4MB flash memory, built-in 3D antenna, RGB LED and button [^cdc] | -| ESP32-C3-DevKitM-1U | [ali](https://s.click.aliexpress.com/e/_c3bVwFQb) [amz/us](https://amzn.to/41WQXFa) | Espressif's official development board with ESP32-C3-MINI-1U module, 4MB flash, 160MHz CPU | +## Chip families -## ESP32-S3 +Pick a chip first, then a board within it. -| Name | Stores | Notes | -|:-------------------|:--------------:|-------| -| M5 Atom S3 Lite | [m5stack](https://docs.m5stack.com/en/core/AtomS3%20Lite) [ali](https://s.click.aliexpress.com/e/_oFSxCND) [amz/us](https://amzn.to/4v3qPFm) | 8MB flash memory, built-in 3D antenna, IR emitter, RGB LED, Button and GROVE interface [^cdc] | -| M5 Atom S3U | [ali](https://s.click.aliexpress.com/e/_c3bZmzLz) | USB-A w/ 8MB flash memory, built-in 3D antenna, IR emitter, PDM mic, RGB LED, Button and GROVE interface [^cdc] | -| M5 Stamp S3 | [ali](https://s.click.aliexpress.com/e/_oB3a0Dv) | Stamp form factor w/ 8MB flash memory, built-in 3D antenna, and RGB LED [^cdc] | -| Teyleten Robot | [ali](https://s.click.aliexpress.com/e/_c3JEwtzv) [amz/us](https://amzn.to/4jXMRUl) | 8MB flash and 2MB PSRAM dev board, sold as a 3-pack | +| Chip | Supported | Notes | +|:-----|:----------|:------| +| ESP32-S3 | yes — recommended for new deployments | 8 MB flash typical, BT 5.0 LE coded PHY, USB-CDC | +| ESP32-C3 | yes — recommended for cost-sensitive deployments | RISC-V, 4 MB flash typical | +| ESP32-C6 | yes | Newer RISC-V part with BT 5.3; firmware build available | +| Original ESP32 | yes | Still fully supported; stick to branded boards | +| ESP32-S2 | no | No Bluetooth radio | +| ESP8266 | no | No Bluetooth radio | -## ESP32 +## Community-tested (branded) -| Name | Stores | Notes | -|:--------------------|:--------------:|-------| -| M5 Atom (all kinds) | [ali](https://s.click.aliexpress.com/e/_oDWoyd1) [m5stack](https://shop.m5stack.com/collections/m5-controllers/products/atom-lite-esp32-development-kit) [digi](https://www.digikey.com/en/products/detail/m5stack-technology-co-ltd/C008/12088545) | The 3D antenna is much better | -| M5 Stamp Pico | [ali](https://s.click.aliexpress.com/e/_olAPbYT) [m5stack](https://shop.m5stack.com/collections/m5-controllers/products/m5stamp-pico-diy-kit) | Small and still has nice 3D antenna | -| Huzzah32 | [amz/us](https://amzn.to/4kWlmw4) | Much better quality than generic ESP32 dev boards | +Branded boards we actively point new users at. The [browser installer](/firmware) selects the right firmware flavour automatically. [^cdc] -## Works with caveats +### ESP32-S3 -| Name | Stores | Notes | -|:-------------------|:--------------:|-------| -| ESP32 dev board clones | [ali](https://s.click.aliexpress.com/e/_okTMXEr) [amz/us](https://amzn.to/4iWKv86) [amz/uk](https://amzn.to/4iyqHYK) | [^unbranded] No brand | -| D1 Mini ESP32 (Micro B) | [amz/us](https://amzn.to/3tlkK8D) | [^unbranded] No brand *Make sure you get the ESP32 NOT the ESP8266* | -| D1 Mini ESP32 (Type C) | [ali](https://s.click.aliexpress.com/e/_oC7KI4X) [amz/us](https://amzn.to/41VjFGq) | [^unbranded] No brand | -| LOLIN D32 ESP32 | [ali](https://s.click.aliexpress.com/e/_onxVPQX) | [^unbranded] No brand | -| M5Stick-C Plus | [ali](https://s.click.aliexpress.com/e/_oo2TM0P) [m5stack](https://shop.m5stack.com/collections/m5-controllers/products/m5stickc-plus-esp32-pico-mini-iot-development-kit) [amz/us](https://amzn.to/4iOzTZj) | These are great little devices, but their built-in battery makes them less ideal | +| Board | Stores | Notes | +|:------|:-------|:------| +| M5 Atom S3 Lite | [m5stack](https://docs.m5stack.com/en/core/AtomS3%20Lite) [ali](https://s.click.aliexpress.com/e/_oFSxCND) [amz/us](https://amzn.to/4v3qPFm) | Enclosed, USB-C. 8 MB flash, 3D antenna, IR emitter, RGB LED, button, GROVE [^cdc] | +| M5 Atom S3U | [ali](https://s.click.aliexpress.com/e/_c3bZmzLz) | Enclosed, USB-A. 8 MB flash, 3D antenna, IR emitter, PDM mic, RGB LED, button, GROVE [^cdc] | +| M5 Stamp S3 | [ali](https://s.click.aliexpress.com/e/_oB3a0Dv) | Stamp form. 8 MB flash, 3D antenna, RGB LED [^cdc] | +| Teyleten Robot S3 | [ali](https://s.click.aliexpress.com/e/_c3JEwtzv) [amz/us](https://amzn.to/4jXMRUl) | Dev board. 8 MB flash + 2 MB PSRAM. Sold as a 3-pack [^cdc] | -## USB C chargers +### ESP32-C3 -* [20W USB C Wall Charger](https://amzn.to/4kXGphK) - Small Fast Charger with Foldable Plug -* [20W USB C Wall Charger (3 pack)](https://amzn.to/4hFLcBz) -* [20W USB C Charger](https://s.click.aliexpress.com/e/_c4Myg1Bl) (AliExpress) - PD/QC 3.0 fast charger +| Board | Stores | Notes | +|:------|:-------|:------| +| M5 Stamp C3 Mate | [m5stack](https://shop.m5stack.com/products/m5stamp-c3-mate-with-pin-headers) [ali](https://s.click.aliexpress.com/e/_omweFp9) | Stamp form. 4 MB flash, 3D antenna, RGB LED, button | +| M5 Stamp C3U Mate | [ali](https://s.click.aliexpress.com/e/_onkgbFp) | Stamp form, USB-A. 4 MB flash, 3D antenna, RGB LED, button [^cdc] | +| ESP32-C3-DevKitM-1U | [ali](https://s.click.aliexpress.com/e/_c3bVwFQb) [amz/us](https://amzn.to/41WQXFa) | Espressif's dev board with ESP32-C3-MINI-1U module and U.FL connector. 4 MB flash, 160 MHz | -## USB C to C cables +### Original ESP32 -* [0.5ft USB C to C](https://amzn.to/4j02B9f) -* [15cm USB C to C](https://s.click.aliexpress.com/e/_c2vxVV1D) (AliExpress) - right angle, fast charging +| Board | Stores | Notes | +|:------|:-------|:------| +| M5 Atom (Lite / Echo / Matrix) | [ali](https://s.click.aliexpress.com/e/_oDWoyd1) [m5stack](https://shop.m5stack.com/collections/m5-controllers/products/atom-lite-esp32-development-kit) [digi](https://www.digikey.com/en/products/detail/m5stack-technology-co-ltd/C008/12088545) | Enclosed. The 3D antenna is much better than generic clones | +| M5 Stamp Pico | [ali](https://s.click.aliexpress.com/e/_olAPbYT) [m5stack](https://shop.m5stack.com/collections/m5-controllers/products/m5stamp-pico-diy-kit) | Stamp form. Small, still has a 3D antenna | +| Adafruit Huzzah32 | [amz/us](https://amzn.to/4kWlmw4) | Dev board. Branded, quality control unlike generic ESP32 dev boards | -## USB A chargers +## Works, with caveats -* [Dual USB A 3 pack](https://amzn.to/4iA0EAq) - 3-pack of dual-port USB-A chargers with compact cube design +These boards run ESPresense, but quality and RF behaviour vary. Use one you already own rather than buying a new one. **If a "with caveats" board misbehaves, reproduce on a tier‑1 board before opening a firmware issue** — RF problems on a marginal clone look identical to firmware bugs and burn a lot of triage time. -## USB A to C cables +| Board | Caveat | Source | +|:------|:-------|:-------| +| AZDelivery ESP32 NodeMCU (WROOM-32 module on a generic dev board) | Works but no brand QC | [#2334][p] / [#1567][1567], [#1577][1577] | +| Generic D1 Mini ESP32 (Micro-B and USB-C) | Multiple users report working in practice; same no-brand → no-QC caveat on the RF front-end | [#2334][p] / [#162][162] | +| LOLIN D32 ESP32 | Works; unbranded RF caveat | [#2334][p] | +| M5StickC Plus | Built-in battery is a liability for a fixed-in-place node | [#2334][p] | +| SEEEDSTUDIO XIAO ESP32-C3 | Runs on the `esp32C3` flavour. One report of a board overheating ([#1364][1364]); use a known-good USB-C cable and a real power supply | [#2334][p] / [#1364][1364] | -* [16ft 2 pack](https://amzn.to/3zzTTXW) -* [1ft 6 pack](https://amzn.to/3kyD8Is) -* [Straight Adapter 4 Pack](https://amzn.to/4hNrh3O) -* [Right Angle Adapter 4 Pack](https://amzn.to/4bWWH6o) +## Steer away -## USB-A to Micro-B cables +Each of these comes up often enough that it's worth saying plainly: -* [0.5 ft Micro USB Cable](https://amzn.to/4hzksTa) +- **Unbranded "ESP32 dev board" listings (Amazon / AliExpress).** Cheap and *usually* fine, but WiFi/BLE quality varies wildly and the failure is silent — the board flashes, joins WiFi, reports to MQTT, but RSSI is erratic and you can't tell whether tracking problems are firmware, calibration or a bad RF front-end. @maxi1134 reports a 40-50% WiFi-retry rate on generic ESP32 dev boards ([#1364][1364], summarised in [#2334][p]). For your first node, spend the extra few dollars on a branded board. +- **ESP32-CAM.** Not officially supported. Camera owns most of the GPIOs, tighter RAM, no maintained firmware variant. One community member keeps a fork working with source-side modifications ([#1347][1347]); we don't build for it. +- **ESP32-S2 / ESP8266.** No Bluetooth radio — physically can't run ESPresense. +- **NSPanel as a base station.** Open question. The chip is an ESP32, but no one has reported flashing ESPresense over the stock NSPanel firmware and getting both the touch UI and BT scanning working ([#1335][1335]). +- **GL-S10 Bluetooth IoT Gateway.** Not an ESP32 — MediaTek MT7621 with a separate BLE module — so the ESPresense firmware doesn't apply ([#1263][1263]). + +## Power and cabling + +### USB-C chargers + +* [20W USB-C Wall Charger](https://amzn.to/4kXGphK) — small fast charger with foldable plug +* [20W USB-C Wall Charger (3 pack)](https://amzn.to/4hFLcBz) +* [20W USB-C Charger (AliExpress)](https://s.click.aliexpress.com/e/_c4Myg1Bl) — PD/QC 3.0 + +### USB-C to C cables + +* [0.5 ft USB-C to C](https://amzn.to/4j02B9f) +* [15 cm USB-C to C, right angle (AliExpress)](https://s.click.aliexpress.com/e/_c2vxVV1D) + +### USB-A chargers + +* [Dual USB-A 3 pack](https://amzn.to/4iA0EAq) — compact cube design + +### USB-A to C cables + +* [16 ft, 2 pack](https://amzn.to/3zzTTXW) +* [1 ft, 6 pack](https://amzn.to/3kyD8Is) +* [Straight adapter 4 pack](https://amzn.to/4hNrh3O) +* [Right-angle adapter 4 pack](https://amzn.to/4bWWH6o) + +### USB-A to Micro-B cables + +* [0.5 ft Micro USB cable](https://amzn.to/4hzksTa) + +## See also + +* [Canonical pin #2334][p] — community discussion, raw quotes, source threads +* [Install Firmware](/firmware) — browser-based installer +* [Discord](https://discord.gg/jbqmn7V6n6) — faster human turnaround on board questions ## Footnotes -[^unbranded]: These are cheap, but no brand usually means no quality control, especially on the WiFi/BLE components -[^cdc]: Use CDC firmware flavor +[^cdc]: USB-CDC firmware flavour. The [browser installer](/firmware) selects this automatically; pick the `cdc` variant if you're flashing manually. + +[p]: https://github.com/ESPresense/ESPresense/discussions/2334 +[162]: https://github.com/ESPresense/ESPresense/discussions/162 +[1263]: https://github.com/ESPresense/ESPresense/discussions/1263 +[1335]: https://github.com/ESPresense/ESPresense/discussions/1335 +[1347]: https://github.com/ESPresense/ESPresense/discussions/1347 +[1364]: https://github.com/ESPresense/ESPresense/discussions/1364 +[1567]: https://github.com/ESPresense/ESPresense/discussions/1567 +[1577]: https://github.com/ESPresense/ESPresense/discussions/1577 From 2668d7225c3233a80b5016d65ab06edaa9478ec2 Mon Sep 17 00:00:00 2001 From: DTTerastar Date: Fri, 22 May 2026 20:37:16 -0400 Subject: [PATCH 02/14] docs(nodes): hyphenate pack-size modifiers in power-and-cabling links Compound modifiers ("3 pack", "2 pack", etc.) take a hyphen when they precede a noun. CodeRabbit nit, but worth fixing across the section. Co-Authored-By: Claude Opus 4.7 (1M context) Co-authored-by: Orca --- src/content/docs/nodes.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/docs/nodes.md b/src/content/docs/nodes.md index 4fb536d4..f33c1f0f 100644 --- a/src/content/docs/nodes.md +++ b/src/content/docs/nodes.md @@ -89,7 +89,7 @@ Each of these comes up often enough that it's worth saying plainly: ### USB-C chargers * [20W USB-C Wall Charger](https://amzn.to/4kXGphK) — small fast charger with foldable plug -* [20W USB-C Wall Charger (3 pack)](https://amzn.to/4hFLcBz) +* [20W USB-C Wall Charger (3-pack)](https://amzn.to/4hFLcBz) * [20W USB-C Charger (AliExpress)](https://s.click.aliexpress.com/e/_c4Myg1Bl) — PD/QC 3.0 ### USB-C to C cables @@ -99,14 +99,14 @@ Each of these comes up often enough that it's worth saying plainly: ### USB-A chargers -* [Dual USB-A 3 pack](https://amzn.to/4iA0EAq) — compact cube design +* [Dual USB-A 3-pack](https://amzn.to/4iA0EAq) — compact cube design ### USB-A to C cables -* [16 ft, 2 pack](https://amzn.to/3zzTTXW) -* [1 ft, 6 pack](https://amzn.to/3kyD8Is) -* [Straight adapter 4 pack](https://amzn.to/4hNrh3O) -* [Right-angle adapter 4 pack](https://amzn.to/4bWWH6o) +* [16 ft, 2-pack](https://amzn.to/3zzTTXW) +* [1 ft, 6-pack](https://amzn.to/3kyD8Is) +* [Straight adapter 4-pack](https://amzn.to/4hNrh3O) +* [Right-angle adapter 4-pack](https://amzn.to/4bWWH6o) ### USB-A to Micro-B cables From 878632682bb5fc9cac26ec8c80dd74c90e182ea1 Mon Sep 17 00:00:00 2001 From: DTTerastar Date: Fri, 22 May 2026 20:40:50 -0400 Subject: [PATCH 03/14] docs(nodes): drop reader-facing "Last verified" header MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tuck the firmware-version marker into an HTML comment instead of a header blockquote — readers don't care about doc-audit metadata. Co-Authored-By: Claude Opus 4.7 (1M context) Co-authored-by: Orca --- src/content/docs/nodes.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/content/docs/nodes.md b/src/content/docs/nodes.md index f33c1f0f..4530c212 100644 --- a/src/content/docs/nodes.md +++ b/src/content/docs/nodes.md @@ -5,7 +5,9 @@ sidebar: order: 4 --- -> **Last verified against firmware v4.0.6** — 2026-05-11. Community-voiced board data and quotes are lifted from the canonical pin: [discussion #2334 — Boards: what works, what's flaky, what to avoid](https://github.com/ESPresense/ESPresense/discussions/2334). If a board you've run isn't listed, comment on that thread and we'll fold it in. + + +Community-voiced board data and quotes are lifted from the canonical pin: [discussion #2334 — Boards: what works, what's flaky, what to avoid](https://github.com/ESPresense/ESPresense/discussions/2334). If a board you've run isn't listed, comment on that thread and we'll fold it in. ## First-time buyer (tier 1) From e0c0ff1ec7100ebf1e5bde85ce9196b422d81100 Mon Sep 17 00:00:00 2001 From: DTTerastar Date: Fri, 22 May 2026 20:57:23 -0400 Subject: [PATCH 04/14] docs(nodes): explain why RSSI consistency matters for ESPresense; clean HTML entities MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Steer-away bullet for unbranded boards now leads with the RSSI/fleet- calibration argument (and preempts the common "but these never drop in ESPHome" objection — ESPHome isn't doing RSSI distance estimation across a calibrated fleet). - "Works, with caveats" intro picks up the same thread: variable antenna QC makes Companion's room solver painful. - Replaces —,  , and ‑ with literal —, space, and -. CommonMark/Starlight render the literals fine and the source is much more readable. Co-Authored-By: Claude Opus 4.7 (1M context) Co-authored-by: Orca --- src/content/docs/nodes.md | 48 +++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/src/content/docs/nodes.md b/src/content/docs/nodes.md index 4530c212..16d21691 100644 --- a/src/content/docs/nodes.md +++ b/src/content/docs/nodes.md @@ -7,9 +7,9 @@ sidebar: -Community-voiced board data and quotes are lifted from the canonical pin: [discussion #2334 — Boards: what works, what's flaky, what to avoid](https://github.com/ESPresense/ESPresense/discussions/2334). If a board you've run isn't listed, comment on that thread and we'll fold it in. +Community-voiced board data and quotes are lifted from the canonical pin: [discussion #2334 — Boards: what works, what's flaky, what to avoid](https://github.com/ESPresense/ESPresense/discussions/2334). If a board you've run isn't listed, comment on that thread and we'll fold it in. -## First-time buyer (tier 1) +## First-time buyer (tier 1) If you've never deployed ESPresense before, buy one of these. Both are branded, enclosed (or stamp-form, not a bare clone PCB), ship with a 3D antenna, and the [browser installer](/firmware) picks the right firmware flavour automatically. @@ -17,10 +17,10 @@ If you've never deployed ESPresense before, buy one of these. Both are branded, Some store links on this page (Amazon, AliExpress) are affiliate links. As an Amazon Associate, ESPresense earns from qualifying purchases, at no extra cost to you. Affiliate revenue helps fund the project — see [Credits](/credits) for other ways to support. ::: -| Board | Chip | Why it's tier 1 | Stores | +| Board | Chip | Why it's tier 1 | Stores | |:------|:-----|:--------------------|:-------| -| **M5 Atom S3 Lite** | ESP32-S3 | First-timer pick: ~$15, enclosed, USB-C, status LED, 8 MB flash, noticeably better BT range than original ESP32 [^cdc] | [m5stack](https://docs.m5stack.com/en/core/AtomS3%20Lite) [ali](https://s.click.aliexpress.com/e/_oFSxCND) [amz/us](https://amzn.to/4v3qPFm) | -| **M5 Stamp C3 Mate** | ESP32-C3 | Cost-conscious pick: stamp form, RISC-V, runs cool, 4 MB flash, 3D antenna, RGB LED | [m5stack](https://shop.m5stack.com/products/m5stamp-c3-mate-with-pin-headers) [ali](https://s.click.aliexpress.com/e/_omweFp9) | +| **M5 Atom S3 Lite** | ESP32-S3 | First-timer pick: ~$15, enclosed, USB-C, status LED, 8 MB flash, noticeably better BT range than original ESP32 [^cdc] | [m5stack](https://docs.m5stack.com/en/core/AtomS3%20Lite) [ali](https://s.click.aliexpress.com/e/_oFSxCND) [amz/us](https://amzn.to/4v3qPFm) | +| **M5 Stamp C3 Mate** | ESP32-C3 | Cost-conscious pick: stamp form, RISC-V, runs cool, 4 MB flash, 3D antenna, RGB LED | [m5stack](https://shop.m5stack.com/products/m5stamp-c3-mate-with-pin-headers) [ali](https://s.click.aliexpress.com/e/_omweFp9) | ## Chip families @@ -28,8 +28,8 @@ Pick a chip first, then a board within it. | Chip | Supported | Notes | |:-----|:----------|:------| -| ESP32-S3 | yes — recommended for new deployments | 8 MB flash typical, BT 5.0 LE coded PHY, USB-CDC | -| ESP32-C3 | yes — recommended for cost-sensitive deployments | RISC-V, 4 MB flash typical | +| ESP32-S3 | yes — recommended for new deployments | 8 MB flash typical, BT 5.0 LE coded PHY, USB-CDC | +| ESP32-C3 | yes — recommended for cost-sensitive deployments | RISC-V, 4 MB flash typical | | ESP32-C6 | yes | Newer RISC-V part with BT 5.3; firmware build available | | Original ESP32 | yes | Still fully supported; stick to branded boards | | ESP32-S2 | no | No Bluetooth radio | @@ -43,18 +43,18 @@ Branded boards we actively point new users at. The [browser installer](/firmware | Board | Stores | Notes | |:------|:-------|:------| -| M5 Atom S3 Lite | [m5stack](https://docs.m5stack.com/en/core/AtomS3%20Lite) [ali](https://s.click.aliexpress.com/e/_oFSxCND) [amz/us](https://amzn.to/4v3qPFm) | Enclosed, USB-C. 8 MB flash, 3D antenna, IR emitter, RGB LED, button, GROVE [^cdc] | -| M5 Atom S3U | [ali](https://s.click.aliexpress.com/e/_c3bZmzLz) | Enclosed, USB-A. 8 MB flash, 3D antenna, IR emitter, PDM mic, RGB LED, button, GROVE [^cdc] | -| M5 Stamp S3 | [ali](https://s.click.aliexpress.com/e/_oB3a0Dv) | Stamp form. 8 MB flash, 3D antenna, RGB LED [^cdc] | -| Teyleten Robot S3 | [ali](https://s.click.aliexpress.com/e/_c3JEwtzv) [amz/us](https://amzn.to/4jXMRUl) | Dev board. 8 MB flash + 2 MB PSRAM. Sold as a 3-pack [^cdc] | +| M5 Atom S3 Lite | [m5stack](https://docs.m5stack.com/en/core/AtomS3%20Lite) [ali](https://s.click.aliexpress.com/e/_oFSxCND) [amz/us](https://amzn.to/4v3qPFm) | Enclosed, USB-C. 8 MB flash, 3D antenna, IR emitter, RGB LED, button, GROVE [^cdc] | +| M5 Atom S3U | [ali](https://s.click.aliexpress.com/e/_c3bZmzLz) | Enclosed, USB-A. 8 MB flash, 3D antenna, IR emitter, PDM mic, RGB LED, button, GROVE [^cdc] | +| M5 Stamp S3 | [ali](https://s.click.aliexpress.com/e/_oB3a0Dv) | Stamp form. 8 MB flash, 3D antenna, RGB LED [^cdc] | +| Teyleten Robot S3 | [ali](https://s.click.aliexpress.com/e/_c3JEwtzv) [amz/us](https://amzn.to/4jXMRUl) | Dev board. 8 MB flash + 2 MB PSRAM. Sold as a 3-pack [^cdc] | ### ESP32-C3 | Board | Stores | Notes | |:------|:-------|:------| -| M5 Stamp C3 Mate | [m5stack](https://shop.m5stack.com/products/m5stamp-c3-mate-with-pin-headers) [ali](https://s.click.aliexpress.com/e/_omweFp9) | Stamp form. 4 MB flash, 3D antenna, RGB LED, button | -| M5 Stamp C3U Mate | [ali](https://s.click.aliexpress.com/e/_onkgbFp) | Stamp form, USB-A. 4 MB flash, 3D antenna, RGB LED, button [^cdc] | -| ESP32-C3-DevKitM-1U | [ali](https://s.click.aliexpress.com/e/_c3bVwFQb) [amz/us](https://amzn.to/41WQXFa) | Espressif's dev board with ESP32-C3-MINI-1U module and U.FL connector. 4 MB flash, 160 MHz | +| M5 Stamp C3 Mate | [m5stack](https://shop.m5stack.com/products/m5stamp-c3-mate-with-pin-headers) [ali](https://s.click.aliexpress.com/e/_omweFp9) | Stamp form. 4 MB flash, 3D antenna, RGB LED, button | +| M5 Stamp C3U Mate | [ali](https://s.click.aliexpress.com/e/_onkgbFp) | Stamp form, USB-A. 4 MB flash, 3D antenna, RGB LED, button [^cdc] | +| ESP32-C3-DevKitM-1U | [ali](https://s.click.aliexpress.com/e/_c3bVwFQb) [amz/us](https://amzn.to/41WQXFa) | Espressif's dev board with ESP32-C3-MINI-1U module and U.FL connector. 4 MB flash, 160 MHz | ### Original ESP32 @@ -66,7 +66,7 @@ Branded boards we actively point new users at. The [browser installer](/firmware ## Works, with caveats -These boards run ESPresense, but quality and RF behaviour vary. Use one you already own rather than buying a new one. **If a "with caveats" board misbehaves, reproduce on a tier‑1 board before opening a firmware issue** — RF problems on a marginal clone look identical to firmware bugs and burn a lot of triage time. +These boards run ESPresense, but antenna and module QC vary — RSSI from one of these often won't agree with a branded board at the same distance, which makes fleet calibration harder and is a real problem for Companion's room solver. Use one you already own rather than buying a new one. **If a "with caveats" board misbehaves, reproduce on a tier-1 board before opening a firmware issue** — RF problems on a marginal clone look identical to firmware bugs and burn a lot of triage time. | Board | Caveat | Source | |:------|:-------|:-------| @@ -80,19 +80,19 @@ These boards run ESPresense, but quality and RF behaviour vary. Use one you alre Each of these comes up often enough that it's worth saying plainly: -- **Unbranded "ESP32 dev board" listings (Amazon / AliExpress).** Cheap and *usually* fine, but WiFi/BLE quality varies wildly and the failure is silent — the board flashes, joins WiFi, reports to MQTT, but RSSI is erratic and you can't tell whether tracking problems are firmware, calibration or a bad RF front-end. @maxi1134 reports a 40-50% WiFi-retry rate on generic ESP32 dev boards ([#1364][1364], summarised in [#2334][p]). For your first node, spend the extra few dollars on a branded board. +- **Unbranded "ESP32 dev board" listings (Amazon / AliExpress).** ESPresense uses RSSI as its primary input — every distance estimate and every Companion room solve assumes the fleet's readings agree with each other. Unbranded clones don't have consistent antenna designs even within a single product listing; two boards from the same batch routinely differ by several dB at the same distance, which translates to feet of error in the Companion floor plan. None of that matters for sensor/relay/presence projects like ESPHome, which is why *"these same cheap boards never drop with ESPHome"* is a common (and accurate, but irrelevant) objection — ESPHome isn't doing RSSI distance estimation across a calibrated fleet. The failure mode here is also silent: the board flashes, joins WiFi, reports to MQTT, but its RSSI numbers don't line up with the rest of the fleet and you can't tell whether bad tracking is firmware, calibration, or a bad RF front-end. @maxi1134 separately reports a 40-50% WiFi-retry rate on generic ESP32 dev boards ([#1364][1364], summarised in [#2334][p]). For any node you intend to calibrate against the fleet — and especially for Companion — spend the extra few dollars on a branded board. - **ESP32-CAM.** Not officially supported. Camera owns most of the GPIOs, tighter RAM, no maintained firmware variant. One community member keeps a fork working with source-side modifications ([#1347][1347]); we don't build for it. -- **ESP32-S2 / ESP8266.** No Bluetooth radio — physically can't run ESPresense. +- **ESP32-S2 / ESP8266.** No Bluetooth radio — physically can't run ESPresense. - **NSPanel as a base station.** Open question. The chip is an ESP32, but no one has reported flashing ESPresense over the stock NSPanel firmware and getting both the touch UI and BT scanning working ([#1335][1335]). -- **GL-S10 Bluetooth IoT Gateway.** Not an ESP32 — MediaTek MT7621 with a separate BLE module — so the ESPresense firmware doesn't apply ([#1263][1263]). +- **GL-S10 Bluetooth IoT Gateway.** Not an ESP32 — MediaTek MT7621 with a separate BLE module — so the ESPresense firmware doesn't apply ([#1263][1263]). ## Power and cabling ### USB-C chargers -* [20W USB-C Wall Charger](https://amzn.to/4kXGphK) — small fast charger with foldable plug +* [20W USB-C Wall Charger](https://amzn.to/4kXGphK) — small fast charger with foldable plug * [20W USB-C Wall Charger (3-pack)](https://amzn.to/4hFLcBz) -* [20W USB-C Charger (AliExpress)](https://s.click.aliexpress.com/e/_c4Myg1Bl) — PD/QC 3.0 +* [20W USB-C Charger (AliExpress)](https://s.click.aliexpress.com/e/_c4Myg1Bl) — PD/QC 3.0 ### USB-C to C cables @@ -101,7 +101,7 @@ Each of these comes up often enough that it's worth saying plainly: ### USB-A chargers -* [Dual USB-A 3-pack](https://amzn.to/4iA0EAq) — compact cube design +* [Dual USB-A 3-pack](https://amzn.to/4iA0EAq) — compact cube design ### USB-A to C cables @@ -116,9 +116,9 @@ Each of these comes up often enough that it's worth saying plainly: ## See also -* [Canonical pin #2334][p] — community discussion, raw quotes, source threads -* [Install Firmware](/firmware) — browser-based installer -* [Discord](https://discord.gg/jbqmn7V6n6) — faster human turnaround on board questions +* [Canonical pin #2334][p] — community discussion, raw quotes, source threads +* [Install Firmware](/firmware) — browser-based installer +* [Discord](https://discord.gg/jbqmn7V6n6) — faster human turnaround on board questions ## Footnotes From 9d4eabda160b63e03f4df845c4a60aa227607246 Mon Sep 17 00:00:00 2001 From: DTTerastar Date: Fri, 22 May 2026 21:27:47 -0400 Subject: [PATCH 05/14] docs(nodes): soften "browser installer auto-picks the firmware flavour" claim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The installer detects the chip family (esp-web-tools handshake) but the firmware *flavour* (including CDC variant) is a manual