From 953ed3c7b18c4a2819762430a20bbbb144399b48 Mon Sep 17 00:00:00 2001 From: Ryan Summers Date: Fri, 31 Mar 2023 13:45:42 +0200 Subject: [PATCH] Readding reference docs --- README.md | 63 +++++++++++++++++++++++++++++++++++++----------------- src/lib.rs | 1 + src/tcp.rs | 28 ++++++++++++------------ src/udp.rs | 18 ++++++++-------- 4 files changed, 67 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index eb59ddf..b82ba44 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ of the SPI implementation. It must be set up to work as the W5500 chip requires * Clock speed: 33MHz maximum ```rust,no_run -use embedded_nal::{IpAddr, Ipv4Addr, SocketAddr, UdpClientStack}; +use embedded_nal::{IpAddr, Ipv4Addr, SocketAddr}; # # struct Mock; # @@ -75,30 +75,53 @@ use embedded_nal::{IpAddr, Ipv4Addr, SocketAddr, UdpClientStack}; # } # } -let mut spi = Mock; -let mut cs = Mock; +{ + use embedded_nal::UdpClientStack; -let mut device = w5500::UninitializedDevice::new(w5500::bus::FourWire::new(spi, cs)) - .initialize_manual( - w5500::MacAddress::new(0, 1, 2, 3, 4, 5), - Ipv4Addr::new(192, 168, 86, 79), - w5500::Mode::default() - ).unwrap(); + let mut spi = Mock; + let mut cs = Mock; -// Allocate a UDP socket to send data with -let mut socket = device.socket().unwrap(); + let mut device = w5500::UninitializedDevice::new(w5500::bus::FourWire::new(spi, cs)) + .initialize_manual( + w5500::MacAddress::new(0, 1, 2, 3, 4, 5), + Ipv4Addr::new(192, 168, 86, 79), + w5500::Mode::default() + ).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(); + // Allocate a UDP socket to send data with + let mut socket = device.socket().unwrap(); -// Send the data -nb::block!(device.send(&mut socket, &[104, 101, 108, 108, 111, 10])); + // 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(); -// Optionally close the socket and deactivate the device -device.close(socket); -let (spi_bus, inactive_device) = device.deactivate(); + // 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); + let (spi_bus, inactive_device) = device.deactivate(); +} + +// 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> = None; // maybe: previously initialized device + let mut socket: Option = None; // maybe: previously opened socket + + if let (Some(socket), Some(device)) = (socket.as_mut(), device.as_mut()) { + let mut buffer = [0u8; 1024]; + 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 diff --git a/src/lib.rs b/src/lib.rs index d3f9ff7..ccbe5f3 100644 --- a/src/lib.rs +++ b/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; diff --git a/src/tcp.rs b/src/tcp.rs index 986305e..7f1075c 100644 --- a/src/tcp.rs +++ b/src/tcp.rs @@ -65,13 +65,13 @@ impl TcpSocket { Ok(()) } - fn _close(&self, bus: &mut B) -> Result<(), TcpSocketError> { + fn socket_close(&self, bus: &mut B) -> Result<(), TcpSocketError> { self.socket.set_mode(bus, socketn::Protocol::Closed)?; self.socket.command(bus, socketn::Command::Close)?; Ok(()) } - fn _connect( + fn socket_connect( &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 { } } - fn _is_connected(&self, bus: &mut B) -> Result> { + fn socket_is_connected(&self, bus: &mut B) -> Result> { Ok(self.socket.get_status(bus)? == socketn::Status::Established as u8) } - fn _send( + fn socket_send( &mut self, bus: &mut B, data: &[u8], ) -> Result> { - 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( + fn socket_receive( &mut self, bus: &mut B, data: &mut [u8], ) -> Result> { - if !self._is_connected(bus)? { + if !self.socket_is_connected(bus)? { return Err(TcpSocketError::NotReady); } @@ -227,13 +227,13 @@ impl TcpClientStack for DeviceRefMut<'_, SpiBus, Ho }; // 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)?; + socket.socket_connect(&mut self.bus, remote)?; Ok(()) } fn is_connected(&mut self, socket: &Self::TcpSocket) -> Result { - socket._is_connected(&mut self.bus) + socket.socket_is_connected(&mut self.bus) } fn send( @@ -241,7 +241,7 @@ impl TcpClientStack for DeviceRefMut<'_, SpiBus, Ho socket: &mut Self::TcpSocket, buffer: &[u8], ) -> nb::Result { - let len = socket._send(&mut self.bus, buffer)?; + let len = socket.socket_send(&mut self.bus, buffer)?; Ok(len) } @@ -250,11 +250,11 @@ impl TcpClientStack for DeviceRefMut<'_, SpiBus, Ho socket: &mut Self::TcpSocket, buffer: &mut [u8], ) -> nb::Result { - 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(()) } diff --git a/src/udp.rs b/src/udp.rs index a2f2427..d0bbcb2 100644 --- a/src/udp.rs +++ b/src/udp.rs @@ -44,7 +44,7 @@ impl UdpSocket { Ok(()) } - fn _send( + fn socket_send( &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( + fn socket_send_to( &mut self, bus: &mut SpiBus, remote: SocketAddrV4, send_buffer: &[u8], ) -> NbResult<(), UdpSocketError> { 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( + fn socket_receive( &mut self, bus: &mut SpiBus, receive_buffer: &mut [u8], @@ -138,7 +138,7 @@ impl UdpSocket { Ok((packet_size, remote)) } - fn _close(&self, bus: &mut SpiBus) -> Result<(), UdpSocketError> { + fn socket_close(&self, bus: &mut SpiBus) -> Result<(), UdpSocketError> { self.socket.set_mode(bus, socketn::Protocol::Closed)?; self.socket.command(bus, socketn::Command::Close)?; Ok(()) @@ -267,7 +267,7 @@ where } 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(()) } @@ -276,11 +276,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(()) } @@ -327,7 +327,7 @@ where return Err(nb::Error::Other(Self::Error::UnsupportedAddress)) }; - socket._send_to(&mut self.bus, remote, buffer)?; + socket.socket_send_to(&mut self.bus, remote, buffer)?; Ok(()) } }