#include <IsolatedEthernet.h>

Data Structures
class	TCPClient
	TCPClient class used to access the isolated Ethernet. More...

class	TCPServer
	Replacement for TCPServer class to use Ethernet. More...

class	UDP
	Replacement for UDP class to use Ethernet. More...

Public Types
enum class	CallbackType { linkUp , linkDown , gotIpAddress }
	Callback messages if you register a callback using withCallback() More...

Public Member Functions
void	setup ()
	You must call this from global setup(). Set options first using the withXXX() methods.

void	stateMachine ()
	State machine. This is called from the worker thread loop. More...

IsolatedEthernet &	withSPI (SPIClass *spi)
	Sets the SPI interface to use. Default is SPI. More...

IsolatedEthernet &	withPinCS (pin_t pinCS)
	Sets the CS pin. Default is D5. More...

IsolatedEthernet &	withPinINT (pin_t pinINT)
	Sets the INT pin. Default is PIN_INVALID (not used). More...

IsolatedEthernet &	withPinRESET (pin_t pinRESET)
	Sets the INT pin. Default is PIN_INVALID (not used). More...

IsolatedEthernet &	withSpiSettings (const SPISettings &spiSettings)
	Sets custom settings for the SPI transactions with the WIZnet W5500. Not normally needed. More...

IsolatedEthernet &	withIPAddress (const IPAddress &ip)
	Sets the IP address when using static IP addressing (instead of DHCP) More...

IsolatedEthernet &	withSubnetMask (const IPAddress &ip)
	Sets the subnet mask when using static IP addressing (instead of DHCP). This is required when using static IP addressing! More...

IsolatedEthernet &	withGatewayAddress (const IPAddress &ip)
	Sets the gateway address static IP addressing (instead of DHCP). More...

IsolatedEthernet &	withDNSAddress (const IPAddress &ip)
	Sets the DNS server address static IP addressing (instead of DHCP). More...

IsolatedEthernet &	withStaticIP ()
	Enables static IP mode. More...

IsolatedEthernet &	withDHCP ()
	Enables DHCP mode. More...

IsolatedEthernet &	withJsonConfigFile (const char *path)
	Specifies that the static IP settings will be stored in a file on the flash file system. More...

void	loadConfigFile ()
	Loads the configuration file. You normally do not need to do this; it's done automatically if necessary. More...

bool	saveConfigFile ()
	Save the configuration file. More...

void	loadJsonConfig (const char *str)
	Loads a JSON configuration from a string. More...

void	loadJsonConfig (const JSONValue &configObj)
	Loads a JSON configuration option that has been parsed by the Device OS JSON parser. More...

bool	hwReset ()
	Does a hardware reset of the W5500. More...

IPAddress	localIP ()
	Get the local IP address as an IPAddress object. For compatibility with the WiFi class. More...

IPAddress	subnetMask ()
	Get the subnet mask as an IPAddress object. For compatibility with the WiFi class. More...

IPAddress	gatewayIP ()
	Get the gateway IP address as an IPAddress object. For compatibility with the WiFi class. More...

IPAddress	dnsServerIP ()
	Get the DNS server IP address as an IPAddress object. For compatibility with the WiFi class. More...

IPAddress	resolve (const char *name)
	Perform a DNS lookup. More...

int	inet_gethostbyname (const char hostname, uint16_t hostnameLen, HAL_IPAddress out_ip_addr, network_interface_t nif, void *reserved)
	Perform a DNS lookup. More...

void	updateAddressSettings ()
	Call this after updating the ipAddr, subnetMaskArray, gatewayAddr, or dnsAddr. More...

bool	ready () const
	Returns true if there is a PHY link and an IP address set. More...

IsolatedEthernet &	withCallback (std::function< void(CallbackType, void *)> cb)
	Add a callback so you can code can be notified when things occur. More...

Static Public Member Functions
static IsolatedEthernet &	instance ()
	Gets the singleton instance of this class, allocating it if necessary. More...

static void	ipAddressToArray (const IPAddress &addr, uint8_t *array)
	Utility function to convert a Device OS IPAddress class to an array of 4 uint8_t for an IPv4 address. More...

static String	arrayToString (const uint8_t *array)
	Utility function to convert an array of 4 uint8_t to a dotted octet String. More...

Data Fields
Logger	appLog
	Logger instance used by IsolatedEthernet. More...

Friends
class	WizInterface

Detailed Description

Particle library for WIZnet W5500 for accessing devices on isolated Ethernet LANs

Features:

Only implements TCPClient, TCPServer, UDP, and UDP multicast to Ethernet. Cloud connection uses native networking (cellular or Wi-Fi).
Static IP addressing or DHCP.
Can run from an isolated Ethernet network.
Works with any avaiable SPI interface and any available GPIO for SPI CS. INT and RESET are optional.
Uses separate TCPClient, TCPServer, and UDP classes over Ethernet so you can still use those classes with native networking at the same time.
Works with any WIZnet W5500 board, including Particle M.2 evaluation board, Ethernet Featherwing, Mikroe ETH click, and Adafruit Ethernet Featherwing.

This class is a singleton; you do not create one as a global, on the stack, or with new.

From global application setup you must call:

IsolatedEthernet::instance().setup();

Member Enumeration Documentation

◆ CallbackType

enum class IsolatedEthernet::CallbackType

strong

Callback messages if you register a callback using withCallback()

Enumerator
linkUp	PHY link is up.
linkDown	PHY link is down.
gotIpAddress	An IP address has been assigned.

Member Function Documentation

◆ arrayToString()

static String IsolatedEthernet::arrayToString ( const uint8_t * array )

static

Utility function to convert an array of 4 uint8_t to a dotted octet String.

Parameters

array Pointer to an array of 4 uint8_t

Returns: String A string containing dotted octets ("192.168.1.1")

◆ dnsServerIP()

IPAddress IsolatedEthernet::dnsServerIP ( )

inline

Get the DNS server IP address as an IPAddress object. For compatibility with the WiFi class.

Returns: IPAddress

◆ gatewayIP()

IPAddress IsolatedEthernet::gatewayIP ( )

inline

Get the gateway IP address as an IPAddress object. For compatibility with the WiFi class.

Returns: IPAddress

◆ hwReset()

bool IsolatedEthernet::hwReset ( )

Does a hardware reset of the W5500.

Returns: true; false

This is only done if pinRESET is defined for the hardware reset pin. If there is no hardware reset pin connected, a software reset is done over SPI.

◆ inet_gethostbyname()

int IsolatedEthernet::inet_gethostbyname	(	const char *	hostname,
		uint16_t	hostnameLen,
		HAL_IPAddress *	out_ip_addr,
		network_interface_t	nif,
		void *	reserved
	)

Perform a DNS lookup.

Parameters

hostname	The hostname to look up
hostnameLen	The length of hostname
out_ip_addr	Filled in with the
nif	Ignored. Pass 0.
reserved	Ignored, pass NULL or 0.

Returns: int 0 on success, or a non-zero error code

This API is provided to match the Device OS HAL API of the same name. The resolve() method is easier to use.

◆ instance()

static IsolatedEthernet & IsolatedEthernet::instance ( )

static

Gets the singleton instance of this class, allocating it if necessary.

Use IsolatedEthernet::instance() to instantiate the singleton.

◆ ipAddressToArray()

static void IsolatedEthernet::ipAddressToArray	(	const IPAddress &	addr,
		uint8_t *	array
	)

static

Utility function to convert a Device OS IPAddress class to an array of 4 uint8_t for an IPv4 address.

Parameters

addr	The address to read from
array	Pointer to an array of 4 uint8_t to fill in

To convert an array to IPAddress, there's a constructor to IPAddress that takes a const uint8_t *.

◆ loadConfigFile()

void IsolatedEthernet::loadConfigFile ( )

Loads the configuration file. You normally do not need to do this; it's done automatically if necessary.

The configuration file name is specified using withJsonConfigFile().

◆ loadJsonConfig() [1/2]

void IsolatedEthernet::loadJsonConfig ( const char * str )

Loads a JSON configuration from a string.

Parameters

str	A string containing a JSON settings object.

You typically do this if you receive a new configuration, such as from a Particle function.

◆ loadJsonConfig() [2/2]

void IsolatedEthernet::loadJsonConfig ( const JSONValue & configObj )

Loads a JSON configuration option that has been parsed by the Device OS JSON parser.

Parameters

configObj

See also the overload that takes a c-string, which really just calls this function after parsing the data.

◆ localIP()

IPAddress IsolatedEthernet::localIP ( )

inline

Get the local IP address as an IPAddress object. For compatibility with the WiFi class.

Returns: IPAddress

◆ ready()

bool IsolatedEthernet::ready ( ) const

inline

Returns true if there is a PHY link and an IP address set.

Returns: true; false

Does not validate that the ipAddress or gateway address is valid or whether there's any connectivity above the PHY layer.

It's normally used in place of WiFi.ready(), Ethernet.ready(), etc..

◆ resolve()

IPAddress IsolatedEthernet::resolve ( const char * name )

inline

Perform a DNS lookup.

Parameters

name	Host name to look up

Returns: IPAddress

This API is compatible with the WiFi class method.

IPAddress supports operator bool() so you can test that IPAddress is true to see if an address was returned. It will be 0 (false) if the hostname could not be looked up because DNS wasn't configured, not available, or the host name does not exist.

◆ saveConfigFile()

bool IsolatedEthernet::saveConfigFile ( )

Save the configuration file.

Returns: true; false

Saves the current settings for ipAddr, subnetMaskArray, gatewayAddr, dnsAddr to the settings file specified by withJsonConfigFile. You use this after updating the settings so they will be used the next restart.

◆ stateMachine()

void IsolatedEthernet::stateMachine ( )

State machine. This is called from the worker thread loop.

While the library does not currently support it, you could disable the thread and run the state machine from loop.

◆ subnetMask()

IPAddress IsolatedEthernet::subnetMask ( )

inline

Get the subnet mask as an IPAddress object. For compatibility with the WiFi class.

Returns: IPAddress

◆ updateAddressSettings()

void IsolatedEthernet::updateAddressSettings ( )

Call this after updating the ipAddr, subnetMaskArray, gatewayAddr, or dnsAddr.

This takes the fields in this class and updates the registers in the W5500.

If you set the fields before calling setup() you do not need to call this method as it will be handled automatically. Same for using the configuration file or JSON configuration options. This is called internally after parsing JSON configuration.

◆ withCallback()

IsolatedEthernet & IsolatedEthernet::withCallback ( std::function< void(CallbackType, void *)> cb )

inline

Add a callback so you can code can be notified when things occur.

Parameters

cb	The callback function or lambds

Returns: IsolatedEthernet& Reference to this object so you can chain options, fluent-style.

The prototype for the callback is:

void callback(CallbackType type, void* data)

◆ withDHCP()

IsolatedEthernet & IsolatedEthernet::withDHCP ( )

Enables DHCP mode.

Returns: IsolatedEthernet& Reference to this object so you can chain options, fluent-style.

Since the default is DHCP mode you normally don't need to call this, but you can use this to switch from static to DHCP again.

◆ withDNSAddress()

IsolatedEthernet & IsolatedEthernet::withDNSAddress ( const IPAddress & ip )

inline

Sets the DNS server address static IP addressing (instead of DHCP).

Parameters

ip	The DNS server to use. Often the gateway address, it could also be a site DNS or public DNS like 8.8.8.8.

Returns: IsolatedEthernet& Reference to this object so you can chain options, fluent-style.

This method should be called before setup(). If you want to change the DNS address later at runtime, set the IP address, subnet mask, gateway address, then call updateAddressSettings.

This internally calls withStaticIP() and will stop any DHCP that is currently in progress.

Only one DNS address is supported.

◆ withGatewayAddress()

IsolatedEthernet & IsolatedEthernet::withGatewayAddress ( const IPAddress & ip )

inline

Sets the gateway address static IP addressing (instead of DHCP).

Parameters

ip	The gateway address to use, often something like 192.168.1.1. This must be in the same subnet as the IP address.

Returns: IsolatedEthernet& Reference to this object so you can chain options, fluent-style.

This method should be called before setup(). If you want to change the gateway address later at runtime, set the IP address, subnet mask, gateway address, then call updateAddressSettings.

This internally calls withStaticIP() and will stop any DHCP that is currently in progress.

◆ withIPAddress()

IsolatedEthernet & IsolatedEthernet::withIPAddress ( const IPAddress & ip )

inline

Sets the IP address when using static IP addressing (instead of DHCP)

Parameters

ip	The IP Address to use. This is often an internal address like 192.168.1.100 or 10.1.2.50.

Returns: IsolatedEthernet& Reference to this object so you can chain options, fluent-style.

This method should be called before setup(). If you want to change the IP address later at runtime, set the IP address, subnet mask, gateway address, then call updateAddressSettings.

This internally calls withStaticIP() and will stop any DHCP that is currently in progress.

If you use withIPAddress you must also call withSubnetMask, it does not configure a default automatically based on your address class!

◆ withJsonConfigFile()

IsolatedEthernet & IsolatedEthernet::withJsonConfigFile ( const char * path )

inline

Specifies that the static IP settings will be stored in a file on the flash file system.

Parameters

path	Path to the file in the POSIX file system. If in a subdirectory, the subdirectory must exist.

Returns: IsolatedEthernet& Reference to this object so you can chain options, fluent-style.

You must call this before setup(). It's OK to call this before the settings file exists.

◆ withPinCS()

IsolatedEthernet & IsolatedEthernet::withPinCS ( pin_t pinCS )

inline

Sets the CS pin. Default is D5.

Parameters

pinCS Any available GPIO to use the CS pin. Default is D5 for Feather and D8 for B Series eval board.

Returns: IsolatedEthernet& Reference to this object so you can chain options, fluent-style.

Must be called before setup()! Changing it later will not work properly.

In the unusual case of using fixed-length data mode (FDM) with the W5500 CS pin grounded, pass PIN_INVALID to this method. Note: FDM is not currently supported, so you must use a CS pin.

◆ withPinINT()

IsolatedEthernet & IsolatedEthernet::withPinINT ( pin_t pinINT )

inline

Sets the INT pin. Default is PIN_INVALID (not used).

Parameters

pinINT Any available GPIO to use the INT pin. Default is D4 for Feather and D22 for B Series eval board.

Returns: IsolatedEthernet& Reference to this object so you can chain options, fluent-style.

This setting is not actually used. This library currently always runs in polling mode and does not use the hardware interrupt support, but it could be used in the future.

Must be called before setup()! Changing it later will not work properly.

◆ withPinRESET()

IsolatedEthernet & IsolatedEthernet::withPinRESET ( pin_t pinRESET )

inline

Sets the INT pin. Default is PIN_INVALID (not used).

Parameters

pinRESET Any available GPIO to use the INT pin. Default is D3 for Feather and A7 for B Series eval board.

Returns: IsolatedEthernet& Reference to this object so you can chain options, fluent-style.

This setting is optional. If not used, then software reset is used instead.

Must be called before setup()! Changing it later will not work properly.

◆ withSPI()

IsolatedEthernet & IsolatedEthernet::withSPI ( SPIClass * spi )

inline

Sets the SPI interface to use. Default is SPI.

Parameters

spi	SPI interface, default is SPI, but you can also use SPI1.

Returns: IsolatedEthernet& Reference to this object so you can chain options, fluent-style.

◆ withSpiSettings()

IsolatedEthernet & IsolatedEthernet::withSpiSettings ( const SPISettings & spiSettings )

inline

Sets custom settings for the SPI transactions with the WIZnet W5500. Not normally needed.

Parameters

spiSettings A SPISettings object (speed, bit order, mode)

Returns: IsolatedEthernet& Reference to this object so you can chain options, fluent-style.

The W5500 only supports mode 0 and 3, MSB first.

◆ withStaticIP()

IsolatedEthernet & IsolatedEthernet::withStaticIP ( )

Enables static IP mode.

Returns: IsolatedEthernet& Reference to this object so you can chain options, fluent-style.

You normally don't need to call this if you are using withIPAddress(), etc.. However, in the case where you do not want to attempt DHCP but also do not know your IP address yet, you can call this to disable DHCP.

◆ withSubnetMask()

IsolatedEthernet & IsolatedEthernet::withSubnetMask ( const IPAddress & ip )

inline

Sets the subnet mask when using static IP addressing (instead of DHCP). This is required when using static IP addressing!

Parameters

ip	The subnet mask to use, often something like 255.255.255.0

Returns: IsolatedEthernet& Reference to this object so you can chain options, fluent-style.

This method should be called before setup(). If you want to change the subnet mask later at runtime, set the IP address, subnet mask, gateway address, then call updateAddressSettings.

This internally calls withStaticIP() and will stop any DHCP that is currently in progress.

Field Documentation

◆ appLog

Logger IsolatedEthernet::appLog

Logger instance used by IsolatedEthernet.

All logging messages use the category app.ether so you can control the level in your log handler instances.

Within this library, always use appLog.info() instead of Log.info(), for example.

The documentation for this class was generated from the following file:

src/IsolatedEthernet.h

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Data Fields

Friends

Detailed Description

Member Enumeration Documentation

◆ CallbackType

Member Function Documentation

◆ arrayToString()

◆ dnsServerIP()

◆ gatewayIP()

◆ hwReset()

◆ inet_gethostbyname()

◆ instance()

◆ ipAddressToArray()

◆ loadConfigFile()

◆ loadJsonConfig() [1/2]

◆ loadJsonConfig() [2/2]

◆ localIP()

◆ ready()

◆ resolve()

◆ saveConfigFile()

◆ stateMachine()

◆ subnetMask()

◆ updateAddressSettings()

◆ withCallback()

◆ withDHCP()

◆ withDNSAddress()

◆ withGatewayAddress()

◆ withIPAddress()

◆ withJsonConfigFile()

◆ withPinCS()

◆ withPinINT()

◆ withPinRESET()

◆ withSPI()

◆ withSpiSettings()

◆ withStaticIP()

◆ withSubnetMask()

Field Documentation

◆ appLog