Restructure and implement embedded-nal UDP traits

.github/workflows/rust.yml

@@ -65,4 +65,4 @@ jobs:
       - uses: actions-rs/cargo@v1
         with:
           command: clippy
-          args: -- -D warnings
+          args: -- -D warnings -A clippy::unknown-clippy-lints

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "w5500"
 version = "0.3.0"
-authors = ["Michael Watzko <michael@watzko.de>"]
+authors = ["Michael Watzko <michael@watzko.de>", "Jonah Dahlquist <hi@jonah.name>"]
 repository = "https://github.com/kellerkindt/w5500.git"
 description = "W5500 IoT Controller implementation. Currently UDP sending and receiving is working. WIP"
 keywords = ["embedded", "w5500", "iot", "arm", "embedded-hal-driver"]
@@ -13,4 +13,6 @@ edition = "2018"
 [dependencies]
 byteorder = { version = "1.3.4", default-features = false }
 embedded-hal = "0.2.4"
-nb = "0.1.2"
+embedded-nal = "0.4.0"
+bit_field = "0.10.1"
+nb = "1.0.0"

README.md

@@ -19,25 +19,9 @@ like this one.  Any microcontroller that implements the
 [`spi::FullDuplex<u8>`](https://docs.rs/embedded-hal/0.2.3/embedded_hal/spi/trait.FullDuplex.html) interface can use
 this driver.
 
-## Implementation
-
-This driver is built in several layers of structs.
-
-The lowest level (and the first a program would instantiate) is the `W5500` struct.  It contains a reference to the
-chip-select [pin](https://docs.rs/embedded-hal/0.2.3/embedded_hal/digital/v2/trait.OutputPin.html).
-
-The next layer is the `ActiveW5500` struct.  It contains a reference to a `W5500` instance, and an implementation of
-the [`spi::FullDuplex<u8>`](https://docs.rs/embedded-hal/0.2.3/embedded_hal/spi/trait.FullDuplex.html) trait.  It has
-the ability to actually communicate with the chip.  It has general methods for reading/writing to the chip, and
-higher-level functions that can set up specific configuration, like the MAC address, etc.
-
-The last layer is the network protocol.  Currently that is only `Udp`.  `Udp` is a tuple struct made up of an
-`ActiveW5500` and a `Socket`.  This last layer can be used to send and receive UDP packets over the network via the
-`receive` and `blocking_send` methods.
-
 # Example Usage
 
-Below is a basic example of listening for UDP packets and replying.  An important thing to confirm is the configuration
+Below is a basic example of sending UDP packets to a remote host.  An important thing to confirm is the configuration
 of the SPI implementation.  It must be set up to work as the W5500 chip requires.  That configuration is as follows:
 
 * Data Order: Most significant bit first
@@ -47,34 +31,16 @@ of the SPI implementation.  It must be set up to work as the W5500 chip requires
 
 ```rust
     let mut spi = ...; // SPI interface to use
-    let mut cs_w5500 : OutputPin = ...; // chip select
-
-    let mut w5500 = W5500::with_initialisation(
-        &mut cs_w5500, // borrowed for whole W5500 lifetime
-        &mut spi, // borrowed for call to `with_initialisation` only
-        OnWakeOnLan::Ignore,
-        OnPingRequest::Respond,
-        ConnectionType::Ethernet,
-        ArpResponses::Cache,
-    ).unwrap();
-
-    let mut active = w5500.activate(&mut spi).unwrap();
-    // using a 'locally administered' MAC address
-    active.set_mac(MacAddress::new(0x02, 0x01, 0x02, 0x03, 0x04, 0x05)).unwrap();
-    active.set_ip(IpAddress::new(192, 168, 0, 222)).unwrap();
-    active.set_subnet(IpAddress::new(255, 255, 255, 0)).unwrap();
-    active.set_gateway(IpAddress::new(192, 168, 0, 1)).unwrap();
+    let mut cs : OutputPin = ...; // chip select
 
-    let socket0: UninitializedSocket = active.take_socket(Socket::Socket0).unwrap();
-    let udp_server_socket = (&mut active, socket0).try_into_udp_server_socket(1234).unwrap();
-
-    let mut buffer = [0u8; 256];
-    let response = [104, 101, 108, 108, 111, 10];// "hello" as ASCII
-    loop {
-        if let Ok(Some((ip, port, len))) = (&mut active, udp_server_socket).receive(&mut buffer[..]) {
-            (&mut active, udp_server_socket).blocking_send(ip, port, response[..]).unwrap();
-        }
-    }
+    let device = UninitializedDevice::new(FourWire::new(spi, cs));
+    let device = device.initialize_manual(MacAddress::new(0, 1, 2, 3, 4, 5), Ipv4Addr::new(192, 168, 86, 79), Mode::default()).unwrap();
+    let socket = interface.socket();
+    socket.connect(
+        SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 86, 38)), 8000),
+    ).unwrap();
+    block!(interface.send(&mut socket, &[104, 101, 108, 108, 111, 10]));
+    interface.close(socket);
 ```
 
 ## Todo
@@ -83,7 +49,3 @@ In no particular order, things to do to improve this driver.
 
 * Add support for TCP
 * Add support for DHCP
-* Method to return socket back to the pool
-* Make reset safe by requiring that all sockets be returned to the pool first
-* Support a 3-wire SPI bus
-* Sane defaults for IP/Gateway/Subnet

src/bus/four_wire.rs

@@ -0,0 +1,87 @@
+#![allow(clippy::inconsistent_digit_grouping, clippy::unusual_byte_groupings)]
+
+use core::fmt;
+use embedded_hal::blocking::spi::{Transfer, Write};
+use embedded_hal::digital::v2::OutputPin;
+
+use crate::bus::Bus;
+
+const WRITE_MODE_MASK: u8 = 0b00000_1_00;
+
+// TODO This name is not ideal, should be renamed to VDM
+pub struct FourWire<Spi: Transfer<u8> + Write<u8>, ChipSelect: OutputPin> {
+    cs: ChipSelect,
+    spi: Spi,
+}
+
+impl<Spi: Transfer<u8> + Write<u8>, ChipSelect: OutputPin> FourWire<Spi, ChipSelect> {
+    pub fn new(spi: Spi, cs: ChipSelect) -> Self {
+        Self { spi, cs }
+    }
+
+    pub fn release(self) -> (Spi, ChipSelect) {
+        (self.spi, self.cs)
+    }
+}
+
+impl<Spi: Transfer<u8> + Write<u8>, ChipSelect: OutputPin> Bus for FourWire<Spi, ChipSelect> {
+    type Error =
+        FourWireError<<Spi as Transfer<u8>>::Error, <Spi as Write<u8>>::Error, ChipSelect::Error>;
+    fn read_frame(&mut self, block: u8, address: u16, data: &mut [u8]) -> Result<(), Self::Error> {
+        let address_phase = address.to_be_bytes();
+        let control_phase = block << 3;
+        let data_phase = data;
+        self.cs.set_low().map_err(FourWireError::ChipSelectError)?;
+        self.spi
+            .write(&address_phase)
+            .and_then(|_| self.spi.write(&[control_phase]))
+            .map_err(FourWireError::WriteError)?;
+        self.spi
+            .transfer(data_phase)
+            .map_err(FourWireError::TransferError)?;
+        self.cs.set_high().map_err(FourWireError::ChipSelectError)?;
+
+        Ok(())
+    }
+    fn write_frame(&mut self, block: u8, address: u16, data: &[u8]) -> Result<(), Self::Error> {
+        let address_phase = address.to_be_bytes();
+        let control_phase = block << 3 | WRITE_MODE_MASK;
+        let data_phase = data;
+        self.cs.set_low().map_err(FourWireError::ChipSelectError)?;
+        self.spi
+            .write(&address_phase)
+            .and_then(|_| self.spi.write(&[control_phase]))
+            .and_then(|_| self.spi.write(data_phase))
+            .map_err(FourWireError::WriteError)?;
+        self.cs.set_high().map_err(FourWireError::ChipSelectError)?;
+
+        Ok(())
+    }
+}
+
+// Must use map_err, ambiguity prevents From from being implemented
+#[repr(u8)]
+pub enum FourWireError<TransferError, WriteError, ChipSelectError> {
+    TransferError(TransferError),
+    WriteError(WriteError),
+    ChipSelectError(ChipSelectError),
+}
+
+impl<TransferError, WriteError, ChipSelectError> fmt::Debug
+    for FourWireError<TransferError, WriteError, ChipSelectError>
+{
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(
+            f,
+            "FourWireError::{}",
+            match self {
+                Self::TransferError(_) => "TransferError",
+                Self::WriteError(_) => "WriteError",
+                Self::ChipSelectError(_) => "ChipSelectError",
+            }
+        )
+    }
+}
+
+// TODO Improved error rendering could be done with specialization.
+// https://github.com/rust-lang/rust/issues/31844

src/bus/mod.rs

@@ -0,0 +1,15 @@
+use core::fmt::Debug;
+
+mod four_wire;
+mod three_wire;
+
+pub use self::four_wire::FourWire;
+pub use self::three_wire::ThreeWire;
+
+pub trait Bus {
+    type Error: Debug;
+
+    fn read_frame(&mut self, block: u8, address: u16, data: &mut [u8]) -> Result<(), Self::Error>;
+
+    fn write_frame(&mut self, block: u8, address: u16, data: &[u8]) -> Result<(), Self::Error>;
+}

src/bus/three_wire.rs

@@ -0,0 +1,128 @@
+#![allow(clippy::inconsistent_digit_grouping, clippy::unusual_byte_groupings)]
+
+use core::fmt;
+use embedded_hal::blocking::spi::{Transfer, Write};
+
+use crate::bus::Bus;
+
+const WRITE_MODE_MASK: u8 = 0b00000_1_0;
+
+const FIXED_DATA_LENGTH_MODE_1: u8 = 0b000000_01;
+const FIXED_DATA_LENGTH_MODE_2: u8 = 0b000000_10;
+const FIXED_DATA_LENGTH_MODE_4: u8 = 0b000000_11;
+
+// TODO This name is not ideal, should be renamed to FDM
+pub struct ThreeWire<Spi: Transfer<u8> + Write<u8>> {
+    spi: Spi,
+}
+
+impl<Spi: Transfer<u8> + Write<u8>> ThreeWire<Spi> {
+    pub fn new(spi: Spi) -> Self {
+        Self { spi }
+    }
+
+    pub fn release(self) -> Spi {
+        self.spi
+    }
+}
+
+impl<Spi: Transfer<u8> + Write<u8>> Bus for ThreeWire<Spi> {
+    type Error = ThreeWireError<<Spi as Transfer<u8>>::Error, <Spi as Write<u8>>::Error>;
+
+    /// Transfers a frame with an arbitrary data length in FDM
+    ///
+    /// This is done by passing chunks of fixed length 4, 2, or 1.  For example if a frame looks like this:
+    ///
+    /// (address 23) 0xF0 0xAB 0x83 0xB2 0x44 0x2C 0xAA
+    ///
+    /// This will be sent as separate frames in the chunks
+    ///
+    /// (address 23) 0xF0 0xAB 0x83 0xB2
+    /// (address 27) 44 2C
+    /// (address 29) AA
+    fn read_frame(
+        &mut self,
+        block: u8,
+        mut address: u16,
+        data: &mut [u8],
+    ) -> Result<(), Self::Error> {
+        let mut control_phase = block << 3;
+
+        let mut data_phase = &mut data[..];
+        let mut last_length_written: u16;
+        while !data_phase.is_empty() {
+            if data_phase.len() >= 4 {
+                control_phase |= FIXED_DATA_LENGTH_MODE_4;
+                last_length_written = 4;
+            } else if data_phase.len() >= 2 {
+                control_phase |= FIXED_DATA_LENGTH_MODE_2;
+                last_length_written = 2;
+            } else {
+                control_phase |= FIXED_DATA_LENGTH_MODE_1;
+                last_length_written = 1;
+            }
+
+            let address_phase = address.to_be_bytes();
+            self.spi
+                .write(&address_phase)
+                .and_then(|_| self.spi.write(&[control_phase]))
+                .map_err(ThreeWireError::WriteError)?;
+            self.spi
+                .transfer(&mut data_phase[..last_length_written as usize])
+                .map_err(ThreeWireError::TransferError)?;
+
+            address += last_length_written;
+            data_phase = &mut data_phase[last_length_written as usize..];
+        }
+        Ok(())
+    }
+
+    fn write_frame(&mut self, block: u8, mut address: u16, data: &[u8]) -> Result<(), Self::Error> {
+        let mut control_phase = block << 3 | WRITE_MODE_MASK;
+
+        let mut data_phase = &data[..];
+        let mut last_length_written: u16;
+        while !data_phase.is_empty() {
+            if data_phase.len() >= 4 {
+                control_phase |= FIXED_DATA_LENGTH_MODE_4;
+                last_length_written = 4;
+            } else if data_phase.len() >= 2 {
+                control_phase |= FIXED_DATA_LENGTH_MODE_2;
+                last_length_written = 2;
+            } else {
+                control_phase |= FIXED_DATA_LENGTH_MODE_1;
+                last_length_written = 1;
+            }
+
+            let address_phase = address.to_be_bytes();
+            self.spi
+                .write(&address_phase)
+                .and_then(|_| self.spi.write(&[control_phase]))
+                .and_then(|_| self.spi.write(&data_phase[..last_length_written as usize]))
+                .map_err(ThreeWireError::WriteError)?;
+
+            address += last_length_written;
+            data_phase = &data_phase[last_length_written as usize..];
+        }
+        Ok(())
+    }
+}
+
+// Must use map_err, ambiguity prevents From from being implemented
+pub enum ThreeWireError<TransferError, WriteError> {
+    TransferError(TransferError),
+    WriteError(WriteError),
+}
+
+impl<TransferError, WriteError> fmt::Debug for ThreeWireError<TransferError, WriteError> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(
+            f,
+            "ThreeWireError::{}",
+            match self {
+                Self::TransferError(_) => "TransferError",
+                Self::WriteError(_) => "WriteError",
+            }
+        )
+    }
+}