Crate embassy_net

embassy-net

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

It builds on smoltcp. It provides a higher-level and more opinionated API. It glues together the components provided by smoltcp, handling the low-level details with defaults and memory management designed to work well for embedded systems, aiming for a more “Just Works” experience.

Features

• IPv4, IPv6
• Ethernet and bare-IP mediums.
• TCP, UDP, DNS, DHCPv4, IGMPv4
• TCP sockets implement the embedded-io async traits.

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

Hardware support

• esp-wifi for WiFi support on bare-metal 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-esp-hosted for using ESP32 chips with the esp-hosted firmware as WiFi adapters for another non-ESP32 MCU.

Examples

• For usage with Embassy HALs and network chip drivers, search here for eth or wifi.
• The esp-wifi 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 embassy-net-driver traits.

Alternatively, embassy-net-driver-channel provides a higer-level API to construct a driver that processes packets in its own background task and communicates with the embassy-net task via packet queues for RX and TX.

Drivers should depend only on embassy-net-driver or embassy-net-driver-channel. 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

• defmt — Enable defmt
• packet-trace — Trace all raw received and transmitted packets using defmt or log.

Many of the following feature flags are re-exports of smoltcp feature flags. See the smoltcp feature flag documentation for more details

• udp — Enable UDP support
• tcp — Enable TCP support
• dns — Enable DNS support
• dhcpv4 — Enable DHCPv4 support
• dhcpv4-hostname — Enable DHCPv4 support with hostname
• proto-ipv4 — Enable IPv4 support
• proto-ipv6 — Enable IPv6 support
• medium-ethernet — Enable the Ethernet medium
• medium-ip — Enable the IP medium
• medium-ieee802154 — Enable the IEEE 802.15.4 medium
• igmp — Enable IGMP support

Re-exports

• pub use embassy_net_driver as driver;

Modules

• dns
  DNS client compatible with the embedded-nal-async traits.
• tcp
  TCP sockets.
• udp
  UDP sockets.

Structs

• Config
  Network stack configuration.
• DhcpConfig
  DHCP configuration.
• EthernetAddress
  A six-octet Ethernet II address.
• Ieee802154Frame
  A read/write wrapper around an IEEE 802.15.4 frame buffer.
• IpEndpoint
  An internet endpoint address.
• IpListenEndpoint
  An internet endpoint address for listening.
• Ipv4Address
  A four-octet IPv4 address.
• Ipv4Cidr
  A specification of an IPv4 CIDR block, containing an address and a variable-length subnet masking prefix length.
• Ipv6Address
  A sixteen-octet IPv6 address.
• Ipv6Cidr
  A specification of an IPv6 CIDR block, containing an address and a variable-length subnet masking prefix length.
• Stack
  A network stack.
• StackResources
  Memory resources needed for a network stack.
• StaticConfigV4
  Static IP address configuration.
• StaticConfigV6
  Static IPv6 address configuration

Enums

• ConfigV4
  Network stack IPv4 configuration.
• ConfigV6
  Network stack IPv6 configuration.
• HardwareAddress
  Representation of an hardware address, such as an Ethernet address or an IEEE802.15.4 address.
• Ieee802154Address
  A IEEE 802.15.4 address.
• IpAddress
  An internetworking address.
• IpCidr
  A specification of a CIDR block, containing an address and a variable-length subnet masking prefix length.
• MulticastError
  Error type for join_multicast_group, leave_multicast_group.