Cloud functions

Particle.keepAlive()

On all Gen 3 devices (Argon, Boron, B-Series SoM, Tracker) and Gen 2 cellular devices:

Sets the duration between keep-alive messages used to maintain the connection to the cloud.

// PROTOTYPE
static void keepAlive(unsigned sec);

// SYNTAX
Particle.keepAlive(23 * 60);    // send a ping every 23 minutes

A keep-alive is used to implement "UDP hole punching" which helps maintain the connection from the cloud to the device. A temporary port-forwarded back-channel is set up by the network to allow packets to be sent from the cloud to the device. As this is a finite resource, unused back-channels are periodically deleted by the network.

Should a device becomes unreachable from the cloud (such as a timed out function call or variable get), one possible cause of this is that the keep alives have not been sent often enough.

The keep-alive for cellular devices duration varies by mobile network operator. The default keep-alive is set to 23 minutes, which is sufficient to maintain the connection on Particle SIM cards. 3rd party SIM cards will need to determine the appropriate keep alive value, typically ranging from 30 seconds to several minutes.

Note: Each keep alive ping consumes 122 bytes of data (61 bytes sent, 61 bytes received).

For Ethernet, you will probably want to set a keepAlive to 25 seconds, like the Argon. In some cases, it could be raised to 2 to 5 minutes; this is dependent on how quickly the Internet router at the site releases port-forwarded back-channel.

For the Argon, the keep-alive is not generally needed. However, in unusual networking situations if the network router/firewall removes the port forwarded back-channels unusually aggressively, you may need to use a keep-alive.

Keep-alives do not use Data Operations from your monthly or yearly quota. However, for cellular devices they do use cellular data, so setting it to a very small value can cause increased data usage, which could result in hitting the monthly data limit for your account.

Since 1.5.0:

You can also specify a value using chrono literals, for example: Particle.keepAlive(2min) for 2 minutes.

Since 6.5.0:

On devices with more than one network interface (such as the M-SoM, which can connect via cellular or Wi-Fi), you can set a keep-alive that only applies to a specific interface:

// PROTOTYPES
static void keepAlive(unsigned sec, network_interface_t network);
static void keepAlive(std::chrono::seconds s, network_interface_t network);

// SYNTAX
Particle.keepAlive(30, Cellular);
Particle.keepAlive(25, WiFi);
Particle.keepAlive(25, Ethernet);

Use Particle.getKeepAlive() to read back the keep-alive currently in effect, in seconds. With no argument, it returns the value for whichever interface the device is currently connected to the cloud on; you can also pass a specific interface:

// PROTOTYPES
static int getKeepAlive();
static int getKeepAlive(network_interface_t network);

// SYNTAX
int currentKeepAlive = Particle.getKeepAlive();
int cellularKeepAlive = Particle.getKeepAlive(Cellular);

The effective keep-alive for an interface is determined in this order:

1. A value set at runtime with Particle.keepAlive(sec, network) (or Particle.keepAlive(sec) for the currently connected interface).
2. The interface-specific environment variable: PARTICLE_CELLULAR_CLOUD_KEEP_ALIVE, PARTICLE_WIFI_CLOUD_KEEP_ALIVE, or PARTICLE_ETHERNET_CLOUD_KEEP_ALIVE.
3. The global PARTICLE_CLOUD_KEEP_ALIVE environment variable, which applies to any interface without its own override.
4. The Device OS default keep-alive for the interface, shown in the table above.

A value set with Particle.keepAlive() takes effect the next time a cloud connection is established on that interface. Environment variable changes also take effect on the next cloud (re)connection to that interface, not immediately. See Environment variables for more information on setting these variables.