Embassy
embassy-net

Crates

git

Versions

default

Flavors

Skip to main content

Crate embassy_net

Crate embassy_net 

Source
Expand description

§embassy-net

embassy-net is a no-std no-alloc async network stack, designed for embedded systems.

It uses the xarxa network stack, and adds convenient async wrappers on top of it and implements the main loop for you.

§Features

  • IPv4, IPv6
  • Ethernet, IP and IEEE 802.15.4 / 6LoWPAN mediums.
  • TCP, UDP, raw sockets, DNS, DHCPv4
  • TCP sockets implement the embedded-io async traits.
  • Multicast
  • Multiple interface support
  • Timestamping sent and received packets for e.g PTP

See the xarxa README for a detailed list of implemented and unimplemented features of the network protocols.

Embassy-net focuses on the network/transport layer protocols up to TCP. Higher-level application layer protocols live in other crates built on top of embassy-net:

§Hardware support

  • esp-radio for WiFi support ESP32 chips. Maintained by Espressif.
  • cyw43 for WiFi on CYW43xx chips, used in the Raspberry Pi Pico W
  • embassy-usb for Ethernet-over-USB (CDC NCM) support.
  • embassy-stm32 for the builtin Ethernet MAC in all STM32 chips (STM32F1, STM32F2, STM32F4, STM32F7, STM32H7, STM32H5).
  • embassy-net-wiznet for Wiznet SPI Ethernet MAC+PHY chips (W5100S, W5500)
  • embassy-net-enc28j60 for the Microchip ENC28J60 SPI Ethernet MAC+PHY chip.
  • embassy-net-adin1110 for the Analog Devices ADIN1110 SPI 10BASE-T1L single-pair Ethernet chip.
  • embassy-net-esp-hosted for using ESP32 chips with the esp-hosted firmware as WiFi adapters for another non-ESP32 MCU.
  • embassy-net-nrf91 for the cellular modem in Nordic nRF91-series chips.
  • embassy-net-ppp for PPP over Serial, useful with cellular modems or for a network link to a host computer.
  • embassy-nrf for IEEE 802.15.4 support on nrf chips.
  • embassy-stm32-wpan for IEEE 802.15.4 support on STM32WB chips.
  • embassy-net-tuntap for Linux TUN/TAP interfaces, useful for running on std platforms.

§Examples

  • For usage with Embassy HALs and network chip drivers, search here for eth or wifi.
  • The esp-hal repo has examples for use on bare-metal ESP32 chips.
  • For usage on std platforms, see the std examples

§Adding support for new hardware

To add embassy-net support for new hardware (i.e. a new Ethernet or WiFi chip, or an Ethernet/WiFi MCU peripheral), you have to implement the xarxa-driver Driver trait. Enable its async feature and implement Driver::register_waker: embassy-net needs it to sleep until the driver has something new.

Drivers should depend only on xarxa-driver. Never on the main embassy-net crate. This allows existing drivers to continue working for newer embassy-net major versions, without needing an update, if the driver trait has not had breaking changes.

§Interoperability

This crate can run on any executor.

embassy-time is used for timekeeping and timeouts. You must link an embassy-time driver in your project to use this crate.

§Feature flags

  • alloc — Enable APIs that use the heap.

§Protocol support

  • medium-ethernet — Support interfaces that send and receive Ethernet frames, with the link-layer machinery that goes with them (ARP, NDISC, the neighbor cache).
  • medium-ip — Support interfaces that send and receive bare IP packets, without a link-layer header.
  • medium-ieee802154 — Support IEEE 802.15.4 interfaces carrying 6LoWPAN (RFC 4944, RFC 6282). Needs ipv6.
  • sixlowpan-fragmentation — Fragment outgoing 6LoWPAN packets larger than one 802.15.4 frame. Needs medium-ieee802154.
  • sixlowpan-reassembly — Reassemble incoming 6LoWPAN fragments. Needs medium-ieee802154.
  • ipv4 — Support IPv4 (and, with medium-ethernet, ARP).
  • ipv4-fragmentation — Fragment outgoing IPv4 packets larger than the interface MTU. Needs ipv4.
  • ipv4-reassembly — Reassemble incoming IPv4 fragments. Needs ipv4.
  • ipv6 — Support IPv6 (and, with medium-ethernet, NDISC).
  • raw-ethernet — Ethernet-mode raw sockets: send and receive whole Ethernet frames. Needs medium-ethernet.
  • raw-ip — IP-mode raw sockets: send and receive whole IP packets.
  • udp — UDP sockets.
  • tcp — TCP sockets.
  • tcp-listener — TCP listeners, for accepting incoming connections.
  • dhcpv4 — DHCPv4 client, built into the interface. Needs ipv4 and medium-ethernet.
  • dhcpv4-options — Allow reading received DHCP options.
  • dhcpv4-server — DHCPv4 server, built into the interface. Needs ipv4 and medium-ethernet.
  • hostname — Give the stack a hostname, with Stack::set_hostname. If set, it is sent to the DHCP server in outgoing DHCP messages.
  • slaac — IPv6 stateless address autoconfiguration (SLAAC). Needs ipv6, and medium-ethernet or medium-ieee802154.
  • dns — DNS client.
  • embedded-nal — Implement the embedded-nal-async traits, with tcp::client::TcpClient and dns::DnsClient.
  • mdns — Resolve .local names with multicast DNS in the DNS client.
  • multicast — Join IP multicast groups, with IGMP (IPv4) and MLD (IPv6) membership reports.
  • tcp-timestamps — Send and receive the TCP timestamp option (RFC 7323).
  • tcp-sack — Send selective acknowledgement ranges (RFC 2018).
  • icmp-ping-reply — Automatically reply to pings (ICMP echo requests).
  • iface-bind — Bind sockets to an interface with bind_to_iface. A bound socket only receives packets that arrive on that interface, and only sends out of it.
  • icmp-errors — Deliver incoming ICMP error messages (destination unreachable, packet too big, …) to the sockets that provoked them.

§TCP congestion control

Enable one of these features to enable congestion control. No feature enabled means no congestion control. You may enable at most one.

  • tcp-reno — Use the Reno congestion control algorithm on TCP sockets.
  • tcp-cubic — Use the CUBIC congestion control algorithm on TCP sockets. Warning: it uses f64 arithmetic which can be slow and pull in soft-float code depending on the target.

§Packet metadata

  • packetmeta-id — Enable the PacketMeta::id field: an opaque number that travels with a packet through the whole stack.
  • packetmeta-timestamp — Enable the PacketMeta::timestamp and PacketMeta::request_timestamp fields, and Driver::poll_tx_timestamp.

§Logging

  • log — Log with the log crate.
  • defmt — Log with the defmt crate.
  • packet-log — Log every packet received and sent, decoded. Needs log or defmt to print anything.

Re-exports§

pub use xarxa_driver as driver;

Modules§

config
Compile-time configuration.
dns
DNS client compatible with the embedded-nal-async traits.
iface
Network interfaces.
raw
Raw sockets.
route
IP routing table.
tcp
TCP sockets.
udp
UDP sockets.
wire
Low-level packet access and construction.

Structs§

Full
A table, slab or queue has no room for another item.
Neighbor
A neighbor: the mapping of an on-link IP address to a hardware address.
NeighborCache
The stack’s neighbor cache, returned by Stack::neighbor_cache.
Runner
Network stack runner.
Stack
A network stack.
StackStorage
Memory storage needed for a network stack.

Enums§

NeighborState
State of a Neighbor entry.
TryError
Error returned by try_* socket methods.