EthernetCellular Class Reference

#include <EthernetCellularRK.h>

Public Types
enum	ActiveInterface : int { NONE = 0, ETHERNET, CELLULAR }

Public Member Functions
void	setup ()
	Perform setup operations; call this from global application setup() More...
void	loop ()
	Perform application loop operations; call this from global application loop() More...
EthernetCellular &	withEthernetKeepAlive (std::chrono::seconds value)
	Set an Ethernet keep-alive value (default: 25 seconds) More...
int	getEthernetKeepAlive () const
	Returns the Ethernet keep-alive value (in seconds)
EthernetCellular &	withCellularKeepAlive (std::chrono::seconds value)
	Set an cellular keep-alive value (default: 23 minutes) More...
int	getCellularKeepAlive () const
	Returns the cellular keep-alive value (in seconds)
EthernetCellular &	withRetryEthernetPeriod (std::chrono::milliseconds value)
	Set the period to try switching back to Ethernet from cellular. Default: 5 minutes. More...
int	getRetryEthernetPeriod () const
	Returns the period to try switching back to Ethernet from cellular (in milliseconds)
EthernetCellular &	withCellularConnectTimeout (std::chrono::milliseconds value)
	Set the maximum time to connect to cellular (blinking green). Default: 5 minutes. More...
int	getCellularConnectTimeout () const
	Returns the maximum time to connect to cellular (blinking green) (in milliseconds)
EthernetCellular &	withCellularCloudConnectTimeout (std::chrono::milliseconds value)
	Set the maximum time to connect to the cloud while connected to cellular (blinking cyan). Default: 2 minutes. More...
int	getCellularCloudConnectTimeout () const
	Returns the maximum time to connect to the cloud while connected to cellular (blinking cyan) (in milliseconds)
EthernetCellular &	withEthernetConnectTimeout (std::chrono::milliseconds value)
	Set the maximum time to connect to Ethernet (blinking green). Default: 30 seconds. More...
int	getEthernetConnectTimeout () const
	Returns the maximum time to connect to Ethernet (blinking green) (in milliseconds)
EthernetCellular &	withEthernetCloudConnectTimeout (std::chrono::milliseconds value)
	Set the maximum time to connect to the cloud while connected to Ethernet (blinking cyan). Default: 30 seconds. More...
int	getEthernetCloudConnectTimeout () const
	Returns the maximum time to connect to the cloud while connected to Ethernet (blinking cyan) (in milliseconds)
EthernetCellular &	withCellularBackupColor (uint32_t value=RGB_COLOR_CYAN)
	Sets the status LED color when using cellular backup, replacing blinking or breathing cyan (default: yellow) More...
uint32_t	getCellularBackupColor () const
	Returns the status LED color when using cellular backup. More...
ActiveInterface	getActiveInterface () const
	Returns the enumeration for the currently active interface (NONE, CELLULAR, or ETHERNET)
EthernetCellular &	withInterfaceChangeCallback (std::function< void(ActiveInterface oldInterface, ActiveInterface newInterface)> callback)
	Sets a notification callback for when the active interface changes. More...

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

Protected Member Functions
	EthernetCellular ()
	The constructor is protected because the class is a singleton. More...
virtual	~EthernetCellular ()
	The destructor is protected because the class is a singleton and cannot be deleted.
	EthernetCellular (const EthernetCellular &)=delete
EthernetCellular &	operator= (const EthernetCellular &)=delete
void	setActiveInterface (ActiveInterface newActiveInterface)
	Sets the active interface and calls the notification handler if necessary. More...
void	stateStart ()
	Starting state at boot. More...
void	stateTryEthernet ()
	Starting point for switching to Ethernet. More...
void	stateWaitEthernetReady ()
	Waits until Ethernet is ready or times out. More...
void	stateWaitEthernetCloud ()
	Waits until cloud connected while on Ethernet. More...
void	stateEthernetCloudConnected ()
	State for when cloud connected. More...
void	stateTryCellular ()
	Starting point for switching to cellular. More...
void	stateWaitCellularReady ()
	Waits until cellular is ready or times out. More...
void	stateWaitCellularCloud ()
	Waits until cloud connected while on cellular. More...
void	stateCellularCloudConnected ()
	State for when cloud is connected via cellular. More...
void	stateCellularWaitDisconnectedThenTryEthernet ()
	Waits for Particle.connected to be false then tries Ethernet again. More...

Protected Attributes
std::function< void(EthernetCellular &)>	stateHandler = &EthernetCellular::stateStart
	State handler method. More...
bool	ethernetPresent = false
	Set during stateStart if Ethernet hardware is detected.
unsigned long	stateTime = 0
	Used for determining how long to wait in a state. More...
std::chrono::seconds	ethernetKeepAlive = 25s
	Ethernet keep-alive value (default: 25 seconds) More...
std::chrono::seconds	cellularKeepAlive = 23min
	Cellular keep-alive value (default: 23 minutes) More...
std::chrono::milliseconds	retryEthernetPeriod = 5min
std::chrono::milliseconds	cellularConnectTimeout = 5min
	The maximum time to connect to cellular (blinking green). Default: 5 minutes. More...
std::chrono::milliseconds	cellularCloudConnectTimeout = 2min
	The maximum time to connect to the cloud while connected to cellular (blinking cyan). Default: 2 minutes. More...
std::chrono::milliseconds	ethernetConnectTimeout = 30s
	The maximum time to connect to Ethernet (blinking green). Default: 30 seconds. More...
std::chrono::milliseconds	ethernetCloudConnectTimeout = 30s
	The maximum time to connect to the cloud while connected to Ethernet (blinking cyan). Default: 30 seconds. More...
uint32_t	cellularBackupColor = RGB_COLOR_YELLOW
	The status LED color when using cellular backup, replacing blinking or breathing cyan (default: yellow) More...
ActiveInterface	activeInterface = ActiveInterface::NONE
	The currently active interface.
std::function< void(ActiveInterface oldInterface, ActiveInterface newInterface)>	interfaceChangeCallback = NULL
	Optional callback function to call when the active interface changes.

Static Protected Attributes
static EthernetCellular *	_instance
	Singleton instance of this class. More...

Detailed Description

This class and library is used with Gen 3 cellular devices (Boron, B Series SoM) that also have Ethernet connectivity. It is used for the case that you want to default to Ethernet, but fall back to cellular if the device loses its Ethernet connection.

This requires additional hardware such as the Ethernet FeatherWing (Boron) or the B Series evaluation board or the equivalent WizNET W5500 circuitry on your own custom B Series Base Board.

Your data operations quota is the same for both cellular and Ethernet, but extra non-cloud data (TCP or UDP) are measured for cellular but not for Ethernet. Thus if you have a large amount of non-cloud data to external servers, Ethernet can reduce your costs.

This class is necessary because Device OS will default to Ethernet, however it will only fall back to cellular if Ethernet is unplugged (no link or no DHCP). The built-in behavior will not switch if the Ethernet LAN loses Internet connectivity and is only providing local LAN access. By adding this class, you can make the device fall back to cellular on losing Internet on the Ethernet LAN.

One caveat to this is that only one network interface can be active at a time. You should expect that it will take a minute or two to fall back to cellular and connect (depending on settings). The default is to check every 5 minutes if Ethernet has come back. The caveat to this is that cloud connectivity is lost during the retry attempts, so you don't want to make the period too short, but making it very long will cause you to stay on cellular longer than necessary.

In your main application file, include the library header:

#include "EthernetCellularRK.h"

Optionally enable logging:

SerialLogHandler LogHandler(LOG_LEVEL_TRACE);

You must use system thread enabled and SEMI_AUTOMATIC mode for this library to function properly!

SYSTEM_THREAD(ENABLED);
SYSTEM_MODE(SEMI_AUTOMATIC);

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:

EthernetCellular::instance().setup();

From global application loop you must call:

EthernetCellular::instance().loop();

If you want to override default settings, use methods like:

EthernetCellular::instance().withRetryEthernetPeriod(10min);

By default, the code replaces cyan blinking or breathing of the RGB status LED to yellow when on cellular backup. To not do this and keep the cyan color always, use:

EthernetCellular::instance().withCellularBackupColor(RGB_COLOR_CYAN);

Constructor & Destructor Documentation

EthernetCellular() [1/2]

EthernetCellular::EthernetCellular ( )

protected

The constructor is protected because the class is a singleton.

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

EthernetCellular() [2/2]

EthernetCellular::EthernetCellular ( const EthernetCellular &  )

protecteddelete

This class is a singleton and cannot be copied

Member Function Documentation

getCellularBackupColor()

uint32_t EthernetCellular::getCellularBackupColor ( ) const

inline

Returns the status LED color when using cellular backup.

Value is an RGB color as a uint32_t of the form 0x00RRGGBB, matching the format of constants like RGB_COLOR_CYAN, RGB_COLOR_YELLOW, or RGB_COLOR_ORANGE.

instance()

EthernetCellular & EthernetCellular::instance ( )

static

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

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

loop()

void EthernetCellular::loop

(

)

Perform application loop operations; call this from global application loop()

You typically use EthernetCellular::instance().loop();

operator=()

EthernetCellular& EthernetCellular::operator= ( const EthernetCellular &  )

protecteddelete

This class is a singleton and cannot be copied

setActiveInterface()

void EthernetCellular::setActiveInterface ( ActiveInterface  newActiveInterface )

protected

Sets the active interface and calls the notification handler if necessary.

Internal use only

setup()

void EthernetCellular::setup

(

)

Perform setup operations; call this from global application setup()

You typically use EthernetCellular::instance().setup();

stateCellularCloudConnected()

void EthernetCellular::stateCellularCloudConnected ( )

protected

State for when cloud is connected via cellular.

Next State;

• stateWaitCellularCloud if cloud connection is lost
• stateCellularWaitDisconnectedThenTryEthernet if retryEthernetPeriod is reached and ethernetPresent is true

stateCellularWaitDisconnectedThenTryEthernet()

void EthernetCellular::stateCellularWaitDisconnectedThenTryEthernet ( )

protected

Waits for Particle.connected to be false then tries Ethernet again.

Next state:

• stateTryEthernet after Particle.connected() is false

stateEthernetCloudConnected()

void EthernetCellular::stateEthernetCloudConnected ( )

protected

State for when cloud connected.

Next State;

• stateWaitEthernetCloud if cloud connection is lost

stateStart()

void EthernetCellular::stateStart ( )

protected

Starting state at boot.

Next state:

• stateTryEthernet if Ethernet is present
• stateTryCellular if no Ethernet is present

stateTryCellular()

void EthernetCellular::stateTryCellular ( )

protected

Starting point for switching to cellular.

• Disconnects from Ethernet
• Connects to cellular
• Sets the cloud connection RGB status LED theme

Next State:

• stateWaitCellularReady (always)

stateTryEthernet()

void EthernetCellular::stateTryEthernet ( )

protected

Starting point for switching to Ethernet.

• Disconnects from Cellular
• Connects to Ethernet
• Sets the cloud connection RGB status LED theme to default (cyan)

Next State:

• stateWaitEthernetReady (always)

stateWaitCellularCloud()

void EthernetCellular::stateWaitCellularCloud ( )

protected

Waits until cloud connected while on cellular.

If connected;

• Sets the keep-alive to cellularKeepAlive

Next State:

• stateCellularCloudConnected if connected to the Particle cloud
• stateTryEthernet if cellularConnectTimeout is reached without ready and ethernetPresent is true

stateWaitCellularReady()

void EthernetCellular::stateWaitCellularReady ( )

protected

Waits until cellular is ready or times out.

If ready:

• Does a Particle.connect to reconnect to the Particle cloud

Next State:

• stateWaitCellularCloud if ready
• stateTryEthernet if cellularConnectTimeout is reached without ready and ethernetPresent is true

If there is no Ethernet controller, this state will be remained in forever until connected to cellular.

stateWaitEthernetCloud()

void EthernetCellular::stateWaitEthernetCloud ( )

protected

Waits until cloud connected while on Ethernet.

If connected;

• Sets the keep-alive to ethernetKeepAlive

Next State:

• stateEthernetCloudConnected if connected to the Particle cloud
• stateTryCellular if timeout of ethernetCloudConnectTimeout is reached

This is separate from connecting to Ethernet, because it's possible for Ethernet to be ready if the local LAN is up, but not be able to reach the Particle cloud if the Internet connection to the LAN is down.

stateWaitEthernetReady()

void EthernetCellular::stateWaitEthernetReady ( )

protected

Waits until Ethernet is ready or times out.

If ready:

• Does a Particle.connect to reconnect to the Particle cloud

Next State:

• stateWaitEthernetCloud if ready
• stateTryCellular if ethernetConnectTimeout is reached without ready

withCellularBackupColor()

EthernetCellular& EthernetCellular::withCellularBackupColor ( uint32_t  value = RGB_COLOR_CYAN )

inline

Sets the status LED color when using cellular backup, replacing blinking or breathing cyan (default: yellow)

Parameters

value

Color value, such as RGB_COLOR_CYAN, RGB_COLOR_YELLOW, or RGB_COLOR_ORANGE

When switching to cellular backup, the cloud connection color (typically blinking cyan, followed by breathing cyan) can be overridden. The default in this class is to use yellow (blinking yellow followed by breathing yellow) when on cellular backup so you can tell it's on backup, and that color is not currently used by Device OS.

If you don't want the status LED color to be overridden, make this call with no parameter or use RGB_COLOR_CYAN to use the Device OS default.

Note that this does not override the blinking green (connecting to network) which will be blinking green for both cellular and Ethernet, however it's normally not in this state for very long and there are only so many available colors.

withCellularCloudConnectTimeout()

EthernetCellular& EthernetCellular::withCellularCloudConnectTimeout ( std::chrono::milliseconds  value )

inline

Set the maximum time to connect to the cloud while connected to cellular (blinking cyan). Default: 2 minutes.

Parameters

value

The value as a chrono-literal, such as 25s for 25 seconds or 5min for 5 minutes.

The default is 2 minutes. It's normally fast, but in areas with low signal strength it make take longer.

If you want to pass in a regular integer (int) instead of a chrono literal, you can use a construct like:

int timeoutMillisecs = 60000;
 
EthernetCellular::instance().withCellularCloudConnectTimeout(std::chrono::milliseconds(timeoutMillisecs));

withCellularConnectTimeout()

EthernetCellular& EthernetCellular::withCellularConnectTimeout ( std::chrono::milliseconds  value )

inline

Set the maximum time to connect to cellular (blinking green). Default: 5 minutes.

Parameters

value

The value as a chrono-literal, such as 25s for 25 seconds or 5min for 5 minutes.

The recommended value is from 5 to 10 minutes. Setting it to short values may prevent ever being able to connect to cellular.

If you want to pass in a regular integer (int) instead of a chrono literal, you can use a construct like:

int timeoutMillisecs = 60000;
 
EthernetCellular::instance().withCellularConnectTimeout(std::chrono::milliseconds(timeoutMillisecs));

withCellularKeepAlive()

EthernetCellular& EthernetCellular::withCellularKeepAlive ( std::chrono::seconds  value )

inline

Set an cellular keep-alive value (default: 23 minutes)

Parameters

value

The value as a chrono-literal, such as 25s for 25 seconds or 5min for 5 minutes.

When the network is cellular, a keep-alive is required to keep the UDP port forwarding active so the cloud can communicate with the device. This rarely needs to be set when using the Particle SIM, but is almost certainly required for a 3rd-party SIM. With a 3rd-party SIM the value could be as low as 30 seconds, but could be a few minutes.

If the limit is too long, at the end of the period the cloud will not longer be able to communicate with the device if the connection is otherwise idle.

If you are publishing, reading variables, or calling functions, this will reset the keep-alive timer so if you are frequently sending data they keep-alive may never be reached.

If you want to pass in a regular integer (int) instead of a chrono literal, you can use a construct like:

int keepAliveSec = 300;
 
EthernetCellular::instance().withEthernetKeepAlive(std::chrono::seconds(keepAliveSec));

withEthernetCloudConnectTimeout()

EthernetCellular& EthernetCellular::withEthernetCloudConnectTimeout ( std::chrono::milliseconds  value )

inline

Set the maximum time to connect to the cloud while connected to Ethernet (blinking cyan). Default: 30 seconds.

Parameters

value

The value as a chrono-literal, such as 25s for 25 seconds or 5min for 5 minutes.

The default is 30 seconds. It should normally only take a few seconds.

If you want to pass in a regular integer (int) instead of a chrono literal, you can use a construct like:

int timeoutMillisecs = 60000;
 
EthernetCellular::instance().withEthernetCloudConnectTimeout(std::chrono::milliseconds(timeoutMillisecs));

withEthernetConnectTimeout()

EthernetCellular& EthernetCellular::withEthernetConnectTimeout ( std::chrono::milliseconds  value )

inline

Set the maximum time to connect to Ethernet (blinking green). Default: 30 seconds.

Parameters

value

The value as a chrono-literal, such as 25s for 25 seconds or 5min for 5 minutes.

This should normally be really fast, but if for some reason your Ethernet network takes a long time to establish a connection you could make the timeout longer.

If you want to pass in a regular integer (int) instead of a chrono literal, you can use a construct like:

int timeoutMillisecs = 60000;
 
EthernetCellular::instance().withEthernetConnectTimeout(std::chrono::milliseconds(timeoutMillisecs));

withEthernetKeepAlive()

EthernetCellular& EthernetCellular::withEthernetKeepAlive ( std::chrono::seconds  value )

inline

Set an Ethernet keep-alive value (default: 25 seconds)

Parameters

value

The value as a chrono-literal, such as 25s for 25 seconds or 5min for 5 minutes.

When the network is Ethernet, a keep-alive is required to keep the UDP port forwarding active so the cloud can communicate with the device. This could be as short as 30 seconds or be minutes or even hours. Since the data in Ethernet is rarely metered, this defaults to 25 seconds but can be made longer on a site-specific basis.

If the limit is too long, at the end of the period the cloud will not longer be able to communicate with the device if the connection is otherwise idle.

If you are publishing, reading variables, or calling functions, this will reset the keep-alive timer so if you are frequently sending data they keep-alive may never be reached.

If you want to pass in a regular integer (int) instead of a chrono literal, you can use a construct like:

int keepAliveSec = 300;
 
EthernetCellular::instance().withEthernetKeepAlive(std::chrono::seconds(keepAliveSec));

withInterfaceChangeCallback()

EthernetCellular& EthernetCellular::withInterfaceChangeCallback ( std::function< void(ActiveInterface oldInterface, ActiveInterface newInterface)>  callback )

inline

Sets a notification callback for when the active interface changes.

You can only have one interface change callback.

withRetryEthernetPeriod()

EthernetCellular& EthernetCellular::withRetryEthernetPeriod ( std::chrono::milliseconds  value )

inline

Set the period to try switching back to Ethernet from cellular. Default: 5 minutes.

Parameters

value

The value as a chrono-literal, such as 25s for 25 seconds or 5min for 5 minutes.

Because the Ethernet and cellular networks cannot be on at the same time, after switching to cellular backup we need to periodically switch back to Ethernet to see if it's back up. This will interrupt network connectivity for a short period of time, so you don't want to make it too short. However, you also won't switch back until this period is reached, so you'll stay on backup longer than necessary if you set it too long. The default is 5 minutes.

If you want to pass in a regular integer (int) instead of a chrono literal, you can use a construct like:

int retryEthernetSecs = 300;
 
EthernetCellular::instance().withRetryEthernetPeriod(std::chrono::milliseconds(retryEthernetSecs));

Field Documentation

_instance

EthernetCellular * EthernetCellular::_instance

staticprotected

Singleton instance of this class.

The object pointer to this class is stored here. It's NULL at system boot.

cellularBackupColor

uint32_t EthernetCellular::cellularBackupColor = RGB_COLOR_YELLOW

protected

The status LED color when using cellular backup, replacing blinking or breathing cyan (default: yellow)

When switching to cellular backup, the cloud connection color (typically blinking cyan, followed by breathing cyan) can be overridden. The default in this class is to use yellow (blinking yellow followed by breathing yellow) when on cellular backup so you can tell it's on backup, and that color is not currently used by Device OS.

If you don't want the status LED color to be overridden, make this call with no parameter or use RGB_COLOR_CYAN to use the Device OS default.

Note that this does not override the blinking green (connecting to network) which will be blinking green for both cellular and Ethernet, however it's normally not in this state for very long and there are only so many available colors.

cellularCloudConnectTimeout

std::chrono::milliseconds EthernetCellular::cellularCloudConnectTimeout = 2min

protected

The maximum time to connect to the cloud while connected to cellular (blinking cyan). Default: 2 minutes.

• The default is 2 minutes. It's normally fast, but in areas with low signal strength it make take longer.

cellularConnectTimeout

std::chrono::milliseconds EthernetCellular::cellularConnectTimeout = 5min

protected

The maximum time to connect to cellular (blinking green). Default: 5 minutes.

The recommended value is from 5 to 10 minutes. Setting it to short values may prevent ever being able to connect to cellular.

cellularKeepAlive

std::chrono::seconds EthernetCellular::cellularKeepAlive = 23min

protected

Cellular keep-alive value (default: 23 minutes)

When the network is cellular, a keep-alive is required to keep the UDP port forwarding active so the cloud can communicate with the device. This rarely needs to be set when using the Particle SIM, but is almost certainly required for a 3rd-party SIM. With a 3rd-party SIM the value could be as low as 30 seconds, but could be a few minutes.

If the limit is too long, at the end of the period the cloud will not longer be able to communicate with the device if the connection is otherwise idle.

If you are publishing, reading variables, or calling functions, this will reset the keep-alive timer so if you are frequently sending data they keep-alive may never be reached.

ethernetCloudConnectTimeout

std::chrono::milliseconds EthernetCellular::ethernetCloudConnectTimeout = 30s

protected

The maximum time to connect to the cloud while connected to Ethernet (blinking cyan). Default: 30 seconds.

The default is 30 seconds. It should normally only take a few seconds.

ethernetConnectTimeout

std::chrono::milliseconds EthernetCellular::ethernetConnectTimeout = 30s

protected

The maximum time to connect to Ethernet (blinking green). Default: 30 seconds.

This should normally be really fast, but if for some reason your Ethernet network takes a long time to establish a connection you could make the timeout longer.

ethernetKeepAlive

std::chrono::seconds EthernetCellular::ethernetKeepAlive = 25s

protected

Ethernet keep-alive value (default: 25 seconds)

When the network is Ethernet, a keep-alive is required to keep the UDP port forwarding active so the cloud can communicate with the device. This could be as short as 30 seconds or be minutes or even hours. Since the data in Ethernet is rarely metered, this defaults to 25 seconds but can be made longer on a site-specific basis.

If the limit is too long, at the end of the period the cloud will not longer be able to communicate with the device if the connection is otherwise idle.

If you are publishing, reading variables, or calling functions, this will reset the keep-alive timer so if you are frequently sending data they keep-alive may never be reached.

retryEthernetPeriod

std::chrono::milliseconds EthernetCellular::retryEthernetPeriod = 5min

protected

Period to try switching back to Ethernet from cellular. Default: 5 minutes.

• Because the Ethernet and cellular networks cannot be on at the same time, after switching to cellular backup we need to periodically switch back to Ethernet to see if it's back up. This will interrupt network connectivity for a short period of time, so you don't want to make it too short. However, you also won't switch back until this period is reached, so you'll stay on backup longer than necessary if you set it too long. The default is 5 minutes.

stateHandler

std::function<void(EthernetCellular &)> EthernetCellular::stateHandler = &EthernetCellular::stateStart

protected

State handler method.

This is one of the protected methods like stateStart.

stateTime

unsigned long EthernetCellular::stateTime = 0

protected

Used for determining how long to wait in a state.

All calculations using stateTime are safe for when millis rolls over to 0 every 49 days.

---

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

• src/EthernetCellularRK.h
• src/EthernetCellularRK.cpp