esp32/README: Update the README details to account for newer chips.

Noted while adding C2 support that some of these comments are a bit out of
date. Spun out to its own commit, and also mention C5 as well.

This change also adds some recommendation on which ESP32 board to pick, as
we occasionally see issues or questions that would be non-issues on a board
with more RAM (and for small production or personal projects the savings of
picking a cheaper ESP32 chip are basically neglible).

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <angus@redyak.com.au>

1 files changed, 26 insertions, 5 deletions

diff --git a/ports/esp32/README.md b/ports/esp32/README.md
index 5a2bb9240..55964febe 100644
--- a/ports/esp32/README.md
+++ b/ports/esp32/README.md
@@ -5,16 +5,17 @@ This is a port of MicroPython to the Espressif ESP32 series of
 microcontrollers.  It uses the ESP-IDF framework and MicroPython runs as
 a task under FreeRTOS.
 
-Currently supports ESP32, ESP32-C2 (aka ESP8684), ESP32-C3, ESP32-C6, ESP32-S2
-and ESP32-S3 (ESP8266 is supported by a separate MicroPython port).
+Currently supports ESP32, ESP32-C2 (aka ESP8684), ESP32-C3, ESP32-C5, ESP32-C6,
+ESP32-S2 and ESP32-S3. ESP8266 is supported by a separate MicroPython port.
 
 Supported features include:
-- REPL (Python prompt) over UART0.
-- 16k stack for the MicroPython task and approximately 100k Python heap.
+- REPL (Python prompt) over UART0 and/or the integrated USB peripheral.
 - Many of MicroPython's features are enabled: unicode, arbitrary-precision
   integers, single-precision floats, complex numbers, frozen bytecode, as
   well as many of the internal modules.
-- Internal filesystem using the flash (currently 2M in size).
+- Internal filesystem using the remaining flash area.
+- Threading support via the _thread module (built on native FreeRTOS tasks),
+  with GIL enabled.
 - The machine module with GPIO, UART, SPI, software I2C, ADC, DAC, PWM,
   TouchPad, WDT and Timer.
 - The network module with WLAN (WiFi) support.
@@ -22,6 +23,26 @@ Supported features include:
 
 Initial development of this ESP32 port was sponsored in part by Microbric Pty Ltd.
 
+Choosing a suitable chip
+------------------------
+
+ESP32 chips are not all the same. The different ESP32 families have different
+capabilities and resources available. In particular, the ESP32-C2 and ESP32-S2
+(without external SPIRAM) have the least RAM. They can still run MicroPython
+well but may run out of RAM if a program uses a lot of resources, eg if it
+needs many complex code modules, multiple TLS connections, large memory
+buffers for a display, etc.
+
+ESP32 boards with external "SPIRAM" (also called PSRAM) have megabytes of RAM
+available - significantly more than any board without external SPIRAM. SPIRAM is
+supported on original ESP32, ESP32-S2 and ESP32-S3 chips. Not every ESP32 board
+has SPIRAM included, even if the chip supports it.
+
+If you don't need particular hardware features but are looking for a board with
+the usual Wi-Fi and BLE support, many peripherals and plenty of RAM then
+recommend finding a board based on ESP32-S3 with SPIRAM included (usually 2MB,
+4MB or 8MB).
+
 Setting up ESP-IDF and the build environment
 --------------------------------------------