READMEs for ESP32, and updated main README

README.md

@@ -1,6 +1,8 @@
 #  Crouton
 
-Crouton is a C++20 coroutine runtime library that provides some general purpose utilities, as well as cross-platform event loops, I/O and networking based on the [libuv][LIBUV], [mbedTLS][MBEDTLS] and [llhttp][LLHTTP] libraries. (On Apple platforms it can also use the system Network.framework.)
+**Crouton** is a C++20 coroutine runtime library that provides some general purpose concurrency utilities, as well as cross-platform event loops, I/O and networking that work the same way on Mac, Linux, Windows and ESP32 microcontrollers.
+
+The cross-platform support is based on the widely-used [libuv][LIBUV], [mbedTLS][MBEDTLS] and [llhttp][LLHTTP] libraries. (On Apple platforms it can also use the system Network.framework. On [ESP32][ESP32], where libuv is not supported, it uses lwip and FreeRTOS APIs instead.)
 
 A **Coroutine** is _a function that can return partway through, and then later be resumed where it left off._ Knuth wrote about them in the 1960s and they remained a curiosity for a long time, but they've since become widely used under the hood of the "async / await" concurrency model used in languages like JavaScript, C#, Rust, Nim, and Swift. Crouton brings this to C++.
 
@@ -53,15 +55,15 @@ How is that better than threads? It's safer and easier to reason about. The only
 
 * Core classes & APIs:
     * General-purpose `Error` and `Result<T>` types
-    * Logging, a thin wrapper around [spdlog][SPDLOG]
+    * Logging uses either a thin wrapper around [spdlog][SPDLOG], or a smaller compatible library I wrote.
 
 * Cross-Platform:
     * macOS (builds and passes tests)
       * iOS? ("It's still Darwin…")
     * Linux (builds and passes test)
       * Android? ("It's still Linux…")
+    * [ESP32][ESP32] embedded CPUs (builds and passes tests. File APIs not available yet.)
     * Windows (sometimes builds; not yet tested; help wanted!)
-    * Would very much like to support some embedded platforms like ESP32 (help wanted!)
 
 ## Example
 
@@ -86,11 +88,13 @@ cout << endl;
 
 See also [demo_server.cc](tests/demo_server.cc), a simple HTTP and WebSocket server.
 
+An example embedded app is at [tests/ESP32](tests/ESP32/README.md).
+
 ## Status: ☠️EXPERIMENTAL☠️
 
 [![Build](https://github.com/couchbaselabs/crouton/actions/workflows/build.yml/badge.svg)](https://github.com/couchbaselabs/crouton/actions/workflows/build.yml)
 
-This is new code, under heavy development! So far, it builds with Clang (Xcode 14) on macOS, GCC 12 on Ubuntu, and Visual Studio 17 2022 on Windows.
+This is new code, under heavy development! So far, it builds with Clang (Xcode 14) on macOS, GCC 12 on Ubuntu, Visual Studio 17 2022 on Windows, and ESP-IDF 5.0.
 
 The tests run regularly on macOS, and occasionally on Ubuntu (though not in CI.) Test coverage is very limited.
 
@@ -136,6 +140,9 @@ Then:
 - Select the `Tests` scheme and Run. 
 - To locate the binaries, choose Product > Show Build Folder In Finder
 
+### Building For ESP32 Embedded Systems
+
+The ESP-IDF component is at `src/io/esp32`; please see the [README](src/io/esp32/README.md) for details. A demo app is at [tests/ESP32](tests/ESP32/README.md).
 
 ## License(s)
 
@@ -171,3 +178,4 @@ Then:
 [BAKER]: https://lewissbaker.github.io/2022/08/27/understanding-the-compiler-transform
 [BSL]: src/io/blip/licences/BSL.txt
 [BLIP]: src/io/blip/README.md
+[ESP32]: https://www.espressif.com

crouton.xcodeproj/project.pbxproj

@@ -610,6 +610,8 @@
 		27B330822AB911470066C8DA /* demo_blipclient.cc */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.cpp; path = demo_blipclient.cc; sourceTree = "<group>"; };
 		27B330842AB912D30066C8DA /* BLIP.hh */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.h; path = BLIP.hh; sourceTree = "<group>"; };
 		27BA40742AA502DD0011BB86 /* Result.hh */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.h; path = Result.hh; sourceTree = "<group>"; };
+		27BCD2CE2AE73844009DFCED /* README.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = README.md; sourceTree = "<group>"; };
+		27BCD2CF2AE738DF009DFCED /* README.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; path = README.md; sourceTree = "<group>"; };
 		27E98EDE2AC2099E002F3D35 /* test_generator.cc */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.cpp; path = test_generator.cc; sourceTree = "<group>"; };
 		27E98EE02AC21940002F3D35 /* Awaitable.hh */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.h; path = Awaitable.hh; sourceTree = "<group>"; };
 		27ED1C702AABF47200ADC971 /* CoroLifecycle.hh */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.cpp.h; path = CoroLifecycle.hh; sourceTree = "<group>"; };
@@ -1061,6 +1063,7 @@
 		277B65322ADA07E0006F053D /* ESP32 */ = {
 			isa = PBXGroup;
 			children = (
+				27BCD2CF2AE738DF009DFCED /* README.md */,
 				277B65332ADA07E0006F053D /* sdkconfig */,
 				277B65362ADA07E0006F053D /* CMakeLists.txt */,
 				277B6C112ADA07E3006F053D /* main */,
@@ -1081,6 +1084,7 @@
 		277B6C222ADF25CD006F053D /* esp32 */ = {
 			isa = PBXGroup;
 			children = (
+				27BCD2CE2AE73844009DFCED /* README.md */,
 				277B6C232ADF2632006F053D /* CMakeLists.txt */,
 				277B6C1D2ADDBE82006F053D /* ESPBase.hh */,
 				277B6C1E2ADDDF13006F053D /* ESPBase.cc */,

src/io/esp32/README.md

@@ -0,0 +1,5 @@
+#  Crouton ESP32 Component
+
+This directory is a Component for the ESP-IDF embedded framework. To use it in your IDF-based project, add it to the root `CMakeLists.txt`'s `EXTRA_COMPONENT_DIRS` property.
+
+For an example, see the `tests/ESP32` directory.

tests/ESP32/CMakeLists.txt

@@ -2,11 +2,12 @@
 # CMakeLists in this exact order for cmake to work correctly
 cmake_minimum_required(VERSION 3.16)
 
-# This example uses an extra component for common functions such as Wi-Fi and Ethernet connection.
+# This example uses the `protocol_examples_common` component for Wi-Fi setup,
+# as well as the Crouton component (of course).
 set(EXTRA_COMPONENT_DIRS
     $ENV{IDF_PATH}/examples/common_components/protocol_examples_common
     ../../src/io/esp32
 )
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
-project(hello_world)
+project(hello_crouton)

tests/ESP32/README.md

@@ -0,0 +1,5 @@
+#  Crouton ESP32 Tests / Example
+
+This directory is an example project for using Crouton with the ESP-IDF embedded framework. You can build and run it with the usual `idf.py build flash monitor` invocation.
+
+You may need to run `idf.py menuconfig` once to change settings in the `sdkconfig` file, such as details of the CPU type or serial port speed, if your board is different enough from the ESP32-S3 I use.

tests/ESP32/main/main.cc

@@ -102,10 +102,10 @@ Task mainTask() {
 CROUTON_MAIN(mainTask)
 
 
-
+// entry point of the `protocol_examples_common` component
 extern "C" esp_err_t example_connect(void);
 
-// Taken from ESP-IDF "hello world" example
+// Adapted from ESP-IDF "hello world" example
 static void initialize() {
     printf("Hello world!\n");