Skip to content

Latest commit

 

History

History
76 lines (59 loc) · 4.33 KB

README.md

File metadata and controls

76 lines (59 loc) · 4.33 KB
Raw

edge-nal

CI crates.io Documentation

Hosts a bunch of networking (UDP, TCP and raw ethernet) traits.

Differences with embedded-nal-async

TCP

  • Factory traits for the creation of TCP server sockets - TcpBind and TcpAccept. embedded-nal-async only has TcpConnect
  • Splittable sockets with TcpSplit (can be optionally implemented by TcpConnect and TcpAccept)
  • Socket shutdown with TcpShutdown

UDP

  • Separate UdpSend and UdpReceive traits for modeling the sending / receiving functinality of a UDP socket. Necessary for protocols that need UDP socket splitting, like mDNS responder
  • Binding to a UDP socket and connecting to a UDP socket modeled with separate traits - UdpBind and UdpConnect, as not all platforms currently have capabilities to connect to a UDP socket (i.e. the networking stack of Embassy)
  • Returning the local address of a UDP socket bind / connect operation is not supported, as not all platforms currently have this capability (i.e. the networking stack of Embassy)
  • "Unbound" UDP sockets are currently not supported, as not all platforms have these capabilities (i.e. the networking stack of Embassy). Also, I've yet to find a good use case for these.
  • Splittable sockets with UdpSplit
  • MulticastV4 and MulticastV6 traits for joining / leaving IPv4 and IPv6 multicast groups (can be optionally implemented by UdpConnect and UdpBind)
  • Readable trait for waiting until a socket becomes readable

Justification

These traits are necessary to unlock the full functionality of some crates in edge-net, which is not possible with the current traits of embedded-nal-async.

Namely:

  • edge-mdns - needs UDP multicast capabilities as well as socket splitting
  • edge-dhcp - needs raw ethernet socket capabilities or at least sending/receiving UDP packets to/from peers identified by their MAC addresses rather than by their IP addresses
  • edge-http - (full server only) needs a way to bind to a server-side TCP socket
  • edge-ws - Most WebSocket use cases do require a splittable TCP socket (separate read and write halves)

Traits

TCP

  • TcpSplit
    • A trait that - when implemented on a TCP socket - allows for splitting the send and receive halves of the socket for full-duplex functionality
  • TcpConnect
    • Client-side TCP socket factory similar in spirit to STD's std::net::TcpListener::connect method
  • TcpBind
    • Server-side TCP socket factory similar in spirit to STD's std::net::TcpListener::bind method and std::net::TcpListener struct
  • TcpAccept
    • The acceptor of the server-side TCP socket factory similar in spirit to STD's std::net::TcpListener::bind method and std::net::TcpListener struct

UDP

  • UdpReceive
    • The receiver half of a UDP socket
  • UdpSend
    • The sender half of a UDP socket
  • UdpSplit
    • A trait that - when implemented on a UDP socket - allows for splitting the send and receive halves of the socket for full-duplex functionality
  • UdpBind
    • Udp socket factory similar in spirit to STD's std::net::UdpSocket::bind method
  • UdpConnect
    • Udp socket factory similar in spirit to STD's std::net::UdpSocket::connect method
  • Multicastv4 and MulticastV6
    • Extra traits for UDP sockets allowing subscription to multicast groups
  • Readable
    • Extra trait for UDP, TCP and raw sockets allowing one to wait until the socket becomes readable

Traits for sending/receiving raw ethernet payloads (a.k.a. raw sockets)

  • RawReceive
    • The receiver half of a raw socket
  • RawSend
    • The sender half of a raw socket
  • RawSplit
    • A trait that - when implemented on a raw socket - allows for splitting the send and receive halves of the socket for full-duplex functionality
  • RawBind
    • A raw socket factory