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
• TCP sockets implement the embedded-io async traits.
• Multicast

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 higher-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

• icmp — Enable ICMP support
• udp — Enable UDP support
• raw — Enable Raw support
• tcp — Enable TCP support
• dns — Enable DNS support
• mdns — Enable mDNS 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
• multicast — Enable multicast support (for both ipv4 and/or ipv6 if enabled)
• std — Enable smoltcp std feature (necessary if using “managed” crate std feature)
• alloc — Enable smoltcp alloc feature (necessary if using “managed” crate alloc feature)

Re-exports

pub use embassy_net_driver as driver;

Modules

dns

DNS client compatible with the embedded-nal-async traits.

icmp

ICMP sockets.

raw

Raw sockets.

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

An IPv4 address.

Ipv4Cidr

A specification of an IPv4 CIDR block, containing an address and a variable-length subnet masking prefix length.

Ipv6Address

An IPv6 address.

Ipv6Cidr

A specification of an IPv6 CIDR block, containing an address and a variable-length subnet masking prefix length.

Runner

Network stack runner.

Stack

Network stack handle

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.

Constants

DNS_MAX_SERVER_COUNT

Functions

new

Create a new network stack.