STM32Ethernet
Arduino Ethernet library for STM32 boards
Loading...
Searching...
No Matches
STM32Ethernet

STM32Ethernet allows an Ethernet-compatible STM32 board, such as a NUCLEO or DISCOVERY board, to connect to a local network or the Internet. It follows the Arduino Ethernet API and provides client, server, DHCP, and DNS functionality.

The hosted API documentation is available online. See the examples for complete sketches.

Requirements

  • An STM32 board with Ethernet hardware support, for example:
    • NUCLEO-F429ZI
    • STM32F746G-DISCOVERY
  • The STM32duino LwIP library.

Both libraries are available through the Arduino Library Manager. In the Arduino IDE, open Sketch > Include Library > Manage Libraries..., search for LwIP, then install LwIP and STM32Ethernet.

STM32Ethernet is based on LwIP, a lightweight TCP/IP stack, and is compatible with the Arduino Ethernet API.

Quick start

Include both libraries, then start the connection with DHCP:

#include <LwIP.h>
#include <STM32Ethernet.h>
void setup() {
Serial.begin(9600);
if (Ethernet.begin() == 0) {
Serial.println("Failed to configure Ethernet using DHCP");
}
}
void loop() {
}
Ethernet
EthernetClass Ethernet
Definition STM32Ethernet.cpp:169
STM32Ethernet.h
Main header of the STM32Ethernet library.
EthernetClass::begin
int begin(unsigned long timeout=60000, unsigned long responseTimeout=4000)
Initialises Ethernet with the built-in MAC address and gets the network configuration from a DHCP ser...
Definition STM32Ethernet.cpp:8

Ethernet.begin() returns 1 when DHCP configuration succeeds and 0 when it fails. When DHCP is unavailable, configure a static address instead:

IPAddress ip(192, 168, 0, 177);
Ethernet.begin(ip);

The static-address overloads also allow the subnet mask, gateway, and DNS server to be provided:

Ethernet.begin(ip, subnet);
Ethernet.begin(ip, subnet, gateway);
Ethernet.begin(ip, subnet, gateway, dns);

See the WebClient example for a DHCP connection with a static-IP fallback.

MAC address

When no MAC address is supplied, the library retrieves the board's internal MAC address. Read it after initializing Ethernet:

uint8_t mac[6];
Ethernet.begin();
Ethernet.MACAddress(mac);
EthernetClass::MACAddress
void MACAddress(uint8_t *mac_address)
Copies the current MAC address of the Ethernet interface.
Definition STM32Ethernet.cpp:139

To use a custom MAC address, set it before initialization:

uint8_t mac[] = {0x00, 0x80, 0xE1, 0x01, 0x01, 0x01};
Ethernet.setMACAddress(mac);
Ethernet.begin();
EthernetClass::setMACAddress
void setMACAddress(const uint8_t *mac_address)
Sets the MAC address of the Ethernet interface.
Definition STM32Ethernet.cpp:134

The library also provides begin() overloads that accept a MAC address directly.

LwIP configuration and scheduling

LwIP options are configured in lwipopts.h. The library provides lwipopts_default.h as its default configuration. To customize options for a sketch, provide a STM32lwipopts.h file, or add options to the default configuration through lwipopts_extra.h.

The LwIP stack needs periodic processing for timers and packet reception. A timer callback runs stm32_eth_scheduler() every 1 ms by default, using TIM14 (DEFAULT_ETHERNET_TIMER). A core variant can redefine DEFAULT_ETHERNET_TIMER. Avoid disabling interrupts for extended periods. Call Ethernet.schedule() to process the LwIP stack explicitly, for example after a long-running loop.

DHCP lease renewal is handled by LwIP in the background, so calling Ethernet.maintain() is not required for normal operation. The method remains available for sketches that need to check or handle DHCP lease renewals.

Examples

The repository includes sketches for DHCP address reporting, TCP clients and servers, UDP, DNS/NTP, and FreeRTOS. Open them from the Arduino IDE's examples menu or browse the examples directory.

Documentation and source

Generated by doxygen 1.9.8