Crate embassy_net
source ·Expand description
§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 Wembassy-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 theesp-hosted
firmware as WiFi adapters for another non-ESP32 MCU.
§Examples
- For usage with Embassy HALs and network chip drivers, search here for
eth
orwifi
. - The
esp-wifi
repo has examples for use on bare-metal ESP32 chips. - For usage on
std
platforms, see thestd
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 defmtpacket-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 supportraw
— Enable Raw supporttcp
— Enable TCP supportdns
— Enable DNS supportmdns
— Enable mDNS supportdhcpv4
— Enable DHCPv4 supportdhcpv4-hostname
— Enable DHCPv4 support with hostnameproto-ipv4
— Enable IPv4 supportproto-ipv6
— Enable IPv6 supportmedium-ethernet
— Enable the Ethernet mediummedium-ip
— Enable the IP mediummedium-ieee802154
— Enable the IEEE 802.15.4 mediummulticast
— Enable multicast support (for both ipv4 and/or ipv6 if enabled)
Re-exports§
pub use embassy_net_driver as driver;
Modules§
- DNS client compatible with the
embedded-nal-async
traits. - Raw sockets.
- TCP sockets.
- UDP sockets.
Structs§
- Network stack configuration.
- DHCP configuration.
- A six-octet Ethernet II address.
- A read/write wrapper around an IEEE 802.15.4 frame buffer.
- An internet endpoint address.
- An internet endpoint address for listening.
- A four-octet IPv4 address.
- A specification of an IPv4 CIDR block, containing an address and a variable-length subnet masking prefix length.
- A sixteen-octet IPv6 address.
- A specification of an IPv6 CIDR block, containing an address and a variable-length subnet masking prefix length.
- Network stack runner.
- Network stack handle
- Memory resources needed for a network stack.
- Static IP address configuration.
- Static IPv6 address configuration
Enums§
- Network stack IPv4 configuration.
- Network stack IPv6 configuration.
- Representation of an hardware address, such as an Ethernet address or an IEEE802.15.4 address.
- A IEEE 802.15.4 address.
- An internetworking address.
- A specification of a CIDR block, containing an address and a variable-length subnet masking prefix length.
- Error type for
join_multicast_group
,leave_multicast_group
.
Constants§
Functions§
- Create a new network stack.