10 files changed, 150 insertions, 35 deletions

diff --git a/examples/std/Cargo.toml b/examples/std/Cargo.toml
index f00953167..449c5ddca 100644
--- a/examples/std/Cargo.toml
+++ b/examples/std/Cargo.toml
@@ -3,14 +3,15 @@ edition = "2021"
 name = "embassy-std-examples"
 version = "0.1.0"
 license = "MIT OR Apache-2.0"
+publish = false
 
 [dependencies]
-embassy-sync = { version = "0.6.2", path = "../../embassy-sync", features = ["log"] }
-embassy-executor = { version = "0.7.0", path = "../../embassy-executor", features = ["arch-std", "executor-thread", "log"] }
-embassy-time = { version = "0.4.0", path = "../../embassy-time", features = ["log", "std", ] }
-embassy-net = { version = "0.7.0", path = "../../embassy-net", features=[ "log", "medium-ethernet", "medium-ip", "tcp", "udp", "dns", "dhcpv4", "proto-ipv6"] }
+embassy-sync = { version = "0.7.2", path = "../../embassy-sync", features = ["log"] }
+embassy-executor = { version = "0.9.0", path = "../../embassy-executor", features = ["arch-std", "executor-thread", "log"] }
+embassy-time = { version = "0.5.0", path = "../../embassy-time", features = ["log", "std", ] }
+embassy-net = { version = "0.7.1", path = "../../embassy-net", features=[ "log", "medium-ethernet", "medium-ip", "tcp", "udp", "dns", "dhcpv4", "proto-ipv6"] }
 embassy-net-tuntap = { version = "0.1.0", path = "../../embassy-net-tuntap" }
-embassy-net-ppp = { version = "0.2.0", path = "../../embassy-net-ppp", features = ["log"]}
+embassy-net-ppp = { version = "0.2.1", path = "../../embassy-net-ppp", features = ["log"]}
 embedded-io-async = { version = "0.6.1" }
 embedded-io-adapters = { version = "0.6.1", features = ["futures-03"] }
 critical-section = { version = "1.1", features = ["std"] }
@@ -21,9 +22,14 @@ futures = { version = "0.3.17" }
 log = "0.4.14"
 nix = "0.26.2"
 clap = { version = "3.0.0-beta.5", features = ["derive"] }
-rand_core = { version = "0.6.3", features = ["std"] }
+rand_core = { version = "0.9.1", features = ["std", "os_rng"] }
 heapless = { version = "0.8", default-features = false }
 static_cell = "2"
 
 [profile.release]
 debug = 2
+
+[package.metadata.embassy]
+build = [
+  { artifact-dir = "out/examples/std" }
+]
diff --git a/examples/std/README.md b/examples/std/README.md
index dcc152fc2..ac2c2a1a6 100644
--- a/examples/std/README.md
+++ b/examples/std/README.md
@@ -1,19 +1,128 @@
 
 ## Running the `embassy-net` examples
 
-First, create the tap99 interface. (The number was chosen to
-hopefully not collide with anything.) You only need to do
-this once.
+To run `net`, `tcp_accept`, `net_udp` and `net_dns` examples you will need a tap interface. Before running these examples, create the tap99 interface. (The number was chosen to
+hopefully not collide with anything.) You only need to do this once every time you reboot your computer.
 
 ```sh
+cd $EMBASSY_ROOT/examples/std/
 sudo sh tap.sh
 ```
 
-Second, have something listening there. For example `nc -lp 8000`
+The example `net_ppp` requires different steps that are detailed in its section.
+
+### `net` example
+
+For this example, you need to have something listening in the correct port. For example `nc -lp 8000`.
 
 Then run the example located in the `examples` folder:
 
 ```sh
 cd $EMBASSY_ROOT/examples/std/
-sudo cargo run --bin net -- --tap tap99 --static-ip
+cargo run --bin net -- --tap tap99 --static-ip
+```
+### `tcp_accept` example
+
+This example listen for a tcp connection.
+
+First run the example located in the `examples` folder:
+
+```sh
+cd $EMBASSY_ROOT/examples/std/
+cargo run --bin tcp_accept -- --tap tap99 --static-ip
+```
+
+Then open a connection to the port. For example `nc 192.168.69.2 9999`.
+
+### `net_udp` example
+
+This example listen for a udp connection.
+
+First run the example located in the `examples` folder:
+
+```sh
+cd $EMBASSY_ROOT/examples/std/
+cargo run --bin net_udp -- --tap tap99 --static-ip
+```
+
+Then open a connection to the port. For example `nc -u 192.168.69.2 9400`.
+
+### `net_dns` example
+
+This example queries a `DNS` for the IP address of `www.example.com`.
+
+In order to achieve this, the `tap99` interface requires configuring tap99 as a gateway device temporarily.
+
+For example, in Ubuntu you can do this by:
+
+1. Identifying your default route device. In the next example `eth0`
+
+```sh
+ip r | grep "default"
+default via 192.168.2.1 dev eth0 proto kernel metric 35
+```
+
+2. Enabling temporarily IP Forwarding:
+
+```sh
+sudo sysctl -w net.ipv4.ip_forward=1
+```
+
+3. Configuring NAT to mascarade traffic from `tap99` to `eth0`
+
+```sh
+sudo iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
+sudo iptables -A FORWARD -i tap99 -j ACCEPT
+sudo iptables -A FORWARD -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT
+```
+
+4. Then you can run the example located in the `examples` folder:
+
+```sh
+cd $EMBASSY_ROOT/examples/std/
+cargo run --bin net_dns -- --tap tap99 --static-ip
+```
+
+### `net_ppp` example
+
+This example establish a Point-to-Point Protocol (PPP) connection that can be used, for example, for connecting to internet through a 4G modem via a serial channel.
+
+The example creates a PPP bridge over a virtual serial channel between `pty1` and `pty2` for the example code and a PPP server running on the same computer. 
+
+To run this example you will need:
+- ppp (pppd server)
+- socat (socket CAT)
+
+To run the examples you may follow the next steps:
+
+1. Save the PPP server configuration:
+```sh
+sudo sh -c 'echo "myuser $(hostname) mypass 192.168.7.10" >> /etc/ppp/pap-secrets'
+```
+
+2. Create a files `pty1` and `pty2` and link them 
+```sh
+cd $EMBASSY_ROOT/examples/std/
+socat -v -x PTY,link=pty1,rawer PTY,link=pty2,rawer
+```
+
+3. open a second terminal and start the PPP server:
+```sh
+cd $EMBASSY_ROOT/examples/std/
+sudo pppd $PWD/pty1 115200 192.168.7.1: ms-dns 8.8.4.4 ms-dns 8.8.8.8 nodetach debug local persist silent
+```
+
+4. Open a third terminal and run the example
+```sh
+cd $EMBASSY_ROOT/examples/std/
+RUST_LOG=trace cargo run --bin net_ppp -- --device pty2
+```
+5. Observe the output in the second and third terminal
+6. Open one last terminal to interact with `net_ppp` example through the PPP connection
+```sh
+# ping the net_ppp client
+ping 192.168.7.10
+# open an tcp connection
+nc 192.168.7.10 1234
+# Type anything and observe the output in the different terminals
 ```
diff --git a/examples/std/src/bin/net.rs b/examples/std/src/bin/net.rs
index 6e50b1a01..fd7b6c930 100644
--- a/examples/std/src/bin/net.rs
+++ b/examples/std/src/bin/net.rs
@@ -9,7 +9,7 @@ use embassy_time::Duration;
 use embedded_io_async::Write;
 use heapless::Vec;
 use log::*;
-use rand_core::{OsRng, RngCore};
+use rand_core::{OsRng, TryRngCore};
 use static_cell::StaticCell;
 
 #[derive(Parser)]
@@ -48,7 +48,7 @@ async fn main_task(spawner: Spawner) {
 
     // Generate random seed
     let mut seed = [0; 8];
-    OsRng.fill_bytes(&mut seed);
+    OsRng.try_fill_bytes(&mut seed).unwrap();
     let seed = u64::from_le_bytes(seed);
 
     // Init network stack
@@ -56,7 +56,7 @@ async fn main_task(spawner: Spawner) {
     let (stack, runner) = embassy_net::new(device, config, RESOURCES.init(StackResources::new()), seed);
 
     // Launch network task
-    spawner.spawn(net_task(runner)).unwrap();
+    spawner.spawn(net_task(runner).unwrap());
 
     // Then we can use it!
     let mut rx_buffer = [0; 4096];
@@ -95,6 +95,6 @@ fn main() {
 
     let executor = EXECUTOR.init(Executor::new());
     executor.run(|spawner| {
-        spawner.spawn(main_task(spawner)).unwrap();
+        spawner.spawn(main_task(spawner).unwrap());
     });
 }
diff --git a/examples/std/src/bin/net_dns.rs b/examples/std/src/bin/net_dns.rs
index a42c5dbb7..dff704b86 100644
--- a/examples/std/src/bin/net_dns.rs
+++ b/examples/std/src/bin/net_dns.rs
@@ -5,7 +5,7 @@ use embassy_net::{Config, Ipv4Address, Ipv4Cidr, StackResources};
 use embassy_net_tuntap::TunTapDevice;
 use heapless::Vec;
 use log::*;
-use rand_core::{OsRng, RngCore};
+use rand_core::{OsRng, TryRngCore};
 use static_cell::StaticCell;
 
 #[derive(Parser)]
@@ -45,7 +45,7 @@ async fn main_task(spawner: Spawner) {
 
     // Generate random seed
     let mut seed = [0; 8];
-    OsRng.fill_bytes(&mut seed);
+    OsRng.try_fill_bytes(&mut seed).unwrap();
     let seed = u64::from_le_bytes(seed);
 
     // Init network stack
@@ -53,7 +53,7 @@ async fn main_task(spawner: Spawner) {
     let (stack, runner) = embassy_net::new(device, config, RESOURCES.init(StackResources::new()), seed);
 
     // Launch network task
-    spawner.spawn(net_task(runner)).unwrap();
+    spawner.spawn(net_task(runner).unwrap());
 
     let host = "example.com";
     info!("querying host {:?}...", host);
@@ -78,6 +78,6 @@ fn main() {
 
     let executor = EXECUTOR.init(Executor::new());
     executor.run(|spawner| {
-        spawner.spawn(main_task(spawner)).unwrap();
+        spawner.spawn(main_task(spawner).unwrap());
     });
 }
diff --git a/examples/std/src/bin/net_ppp.rs b/examples/std/src/bin/net_ppp.rs
index f667e8d4c..82272c798 100644
--- a/examples/std/src/bin/net_ppp.rs
+++ b/examples/std/src/bin/net_ppp.rs
@@ -23,7 +23,7 @@ use futures::io::BufReader;
 use heapless::Vec;
 use log::*;
 use nix::sys::termios;
-use rand_core::{OsRng, RngCore};
+use rand_core::{OsRng, TryRngCore};
 use static_cell::StaticCell;
 
 use crate::serial_port::SerialPort;
@@ -89,7 +89,7 @@ async fn main_task(spawner: Spawner) {
 
     // Generate random seed
     let mut seed = [0; 8];
-    OsRng.fill_bytes(&mut seed);
+    OsRng.try_fill_bytes(&mut seed).unwrap();
     let seed = u64::from_le_bytes(seed);
 
     // Init network stack
@@ -102,8 +102,8 @@ async fn main_task(spawner: Spawner) {
     );
 
     // Launch network task
-    spawner.spawn(net_task(net_runner)).unwrap();
-    spawner.spawn(ppp_task(stack, runner, port)).unwrap();
+    spawner.spawn(net_task(net_runner).unwrap());
+    spawner.spawn(ppp_task(stack, runner, port).unwrap());
 
     // Then we can use it!
     let mut rx_buffer = [0; 4096];
@@ -160,6 +160,6 @@ fn main() {
 
     let executor = EXECUTOR.init(Executor::new());
     executor.run(|spawner| {
-        spawner.spawn(main_task(spawner)).unwrap();
+        spawner.spawn(main_task(spawner).unwrap());
     });
 }
diff --git a/examples/std/src/bin/net_udp.rs b/examples/std/src/bin/net_udp.rs
index 02d4d3efb..c5c4da65f 100644
--- a/examples/std/src/bin/net_udp.rs
+++ b/examples/std/src/bin/net_udp.rs
@@ -5,7 +5,7 @@ use embassy_net::{Config, Ipv4Address, Ipv4Cidr, StackResources};
 use embassy_net_tuntap::TunTapDevice;
 use heapless::Vec;
 use log::*;
-use rand_core::{OsRng, RngCore};
+use rand_core::{OsRng, TryRngCore};
 use static_cell::StaticCell;
 
 #[derive(Parser)]
@@ -44,7 +44,7 @@ async fn main_task(spawner: Spawner) {
 
     // Generate random seed
     let mut seed = [0; 8];
-    OsRng.fill_bytes(&mut seed);
+    OsRng.try_fill_bytes(&mut seed).unwrap();
     let seed = u64::from_le_bytes(seed);
 
     // Init network stack
@@ -52,7 +52,7 @@ async fn main_task(spawner: Spawner) {
     let (stack, runner) = embassy_net::new(device, config, RESOURCES.init(StackResources::new()), seed);
 
     // Launch network task
-    spawner.spawn(net_task(runner)).unwrap();
+    spawner.spawn(net_task(runner).unwrap());
 
     // Then we can use it!
     let mut rx_meta = [PacketMetadata::EMPTY; 16];
@@ -86,6 +86,6 @@ fn main() {
 
     let executor = EXECUTOR.init(Executor::new());
     executor.run(|spawner| {
-        spawner.spawn(main_task(spawner)).unwrap();
+        spawner.spawn(main_task(spawner).unwrap());
     });
 }
diff --git a/examples/std/src/bin/serial.rs b/examples/std/src/bin/serial.rs
index 10c85511d..1ed9997c4 100644
--- a/examples/std/src/bin/serial.rs
+++ b/examples/std/src/bin/serial.rs
@@ -50,6 +50,6 @@ fn main() {
 
     let executor = EXECUTOR.init(Executor::new());
     executor.run(|spawner| {
-        spawner.spawn(run()).unwrap();
+        spawner.spawn(run().unwrap());
     });
 }
diff --git a/examples/std/src/bin/tcp_accept.rs b/examples/std/src/bin/tcp_accept.rs
index 18646a083..77886f471 100644
--- a/examples/std/src/bin/tcp_accept.rs
+++ b/examples/std/src/bin/tcp_accept.rs
@@ -7,7 +7,7 @@ use embassy_time::{Duration, Timer};
 use embedded_io_async::Write as _;
 use heapless::Vec;
 use log::*;
-use rand_core::{OsRng, RngCore};
+use rand_core::{OsRng, TryRngCore};
 use static_cell::StaticCell;
 
 #[derive(Parser)]
@@ -46,7 +46,7 @@ async fn main_task(spawner: Spawner) {
 
     // Generate random seed
     let mut seed = [0; 8];
-    OsRng.fill_bytes(&mut seed);
+    OsRng.try_fill_bytes(&mut seed).unwrap();
     let seed = u64::from_le_bytes(seed);
 
     // Init network stack
@@ -54,7 +54,7 @@ async fn main_task(spawner: Spawner) {
     let (stack, runner) = embassy_net::new(device, config, RESOURCES.init(StackResources::new()), seed);
 
     // Launch network task
-    spawner.spawn(net_task(runner)).unwrap();
+    spawner.spawn(net_task(runner).unwrap());
 
     // Then we can use it!
     let mut rx_buffer = [0; 4096];
@@ -101,6 +101,6 @@ fn main() {
 
     let executor = EXECUTOR.init(Executor::new());
     executor.run(|spawner| {
-        spawner.spawn(main_task(spawner)).unwrap();
+        spawner.spawn(main_task(spawner).unwrap());
     });
 }
diff --git a/examples/std/src/bin/tick.rs b/examples/std/src/bin/tick.rs
index f23cf3549..16b82c82b 100644
--- a/examples/std/src/bin/tick.rs
+++ b/examples/std/src/bin/tick.rs
@@ -17,5 +17,5 @@ async fn main(spawner: Spawner) {
         .format_timestamp_nanos()
         .init();
 
-    spawner.spawn(run()).unwrap();
+    spawner.spawn(run().unwrap());
 }
diff --git a/examples/std/tap.sh b/examples/std/tap.sh
index 39d92a099..fb89d2381 100644
--- a/examples/std/tap.sh
+++ b/examples/std/tap.sh
@@ -1,4 +1,4 @@
-ip tuntap add name tap99 mode tap user $USER
+ip tuntap add name tap99 mode tap user $SUDO_USER
 ip link set tap99 up
 ip addr add 192.168.69.100/24 dev tap99
 ip -6 addr add fe80::100/64 dev tap99