Mostly rewrite esp-hal/README.md (oops :) )

esp-hal/README.md

@@ -5,49 +5,51 @@
 ![Crates.io](https://img.shields.io/crates/l/esp-hal?labelColor=1C2C2E&style=flat-square)
 [![Matrix](https://img.shields.io/matrix/esp-rs:matrix.org?label=join%20matrix&labelColor=1C2C2E&color=BEC5C9&logo=matrix&style=flat-square)](https://matrix.to/#/#esp-rs:matrix.org)
 
-### Quickstart
+The `esp-hal` package aims to provide a safe, idiomatic Hardware Abstraction Layer (HAL) for the entire family of ESP32 devices from Espressif.
 
-[esp-hal] encompasses the hardware abstraction layer across multiple Espressif devices atop peripheral access crate. Implements a number of the traits defined by [embedded-hal](https://github.com/rust-embedded/embedded-hal) for both, blocking and async APIs. Blocking API is avalaible by default.
-To select a chip, the correct chip feature has to be used. The current list of chip features is `esp32`, `esp32c2`, `esp32c3`, `esp32c6`, `esp32h2`, `esp32p4`, `esp32s2`, and `esp32s3`.
+This package implements both blocking and, when able, asynchronous drivers for the various peripherals. At this time the blocking APIs are used by default, with all asynchronous functionality gated behind the `async` feature. See the package documentation for more information on its features.
 
-`esp-hal` is associated with different crates as well. [esp-lp-hal] is HAL for the low-power RISC-V coprocessors found on the ESP32-C6, ESP32-S2, and ESP32-S3 and is part of the [esp-hal](https://github.com/esp-rs/esp-hal) package. Another crates, supporting not only Wi-Fi and BLE that are not part of the [esp-hal](https://github.com/esp-rs/esp-hal) package could be found [here](https://github.com/esp-rs/esp-hal?tab=readme-ov-file#ancillary-crates).
+Most traits defined by the [embedded-hal] family of packages are implemented as applicable.
 
-The package tree is as follows:
-- [devices] holds the information about which `peripherals` are supported by the chip's hardware, `symbols` created by the maintainers to simplify writing drivers for multiple chips, and `efuse` description.
-- [ld] contains `linker-scripts` defining the layout of the chip's memory sections, specify the location of various symbols (such as ROM functions, for example).
-- [src] is a place, where _all_ peripheral drivers for main (high-power) core are placed. Each peripheral is separated into its own source file(s).
+[embedded-hal]: https://github.com/rust-embedded/embedded-hal
+
+## [Documentation]
+
+[documentation]: https://docs.rs/esp-hal/
 
 ## Usage
 
-Before using this `esp-hal`, be sure you [configured] the environment and [tooling] correctly.
-We **highly recommend** to use our [esp-template] that does all the basic configuration for you. If you want to try to run examples, the [xtask] should be used:
+Before using `esp-hal`, ensure that you have configured your [development environment] correctly, and the [required tooling] has been installed.
 
-`cargo xtask run-example examples esp32c3 hello_world`
+When starting a new project using `esp-hal`, we strongly recommend you generate a project skeleton using [cargo-generate] and [esp-template]. This will take much of the guesswork out of the process and give you a starting point to build an application form.
 
-> [!NOTE]
->
-> Please note, not all chips support the same set of peripherals.
+Much of the functionality available is feature-gated, so be sure to refer to the documentation to read about all available Cargo features.
 
-For more information about examples, see [examples].
+[development environment]: https://esp-rs.github.io/book/installation/index.html
+[required tooling]: https://esp-rs.github.io/book/tooling/espflash.html
+[cargo-generate]: https://github.com/cargo-generate/cargo-generate/
+[esp-template]: https://github.com/esp-rs/esp-template/
 
-[Embassy]: https://github.com/embassy-rs/embassy
-[esp-lp-hal]: https://github.com/esp-rs/esp-hal/tree/main/esp-lp-hal
-[ESP-HAL]: https://github.com/esp-rs/esp-hal
-[configured]: https://esp-rs.github.io/book/installation/index.html
-[tooling]: https://esp-rs.github.io/book/tooling/espflash.html
-[examples]: https://github.com/esp-rs/esp-hal/tree/main/examples
-[esp-template]: https://github.com/esp-rs/esp-template
-[template]: https://esp-rs.github.io/book/writing-your-own-application/generate-project/esp-template.html
-[esp-hal]: https://github.com/esp-rs/esp-hal/tree/main/esp-hal
-[devices]: https://github.com/esp-rs/esp-hal/tree/main/esp-hal/devices
-[ld]: https://github.com/esp-rs/esp-hal/tree/main/esp-hal/ld
-[src]: https://github.com/esp-rs/esp-hal/tree/main/esp-hal/src
-[xtask]: https://github.com/esp-rs/esp-hal/tree/main/xtask
-[examples]: https://github.com/esp-rs/esp-hal/tree/main/examples#examples
+### Supporting Packages
 
-## [Documentation]
+A number of additional packages are available which add additional functionality beyond the HAL.
 
-[documentation]: https://docs.rs/esp-hal/
+Within this repository, the [esp-lp-hal] package provides support for the (ultra-)low-power RISC-V coprocessors found aboard the ESP32-C6, ESP32-S2, and ESP32-S3.
+
+There is also the [esp-wifi] package, which provides support for Bluetooth and Wi-Fi.
+
+For additional libraries, you can check the [list of repositories] in the [esp-rs organization].
+
+[esp-lp-hal]: ../esp-lp-hal/
+[esp-wifi]: https://github.com/esp-rs/esp-wifi
+[list of repositories]: https://github.com/orgs/esp-rs/repositories
+[esp-rs organization]: https://github.com/esp-rs
+
+## Examples
+
+Examples demonstrating the use of various peripherals and features of the HAL are available in the [examples] package.
+
+[examples]: ../examples/
 
 ## License