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, aiiming 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.

License

This work is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

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.