Merge pull request #43 from kellerkindt/rs/issue-36/trait-names

Renaming trait function names, cleaning up docs

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Add `defmt` features for enabling `defmt::Format` to most structs and errors by [@elpiel](https://github.com/elpiel) ([#39](https://github.com/kellerkindt/w5500/issues/39))
+- Fixed an issue where internal function names were conflicting with trait names by [@ryan-summers](https://github.com/ryan-summers) ([#36](https://github.com/kellerkindt/w5500/issues/36))
 
 ## [0.4.1] - January 2nd, 2023
 

README.md

@@ -29,49 +29,99 @@ of the SPI implementation.  It must be set up to work as the W5500 chip requires
 * Clock Phase: Sample leading edge
 * Clock speed: 33MHz maximum
 
-Initialization and usage of owned `Device`:
-```rust
-    let mut spi = ...; // SPI interface to use
-    let mut cs : OutputPin = ...; // chip select
+```rust,no_run
+use embedded_nal::{IpAddr, Ipv4Addr, SocketAddr};
+#
+# struct Mock;
+# 
+# impl embedded_hal::blocking::spi::Transfer<u8> for Mock {
+#     type Error = ();
+# 
+#     fn transfer<'w>(&mut self, words: &'w mut [u8]) -> Result<&'w [u8], Self::Error> {
+#         words[0] = 0x04;
+#         Ok(words)
+#     }
+# }
+# 
+# impl embedded_hal::spi::FullDuplex<u8> for Mock {
+#     type Error = ();
+# 
+#     fn read(&mut self) -> nb::Result<u8, Self::Error> {
+#         Ok(0)
+#     }
+# 
+#     fn send(&mut self, word: u8) -> nb::Result<(), Self::Error> {
+#         Ok(())
+#     }
+# }
+# 
+# impl embedded_hal::blocking::spi::Write<u8> for Mock {
+#     type Error = ();
+# 
+#     fn write(&mut self, words: &[u8]) -> Result<(), Self::Error> {
+#         Ok(())
+#     }
+# }
+# 
+# impl embedded_hal::digital::v2::OutputPin for Mock {
+#     type Error = ();
+# 
+#     fn set_low(&mut self) -> Result<(), Self::Error> {
+#         Ok(())
+#     }
+# 
+#     fn set_high(&mut self) -> Result<(), Self::Error> {
+#         Ok(())
+#     }
+# }
 
-    // alternative                     FourWireRef::new(&mut spi, &mut cs)
-    let device = UninitializedDevice::new(FourWire::new(spi, cs))
+{
+    use embedded_nal::UdpClientStack;
+
+    let mut spi = Mock;
+    let mut cs = Mock;
+
+    let mut device = w5500::UninitializedDevice::new(w5500::bus::FourWire::new(spi, cs))
             .initialize_manual(
-                    MacAddress::new(0, 1, 2, 3, 4, 5),
+                    w5500::MacAddress::new(0, 1, 2, 3, 4, 5),
                     Ipv4Addr::new(192, 168, 86, 79),
-                    Mode::default()
+                    w5500::Mode::default()
             ).unwrap();
 
-    let socket = device.socket();
-    socket.connect(
+    // Allocate a UDP socket to send data with
+    let mut socket = device.socket().unwrap();
+
+    // Connect the socket to the IP address and port we want to send to.
+    device.connect(&mut socket,
         SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 86, 38)), 8000),
     ).unwrap();
-    block!(interface.send(&mut socket, &[104, 101, 108, 108, 111, 10]));
+
+    // Send the data
+    nb::block!(device.send(&mut socket, &[104, 101, 108, 108, 111, 10]));
+
+    // Optionally close the socket and deactivate the device
     device.close(socket);
-
-    // optional
     let (spi_bus, inactive_device) = device.deactivate();
-```
+}
 
-Usage of borrowed SPI-Bus and previously initialized `Device`:
-```rust
-    let mut spi = ...; // SPI interface to use
-    let mut cs: OutputPin = ...; // chip select
+// Alternatively, you can use the W5500 where a SPI bus is shared between drivers:
+{
+    use embedded_nal::TcpClientStack;
+
+    let mut spi = Mock;
+    let mut cs = Mock;
+
+    let mut device: Option<w5500::InactiveDevice<w5500::Manual>> = None; // maybe: previously initialized device
+    let mut socket: Option<w5500::tcp::TcpSocket> = None; // maybe: previously opened socket
 
-    let mut device: Option<InactiveDevice<..>> = ...; // maybe: previously initialized device
-    let mut socket: Option<Socket> = ...; // maybe: previously opened socket
-    
     if let (Some(socket), Some(device)) = (socket.as_mut(), device.as_mut()) {
         let mut buffer = [0u8; 1024];
-        match device
-            // scoped activation & usage of the SPI bus without move
-            .activate_ref(FourWireRef::new(&mut spi, &mut cs))
-            .receive(socket, &mut buffer)
-        {
-            Ok(..) => todo!(),
-            Err(..) => todo!(),
-        }
+        let mut active = device.activate_ref(w5500::bus::FourWireRef::new(&mut spi, &mut cs));
+
+        // Read from the device.
+        active.receive(socket, &mut buffer).unwrap();
     }
+}
 ```
 ## Todo
 

src/lib.rs

@@ -1,6 +1,7 @@
 #![no_std]
 #![allow(unused)]
 #![deny(rustdoc::broken_intra_doc_links)]
+#![doc = include_str!("../README.md")]
 
 pub mod bus;
 mod device;

src/register.rs

@@ -13,7 +13,7 @@ pub mod common {
     pub const PHY_CONFIG: u16 = 0x2E;
     pub const VERSION: u16 = 0x39;
 
-    #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
+    #[derive(Default, Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
     #[repr(u8)]
     pub enum PhyOperationMode {
         /// 10BT half-duplex. Auto-negotiation disabled.
@@ -29,6 +29,7 @@ pub mod common {
         /// Power down mode.
         PowerDown = 0b110_000,
         /// All capable. Auto-negotiation enabled.
+        #[default]
         Auto = 0b111_000,
     }
 
@@ -38,12 +39,6 @@ pub mod common {
         }
     }
 
-    impl Default for PhyOperationMode {
-        fn default() -> PhyOperationMode {
-            PhyOperationMode::Auto
-        }
-    }
-
     #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
     #[repr(u8)]
     pub enum PhySpeedStatus {

src/tcp.rs

@@ -65,13 +65,13 @@ impl TcpSocket {
         Ok(())
     }
 
-    fn close<B: Bus>(&self, bus: &mut B) -> Result<(), TcpSocketError<B::Error>> {
+    fn socket_close<B: Bus>(&self, bus: &mut B) -> Result<(), TcpSocketError<B::Error>> {
         self.socket.set_mode(bus, socketn::Protocol::Closed)?;
         self.socket.command(bus, socketn::Command::Close)?;
         Ok(())
     }
 
-    fn connect<B: Bus>(
+    fn socket_connect<B: Bus>(
         &mut self,
         bus: &mut B,
         remote: SocketAddrV4,
@@ -89,7 +89,7 @@ impl TcpSocket {
             // All other cases are transient TCP states. For these, we need to reset the TCP
             // machinery to return to the INIT state.
             Ok(_) => {
-                self.close(bus)?;
+                self.socket_close(bus)?;
                 self.reopen(bus)?;
             }
         }
@@ -115,7 +115,7 @@ impl TcpSocket {
                 Ok(socketn::Status::Closed) => {
                     // For now, always return an open socket so that the user can re-connect with
                     // it in the future.
-                    self.close(bus)?;
+                    self.socket_close(bus)?;
                     return self.reopen(bus);
                 }
 
@@ -126,16 +126,16 @@ impl TcpSocket {
         }
     }
 
-    pub fn is_connected<B: Bus>(&self, bus: &mut B) -> Result<bool, TcpSocketError<B::Error>> {
+    fn socket_is_connected<B: Bus>(&self, bus: &mut B) -> Result<bool, TcpSocketError<B::Error>> {
         Ok(self.socket.get_status(bus)? == socketn::Status::Established as u8)
     }
 
-    fn send<B: Bus>(
+    fn socket_send<B: Bus>(
         &mut self,
         bus: &mut B,
         data: &[u8],
     ) -> Result<usize, TcpSocketError<B::Error>> {
-        if !self.is_connected(bus)? {
+        if !self.socket_is_connected(bus)? {
             return Err(TcpSocketError::NotReady);
         }
 
@@ -166,12 +166,12 @@ impl TcpSocket {
         Ok(write_data.len())
     }
 
-    fn receive<B: Bus>(
+    fn socket_receive<B: Bus>(
         &mut self,
         bus: &mut B,
         data: &mut [u8],
     ) -> Result<usize, TcpSocketError<B::Error>> {
-        if !self.is_connected(bus)? {
+        if !self.socket_is_connected(bus)? {
             return Err(TcpSocketError::NotReady);
         }
 
@@ -222,19 +222,18 @@ impl<SpiBus: Bus, HostImpl: Host> TcpClientStack for DeviceRefMut<'_, SpiBus, Ho
         socket: &mut Self::TcpSocket,
         remote: SocketAddr,
     ) -> nb::Result<(), Self::Error> {
-        if let SocketAddr::V4(remote) = remote {
-            // TODO dynamically select a random port
-            socket.open(&mut self.bus, 49849 + u16::from(socket.socket.index))?; // chosen by fair dice roll.
-            socket.connect(&mut self.bus, remote)?;
+        let SocketAddr::V4(remote) = remote else {
+            return Err(nb::Error::Other(Self::Error::UnsupportedAddress))
+        };
+        // TODO dynamically select a random port
+        socket.open(&mut self.bus, 49849 + u16::from(socket.socket.index))?; // chosen by fair dice roll.
+        socket.socket_connect(&mut self.bus, remote)?;
 
-            Ok(())
-        } else {
-            Err(nb::Error::Other(Self::Error::UnsupportedAddress))
-        }
+        Ok(())
     }
 
     fn is_connected(&mut self, socket: &Self::TcpSocket) -> Result<bool, Self::Error> {
-        socket.is_connected(&mut self.bus)
+        socket.socket_is_connected(&mut self.bus)
     }
 
     fn send(
@@ -242,7 +241,7 @@ impl<SpiBus: Bus, HostImpl: Host> TcpClientStack for DeviceRefMut<'_, SpiBus, Ho
         socket: &mut Self::TcpSocket,
         buffer: &[u8],
     ) -> nb::Result<usize, Self::Error> {
-        let len = socket.send(&mut self.bus, buffer)?;
+        let len = socket.socket_send(&mut self.bus, buffer)?;
         Ok(len)
     }
 
@@ -251,11 +250,11 @@ impl<SpiBus: Bus, HostImpl: Host> TcpClientStack for DeviceRefMut<'_, SpiBus, Ho
         socket: &mut Self::TcpSocket,
         buffer: &mut [u8],
     ) -> nb::Result<usize, Self::Error> {
-        Ok(socket.receive(&mut self.bus, buffer)?)
+        Ok(socket.socket_receive(&mut self.bus, buffer)?)
     }
 
     fn close(&mut self, socket: Self::TcpSocket) -> Result<(), Self::Error> {
-        socket.close(&mut self.bus)?;
+        socket.socket_close(&mut self.bus)?;
         self.release_socket(socket.socket);
         Ok(())
     }

src/udp.rs

@@ -44,7 +44,7 @@ impl UdpSocket {
         Ok(())
     }
 
-    fn send<SpiBus: Bus>(
+    fn socket_send<SpiBus: Bus>(
         &self,
         bus: &mut SpiBus,
         send_buffer: &[u8],
@@ -79,20 +79,20 @@ impl UdpSocket {
     }
 
     /// Sets a new destination before performing the send operation.
-    fn send_to<SpiBus: Bus>(
+    fn socket_send_to<SpiBus: Bus>(
         &mut self,
         bus: &mut SpiBus,
         remote: SocketAddrV4,
         send_buffer: &[u8],
     ) -> NbResult<(), UdpSocketError<SpiBus::Error>> {
         self.set_destination(bus, remote)?;
-        self.send(bus, send_buffer)
+        self.socket_send(bus, send_buffer)
     }
 
     /// Receive data and mutate the `receive_buffer`.
     ///
     /// If [`Interrupt::Receive`] is not set, it will always return [`NbError::WouldBlock`].
-    fn receive<SpiBus: Bus>(
+    fn socket_receive<SpiBus: Bus>(
         &mut self,
         bus: &mut SpiBus,
         receive_buffer: &mut [u8],
@@ -138,7 +138,10 @@ impl UdpSocket {
         Ok((packet_size, remote))
     }
 
-    fn close<SpiBus: Bus>(&self, bus: &mut SpiBus) -> Result<(), UdpSocketError<SpiBus::Error>> {
+    fn socket_close<SpiBus: Bus>(
+        &self,
+        bus: &mut SpiBus,
+    ) -> Result<(), UdpSocketError<SpiBus::Error>> {
         self.socket.set_mode(bus, socketn::Protocol::Closed)?;
         self.socket.command(bus, socketn::Command::Close)?;
         Ok(())
@@ -256,19 +259,18 @@ where
         socket: &mut Self::UdpSocket,
         remote: SocketAddr,
     ) -> Result<(), Self::Error> {
-        if let SocketAddr::V4(remote) = remote {
-            // TODO dynamically select a random port
-            socket.open(&mut self.bus, 49849 + u16::from(socket.socket.index))?; // chosen by fair dice roll.
-                                                                                 // guaranteed to be random.
-            socket.set_destination(&mut self.bus, remote)?;
-            Ok(())
-        } else {
-            Err(Self::Error::UnsupportedAddress)
-        }
+        let SocketAddr::V4(remote) = remote else {
+            return Err(Self::Error::UnsupportedAddress)
+        };
+        // TODO dynamically select a random port
+        socket.open(&mut self.bus, 49849 + u16::from(socket.socket.index))?; // chosen by fair dice roll.
+                                                                             // guaranteed to be random.
+        socket.set_destination(&mut self.bus, remote)?;
+        Ok(())
     }
 
     fn send(&mut self, socket: &mut Self::UdpSocket, buffer: &[u8]) -> nb::Result<(), Self::Error> {
-        socket.send(&mut self.bus, buffer)?;
+        socket.socket_send(&mut self.bus, buffer)?;
         Ok(())
     }
 
@@ -277,11 +279,11 @@ where
         socket: &mut Self::UdpSocket,
         buffer: &mut [u8],
     ) -> nb::Result<(usize, SocketAddr), Self::Error> {
-        Ok(socket.receive(&mut self.bus, buffer)?)
+        Ok(socket.socket_receive(&mut self.bus, buffer)?)
     }
 
     fn close(&mut self, socket: Self::UdpSocket) -> Result<(), Self::Error> {
-        socket.close(&mut self.bus)?;
+        socket.socket_close(&mut self.bus)?;
         self.release_socket(socket.socket);
         Ok(())
     }
@@ -324,11 +326,11 @@ where
         remote: SocketAddr,
         buffer: &[u8],
     ) -> nb::Result<(), Self::Error> {
-        if let SocketAddr::V4(remote) = remote {
-            socket.send_to(&mut self.bus, remote, buffer)?;
-            Ok(())
-        } else {
-            Err(nb::Error::Other(Self::Error::UnsupportedAddress))
-        }
+        let SocketAddr::V4(remote) = remote else {
+            return Err(nb::Error::Other(Self::Error::UnsupportedAddress))
+        };
+
+        socket.socket_send_to(&mut self.bus, remote, buffer)?;
+        Ok(())
     }
 }