From e5a57312ffd86fe8b2e715fb681c1a6fdf9d2fb6 Mon Sep 17 00:00:00 2001
From: Gorynych <48762816+StevenMagnet@users.noreply.github.com>
Date: Thu, 23 Jul 2026 18:29:12 +0300
Subject: [PATCH] docs: rewrite README for clearer discovery and onboarding

---
 README.md | 99 ++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 69 insertions(+), 30 deletions(-)

diff --git a/README.md b/README.md
index 1f0e51b..e1569a5 100644
--- a/README.md
+++ b/README.md
@@ -1,37 +1,76 @@
-## Build Instructions
-### Init dependencies
-It uses git submodules to manage dependencies.
+# Æthernet ESP32 Temperature Sensor
+
+Reference firmware for sending environmental sensor data from an ESP32 through Æthernet. The same codebase can be built as a desktop CMake project for development or as ESP-IDF firmware for supported ESP32 boards.
+
+[Æthernet C++ SDK](https://github.com/aethernetio/aether-client-cpp) · [Documentation](https://aethernet.io/documentation)
+
+## Supported build targets
+
+- desktop CMake build;
+- ESP-IDF;
+- PlatformIO with ESP-IDF;
+- ESP32-C6 DevKitC-1;
+- ESP32-S3 DevKitM-1;
+- ESP-WROVER-KIT.
+
+## Clone
+
+The project uses Git submodules:
+
+```bash
+git clone --recurse-submodules https://github.com/aethernetio/temperature-sensor.git
+cd temperature-sensor
 ```
-git submodule update --init --remote ./aether-client-cpp
+
+For an existing clone:
+
+```bash
+git submodule update --init --recursive
 ```
 
-### For desktop
-For desktop a regular cmake project is used.
-Make build directory, cd to it and configure cmake.
-```sh
-mkdir build
-cd build
-cmake ..
-cmake --build . --parallel
+## Desktop build
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build --parallel
 ```
 
-### ESP IDF
-For ESP IDF the same CMakeLists.txt is used.
-Make build directory, cd to it and configure cmake.
-ESP is using wifi connection for internet. Pass your ssid and password to cmake.
-```sh
-mkdir build
-cd build
-
-idf.py -C .. -B . set-target <write your board here>
-idf.py -C .. -B . build -DWIFI_SSID=<your_ssid> -DWIFI_PASSWORD=<your_password>
-idf.py -C .. -B . flash
+## ESP-IDF
+
+Make sure `IDF_PATH` is configured, then replace the board and Wi-Fi placeholders:
+
+```bash
+idf.py -C . -B build set-target esp32c6
+idf.py -C . -B build build \
+  -DWIFI_SSID="your-ssid" \
+  -DWIFI_PASSWORD="your-password"
+idf.py -C . -B build flash monitor
 ```
 
-### PlatformIO
-For PlatformIO the platformio.ini is provided.
-ESP is using wifi connection for internet.
-Edit platformio.ini to match your board and set ssid and password.
-```sh
-pio run -e <env_name> -t upload
-```
\ No newline at end of file
+Do not commit real Wi-Fi credentials.
+
+## PlatformIO
+
+Choose one of the environments defined in `platformio.ini`:
+
+```bash
+pio run -e esp32-c6-devkitc-1 -t upload
+pio device monitor
+```
+
+Before building, replace the placeholder Wi-Fi values in a local configuration. Avoid committing the modified credentials.
+
+## What this project demonstrates
+
+- integrating the Æthernet C++ client into ESP-IDF;
+- configuring filtered release builds for embedded targets;
+- collecting sensor data and delivering it through the Æthernet network;
+- sharing a codebase between desktop development and ESP32 firmware.
+
+## Troubleshooting
+
+Include the board, ESP-IDF or PlatformIO version, sensor model, build command, and serial log when opening an issue.
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE).