ArduinoNetAPILibs.md

Arduino networking API implementations

Contents

• Overview
• Ethernet/WiFi object
• Client class
• Server class
• UDP class

Overview

library	year	TCP/IP	network interfaces	maintainer
Ethernet	2008	in fw	Ethernet (Wiznet W5x00)	Arduino
WiFi (1)	2011	in fw	WiFi STA (AT32UC3 with wifiHD fw)	Arduino
WiFi101	2015	in fw	WiFi STA and local AP (ATWINC1500)	Arduino
WiFiNINA	2018	in fw	WiFi STA and SoftAP (ESP32 with nina-fw)	Arduino
WiFiS3	2023	in fw	WiFi STA and SoftAP (ESP32S3 with Uno R4 WiFi fw)	Arduino
Mbed core	2018	LwIP	Ethernet/WiFi (any HW with Mbed EMAC driver)	Arduino
C33 core	2023	LwIP	Ethernet (Eth peripheral), WiFi STA and SoftAP (ESPHost)	Arduino
ESP8266 core	2014	LwIP	WiFi STA and SoftAP, Ethernet (W5500, W5100, ENC28J60), PPP	community
ESP32 core	2016	LwIP	WiFi STA and SoftAP, Ethernet (Ethernet peripheral, W5500, ENC28J60, ...)	Espressif
WiFiEspAT	2019	in fw	WiFi STA and SoftAP (ESP8266 or ESP32 with AT fw)	Juraj A
EthernetENC	2013	uIP	Ethernet (ENC28J60)	Juraj A
STM32Ethernet	2017	LwIP	Ethernet (STM32 Eth peripheral)	STM
QNEthernet	2021	LwIP	Ethernet (Teensy 4.1 Eth peripheral, W5500)	Shawn S
RP2040 Core	2022	LwIP	WiFi STA and SoftAP (Pico W, ESPHost, ATWINC1500), Ethernet (W5500, W5100, ENC28J60)	Earle P

(1) The Arduino WiFi library is obsolete. It is included in the research only because it was the first WiFi library.

Legend for the tables in this document:

• ✓ library has the function
• * the official Arduino library with the first introduction of the API function(s).
• + the function was added in API unification effort after the research
• ✗ library will not support the function

Ethernet/WiFi object

Module control

library	hw setup	detection with	firmwareVersion	end	power save
Ethernet	init(CS)	hardwareStatus
WiFi		status* (1)
WiFi101	setPins	status	✓*	✓*	lowPowerMode
WiFiNINA	defines	status	✓	✓	lowPowerMode
WiFiS3		status	✓	✓
Mbed WiFi		status	✓	✓	lowPowerMode
Mbed Ethernet	init(CS)	hardwareStatus		✓
C33 Wifi		status	returns a constant	✓	lowPowerMode
C33 Ethernet		hardwareStatus
esp8266 WiFi		status			sleepMode
esp8266 LwipIntfDev (2)	constructor	hardwareStatus (3), status		✓
esp32 WiFi		status			sleep
esp32 Ethernet	defines			✓
WiFiEspAT	init(Stream&)	status	✓		sleepMode
EthernetENC	init(CS)	hardwareStatus		+
STM32Ethernet
QNEthernet		hardwareStatus		✓
RP2040 WiFi		status			lowPowerMode
RP2040 LwipIntfDev	constructor	hardwareStatus (3), status		✓

(1) status() is for the WiFi state, but returns WL_NO_SHIELD/WL_NO_MODULE if the hardware is not detected

(2) LwipIntfDev is the common class for (wired) network interface libraries

(3) with EthernetCompat from lwIP_Ethernet library

Ethernet network interface

library	linkStatus	begin DHCP	begin static IP	config (1)	auto dns, gw, mask	maintain
Ethernet *	✓	✓	✓		✓	✓
Mbed Ethernet	✓	✓	✓		✓	✓
C33 Ethernet	✓	✓	✓		✓	✓
esp8266 EthernetCompat	✓	✓	✓		+	✓
esp8266 LwipIntfDev	✓	not blocking	✗	✓	+
esp32 Ethernet (2)		not blocking	✗	wrong param. order
EthernetENC	✓	✓	✓		✓	✓
STM32Ethernet	✓	✓	✓		✓	✓
QNEthernet	✓	✓	✓		✓
RP2040 EthernetCompat	+	+	+		+	+
RP2040 LwipIntfDev	+	not blocking	✗	✓	+

(1) Modern Ethernet libraries use configfor static IP

(2) EthernetESP32 library has standard Ethernet API for esp32 platform's LwIP networking

WiFi station network interface

library	status	begin	beginEnterprise	config	auto dns, gw, mask	disconnect
WiFi *	✓	✓		✓		✓
WiFi101	✓	✓		✓	PR	✓
WiFiNINA	✓	✓	✓*	✓	PR	✓
WiFiS3	✓	✓		✓	✓	✓
Mbed WiFi	✓	✓		✓ PR	+	✓
C33 Wifi	✓	✓		✓	✓	✓
esp8266 WiFi	✓	not blocking		✓	+	✓
esp32 WiFi	✓	not blocking		✓ PR	+	✓
WiFiEspAT	✓	✓	✓	✓	✓	✓
RP2040 WiFi	✓	✓		✓	+	✓

Network interface getters and setters

All libraries have localIP(), gatewayIP() and subnetMask() getters. Many Ethernet libraries now have the getters and setters introduced in WiFi libraries.

library	setHostname	setDNS	dnsIP(n)	macAddress
Ethernet	PR	PR	PR	PR
WiFi		✓*		✓* R
WiFi101	hostname PR	✗	PR	✓ R
WiFiNINA	✓*	✓	PR	✓ R
WiFiS3	✓	✓	✓*	✓ R PR
Mbed WiFi	✗	✓	+	✓ R
Mbed Ethernet	✗	✓	+	✓ R !!! issue
C33 Wifi	✓ (1)	✓	+	✓ R PR
C33 Ethernet	PR	✓	PR	PR
esp8266 WiFi	✓	+	✓	✓
esp8266 LwipIntfDev	✓	+	+	+
esp32 WiFi	✓	+	✓	✓
esp32 Ethernet	✓	(2)	✓	✓
WiFiEspAT	✓	✓	+	✓ R
EthernetENC	+	+	+	✓
STM32Ethernet
QNEthernet	✓			✓
RP2040 WiFi	✓	✓	+	✓
RP2040 LwipIntfDev	✓	+	+	+

Flag R is for "reversed". Arduino WiFi libraries copied the bug of the first WiFi library. The bytes of the MAC address are from macAddress getter returned in reversed order.

(1) hostname is not send with DHCP request

(2) EthernetESP32 library has standard Ethernet API for esp32 platform's LwIP networking

Legacy Ethernet getters and setters

library	setDnsServerIP	dnsServerIP	MACAddress
Ethernet	✓	✓	✓
Mbed Ethernet	✓	✓	✓ R issue
C33 Ethernet	PR	✓	+
esp8266 EthernetCompat	+	+	+
EthernetENC	✓	✓	✓
STM32Ethernet	+	✓	is a setter! (issue)
QNEthernet	✓	✓	✓
RP2040 EthernetCompat	+	+	+

WiFi station getters

library	SSID	BSSID	encryptionType	channel	RSSI	reasonCode
WiFi *	✓	✓ R	✓		✓
WiFi101	✓	✓ R	✓		✓
WiFiNINA	✓	✓ R	✓		✓	✓*
WiFiS3	✓	✓	✓		✓	returns 0
Mbed WiFi	✓	✓	✓		✓
C33 Wifi	✓	✓	✓		✓	returns 0
esp8266 WiFi	✓	+	PR	✓	✓
esp32 WiFi	✓	+		✓	✓
WiFiEspAT	✓	✓ R		+	✓
RP2040 WiFi	✓	✓	✓	✓	✓	returns WL_NO_SHIELD

WiFi AP network interface

For libraries which can only run one WiFi interface, AP ends with begin for station.

library	beginAP	end	configure
WiFi	✗
WiFi101	✓*
WiFiNINA	✓
WiFiS3	✓
Mbed WiFi	✓
C33 Wifi	✓
esp8266 WiFi	softAP	softAPdisconnect	softAPConfig
esp32 WiFi	softAP	softAPdisconnect	softAPConfig
WiFiEspAT	✓, softAP	endAP, softAPdisconnect	configureAP, softAPConfig
RP2040 WiFi	✓, softAP	softAPdisconnect	softAPConfig

WiFi AP getters

For libraries which can only run one WiFi interface, after beginAP standard getters read the AP information.

library	MAC	SSID	Pass	encryption	ip	gw	mask
esp8266 WiFi	softAPmacAddress	softAPSSID	softAPPSK		softAPIP
esp32 WiFi	softAPmacAddress	softAPSSID	softAPPSK		softAPIP
WiFiEspAT	apMacAddress, softAPmacAddress	apSSID, softAPSSID	apPassphrase, softAPPSK	apEncryptionType	apIP, softAPIP	apGatewayIP	apSubnetMask
RP2040 WiFi	softAPmacAddress	softAPSSID			softAPIP

WiFi station networks scan

All researched libraries have methods scanNetworks(), SSID(n), encryptionType(n) and RSSI(n) defined by the first WiFi library. All libraries except of the old WiFi library have BSSID(n,bssid) and channel(n)defined by the WiFi101 library. WiFi101 and WiFiNINA have the BSSID in reversed ordering.

Encryption type constant names are in esp32 WiFi library very different from the common set used in all other WiFi libraries.

Network services

The Ethernet/WiFi objects have some functions for simple services. (Libraries may have these services in other classes or they may be available as separate libraries.)

library	hostByName	ping	getTime
Ethernet	PR
WiFi	✓*
WiFi101	✓	✓*	✓*
WiFiNINA	✓	✓	✓
WiFiS3	✓		returns 0
Mbed WiFi	✓		returns 0
Mbed Ethernet	✓		returns 0
C33 Wifi	✓		returns 0
C33 Ethernet	PR
esp8266 WiFi	✓
esp8266 LwipIntfDev
esp32 WiFi	✓
esp32 Ethernet
WiFiEspAT	✓	✓	✓
EthernetENC	+
STM32Ethernet
QNEthernet	+
RP2040 WiFi	✓	✓	returns millis() !!!
RP2040 LwipIntfDev	✓	✓

Client class

Inherited methods

All Client classes in the researched libraries implement the Arduino Client class which forces the essential methods.

Method connected()

The method connected should return true if the Client has data available to read even if the underlying TCP connection is closed. Esp8266 and Esp32 libraries return false if the TCP connection is closed even if there are still data to read.

Client getters and setters

All libraries have remoteIP() and remotePort() with exception of the old WiFi library. A few libraries have localIP() to identify the network interface used for the Client.

library	class	localIP	localPort	status	setConnectionTimeout
Ethernet	EthernetClient			✓*	✓ *2018
WiFi	WiFiClient			✓
WiFi101	WiFiClient			returns 0 PR	PR
WiFiNINA	WiFiClient			✓	PR
WiFiS3	WiFiClient			✓	+
Mbed SocketWrapper	MbedClent (1)			returns only 1 or 0	✗
C33 lwIpWrapper	lwipClient (1)			✓	✓
ESP8266WiFi	WiFiClient (2)	✓	✓	✓	Stream's setTimeout discussion
esp32 Network	NetworkClient (3)	✓	✓		+
WiFiEspAT	WiFiClient		✓	✓	✗
EthernetENC	EthernetClient			+	✓
STM32Ethernet	EthernetClient			✓	+
QNEthernet	EthernetClient	+	✓	+	✓
RP2040 WiFi	WiFiClient (2)	✓	✓	✓	Stream's setTimeout

(1) common implementation for WiFiClient and EthernetClient in the platform's libraries

(2) WiFiClient is used for Ethernet interface too. EthernetCompat has EthernetClient as alias to WiFiClient.

(3) WiFiClient is alias for NetworkClient. EthernetClient is not defined

client.read(buff, size) return value

There are differences for return value of client.read(buff, size). According to Arduino documentation return -1 is "no data available" and 0 is "connection is closed". And this is how it is in BSD sockets where there is no other way to get the closed state. But most Arduino libraries return 0 if no data are available and some return -1 if the client is not valid.

Note: The Arduino documentation mixes read() with read(buff, size). read() should definitely return -1 if no byte is available, because 0 is a valid returned value.

library	class	no data available	connection is closed (1)
Ethernet	EthernetClient	-1	0
WiFi101	WiFiClient	-1	0
WiFiNINA	WiFiClient	0
WiFiS3	WiFiClient	0
Mbed SocketWrapper	MbedClent	-1
C33 lwIpWrapper	lwipClient	-1
ESP8266WiFi	WiFiClient	0
esp32 Network	NetworkClient	0
WiFiEspAT	WiFiClient	0
EthernetENC	EthernetClient	0	-1
STM32Ethernet	EthernetClient	0	-1
QNEthernet	EthernetClient	0	0
RP2040 WiFi	WiFiClient (2)	0

(1) empty field means that the state of the connection is not checked in read(buff, size)

Secure layer

library	secure client	lastError()	setInsecure	allowSelfSignedCerts	disableSNI
Ethernet	(1)
WiFi
WiFi101	WiFiSSLClient
WiFiNINA	WiFiSSLClient
WiFiS3	WiFiSSLClient
Mbed SocketWrapper	MbedSSLClient (2)				✓*
C33 lwIpWrapper	SSLClient (2)	✓*	✓*
ESP8266WiFi	WiFiClientSecure	getLastSSLError	✓	✓
esp32 Network	NetworkClientSecure	✓	✓
WiFiEspAT	WiFiSSLClient
EthernetENC	(1)
STM32Ethernet
QNEthernet
RP2040 WiFi	WiFiClientSecure	getLastSSLError	✓	✓

(1) SSLClient library can add secure layer

(2) common implementation for WiFiSSLClient and EthernetSSLClient in the platform's libraries

Certificates for the connection:

library	setPreSharedKey	setCACert	setCertificate	setPrivateKey	load (1)
Mbed SocketWrapper		appendCustomCACert			root CA from default block device
C33 lwIpWrapper *	✓	✓	✓	✓	✓
ESP8266WiFi		setTrustAnchors	setClientRSACert	setClientRSACert	setCertStore
esp32 WiFi	✓	✓	✓	✓	✓
RP2040 WiFi		✓, setTrustAnchors	✓, setClientRSACert	✓, setClientRSACert	✓, setCertStore

(1) loadCACert, loadCertificate, loadPrivateKey from a Stream, or other way for stored certificates

Additional properties:

library	secure client	setKnownKey	setFingerprint	setCiphers	setCiphersLessSecure
Mbed SocketWrapper	MbedSSLClient
C33 lwIpWrapper	SSLClient
ESP8266WiFi	WiFiClientSecure	✓	✓	✓	✓
esp32 Network	NetworkClientSecure
RP2040 WiFi	WiFiClientSecure	✓	✓	✓	✓

Server class

Class

All Server classes have a constructor with parameter port. ESP8266, ESP32 and RP2040 WiFi library WiFiServer have additional constructor with IP to identify the network interface on which the server should listen.

Arduino core has Server class which inherits from the Print class. The idea is to use the methods of Print to output to all clients at once. The Server class itself doesn't define anything useful.

Modern server class implementations have constructor without parameters, method begin(port), method accept(), method end() and bool operator. Modern implementations of the server class do not implement available() and print-to-all-clients so they don't inherit from Server.

library	class	ctor without params	print to all clients	modern
Ethernet	EthernetServer	PR	✓
WiFi	WiFiServer		✓
WiFi101	WiFiServer	PR	✓
WiFiNINA	WiFiServer	PR	✓
WiFiS3	WiFiServer	✓*	✓
Mbed SocketWrapper	MbedServer (2)		✗ (1)	PR
C33 lwIpWrapper	lwipServer (2)	✓	✓
ESP8266WiFi	WiFiServer (3)	+	ArduinoWiFiServer	✓
esp32 Network	NetworkServer (4)	✓	✗ (1)	✓
WiFiEspAT	WiFiServer	+	✗ (1)	✓
EthernetENC	EthernetServer	+	EthernetServerPrint	✓
STM32Ethernet	EthernetServer	✓	✓
QNEthernet	EthernetServer	✓	✓
RP2040 WiFi	WiFiServer (3)	+	✗ (1)	✓

(1) ArduinoWiFiServer in NetApiHelpers library has print-to-all-clients and proper server.available()

(2) common implementation for WiFiServer and EthernetServer in the platform's libraries

(3) WiFiServer is used for Ethernet interface too. EthernetCompat.h has EthernetServer as alias to WiFiServer.

(4) WiFiServer is alias for NetworkServer. EthernetServer is not defined

Methods

All Server classes have method begin without parameters.

library	class	begin(port)	end	op bool	status	available	accept
Ethernet	EthernetServer	PR->	PR	✓ *2018 issue		✓*	✓ *2018
WiFi	WiFiServer				✓*	✓
WiFi101	WiFiServer	PR	PR	PR	returns 0 PR	✓	PR
WiFiNINA	WiFiServer	PR->	PR	PR	✓	✓	PR
WiFiS3	WiFiServer	✓*	✓*	+		✓	+
Mbed SocketWrapper	MbedServer				returns 0 issue	✗(1)
C33 lwIpWrapper	lwipServer	✓				✓
ESP8266WiFi	WiFiServer	✓	+	+	✓	(1)(2)	✓
esp32 Network	NetworkServer	✓	✓	✓	✓	✗(1)	✓
WiFiEspAT	WiFiServer	+	✓	✓	✓	✗(1)	✓
EthernetENC	EthernetServer	+	✓	✓		✓	✓
STM32Ethernet	EthernetServer	✓	+	+		✓	✓
QNEthernet	EthernetServer	✓	✓	✓		✓	✓
RP2040 WiFi	WiFiServer	✓	+	+	✓	✗(1)	✓

(1) the method called available in WiFiServer works like accept method

(2) available() with ArduinoWiFiServer

UDP class

Class

All UDP classes in the researched libraries implement the Arduino UDP class which forces to implement the essential methods.

library	class
Ethernet	EthernetUDP
WiFi	WiFiUDP
WiFi101	WiFiUDP
WiFiNINA	WiFiUDP
WiFiS3	WiFiUDP
Mbed SocketWrapper	MbedUDP (1)
C33 lwIpWrapper	lwipUDP (1)
ESP8266WiFi	WiFiUDP
esp32 Network	NetworkUDP (3)
WiFiEspAT	WiFiUDP
EthernetENC	EthernetUDP
STM32Ethernet	EthernetUDP
QNEthernet	EthernetUDP
RP2040 WiFi	WiFiUDP (2)

(1) common implementation for WiFiUdp and EthernetUdp in the platform's libraries

(3) WiFiUdp is used for Ethernet interface too. EthernetCompat.h has EthernetUdp as alias to WiFiUdp.

(4) WiFiUdp is alias for NetworkUdp. EthernetUdp is not defined