Release embassy-net v0.1

1 files changed, 45 insertions, 19 deletions

diff --git a/embassy-net/README.md b/embassy-net/README.md
index 470926c58..48f9fd832 100644
--- a/embassy-net/README.md
+++ b/embassy-net/README.md
@@ -1,30 +1,56 @@
 # embassy-net
 
-embassy-net contains an async network API based on smoltcp and embassy, designed
-for embedded systems.
+`embassy-net` is a no-std no-alloc async network stack, designed for embedded systems.
 
-## Running the example
+It builds on [`smoltcp`](https://github.com/smoltcp-rs/smoltcp). It provides a higher-level and more opinionated
+API. It glues together the components provided by `smoltcp`, handling the low-level details with defaults and
+memory management designed to work well for embedded systems, aiiming for a more "Just Works" experience.
 
-First, create the tap0 interface. You only need to do this once.
+## Features
 
-```sh
-sudo ip tuntap add name tap0 mode tap user $USER
-sudo ip link set tap0 up
-sudo ip addr add 192.168.69.100/24 dev tap0
-sudo ip -6 addr add fe80::100/64 dev tap0
-sudo ip -6 addr add fdaa::100/64 dev tap0
-sudo ip -6 route add fe80::/64 dev tap0
-sudo ip -6 route add fdaa::/64 dev tap0
-```
+- IPv4, IPv6
+- Ethernet and bare-IP mediums.
+- TCP, UDP, DNS, DHCPv4, IGMPv4
+- TCP sockets implement the `embedded-io` async traits.
 
-Second, have something listening there. For example `nc -l 8000`
+See the [`smoltcp`](https://github.com/smoltcp-rs/smoltcp) README for a detailed list of implemented and 
+unimplemented features of the network protocols. 
 
-Then run the example located in the `examples` folder:
+## Hardware support
 
-```sh
-cd $EMBASSY_ROOT/examples/std/
-cargo run --bin net -- --static-ip
-```
+- [`esp-wifi`](https://github.com/esp-rs/esp-wifi) for WiFi support on bare-metal ESP32 chips. Maintained by Espressif.
+- [`cyw43`](https://github.com/embassy-rs/embassy/tree/main/cyw43) for WiFi on CYW43xx chips, used in the Raspberry Pi Pico W
+- [`embassy-usb`](https://github.com/embassy-rs/embassy/tree/main/embassy-usb) for Ethernet-over-USB (CDC NCM) support.
+- [`embassy-stm32`](https://github.com/embassy-rs/embassy/tree/main/embassy-stm32) for the builtin Ethernet MAC in all STM32 chips (STM32F1, STM32F2, STM32F4, STM32F7, STM32H7, STM32H5).
+- [`embassy-net-w5500`](https://github.com/embassy-rs/embassy/tree/main/embassy-net-w5500) for Wiznet W5500 SPI Ethernet MAC+PHY chip.
+- [`embassy-net-esp-hosted`](https://github.com/embassy-rs/embassy/tree/main/embassy-net-esp-hosted) for using ESP32 chips with the [`esp-hosted`](https://github.com/espressif/esp-hosted) firmware as WiFi adapters for another non-ESP32 MCU.
+
+## Examples
+
+- For usage with Embassy HALs and network chip drivers, search [here](https://github.com/embassy-rs/embassy/tree/main/examples) for `eth` or `wifi`.
+- The [`esp-wifi` repo](https://github.com/esp-rs/esp-wifi) has examples for use on bare-metal ESP32 chips.
+- For usage on `std` platforms, see [the `std` examples](https://github.com/embassy-rs/embassy/tree/main/examples/std/src/bin)
+
+## Adding support for new hardware
+
+To add `embassy-net` support for new hardware (i.e. a new Ethernet or WiFi chip, or
+an Ethernet/WiFi MCU peripheral), you have to implement the [`embassy-net-driver`](https://crates.io/crates/embassy-net-driver)
+traits.
+
+Alternatively, [`embassy-net-driver-channel`](https://crates.io/crates/embassy-net-driver-channel) provides a higer-level API
+to construct a driver that processes packets in its own background task and communicates with the `embassy-net` task via
+packet queues for RX and TX.
+
+Drivers should depend only on `embassy-net-driver` or `embassy-net-driver-channel`. Never on the main `embassy-net` crate.
+This allows existing drivers to continue working for newer `embassy-net` major versions, without needing an update, if the driver
+trait has not had breaking changes.
+
+## Interoperability
+
+This crate can run on any executor.
+
+[`embassy-time`](https://crates.io/crates/embassy-net-driver) is used for timekeeping and timeouts. You must
+link an `embassy-time` driver in your project to use this crate.
 
 ## License