Notify the cloud about keepalive interval changes

[sergeuz]

Problem

User applications can change the keepalive interval of the cloud connection via the Particle.keepAlive() method. The interval can also be changed by the system depending on the cellular provider and/or the type of the external connectivity used by the gateway device in a mesh network.

At present, the cloud has no means to determine the keepalive interval set on a particular device, and this affects the ability of the cloud to track the online status of the device accurately.

Solution

Publish a special private event (particle/device/keepalive) containing the actual value of the keepalive interval every time the interval changes.

Steps to Test

Flash the example application to a device. Subscribe to the device's events and verify that keepalive events get published when the keepalive interval is changed.

Note: The cloud-side handler for the keepalive events is not yet implemented, so this test requires running a local instance of the device service, which has particle/device/keepalive added to the list of known internal events.

Example App

#include "application.h"

SYSTEM_MODE(MANUAL);

namespace {

int cloudStatus = cloud_status_disconnected;
bool done = false;

void cloudStatusChanged(system_event_t event, int param) {
    cloudStatus = param;
}

void waitCloudStatus(int status) {
    while (cloudStatus != status) {
        Particle.process();
    }
}

} // unnamed

void setup() {
    System.on(cloud_status, cloudStatusChanged);
}

void loop() {
    if (done) {
        return;
    }

    // The default keepalive interval should be published after the protocol handshake
    Particle.connect();
    waitCloudStatus(cloud_status_connected);
    delay(1000);

    // This should generate a new keepalive event
    Particle.keepAlive(10);

    // This should not generate a new event, since the interval has not changed
    Particle.keepAlive(10);

    // Disconnect from the cloud
    delay(1000);
    Particle.disconnect();
    waitCloudStatus(cloud_status_disconnected);

    // Set the interval before establishing a connection to the cloud. The interval should be
    // published after the protocol handshake
    Particle.keepAlive(20);
    Particle.connect();
    waitCloudStatus(cloud_status_connected);

    // Disconnect from the cloud
    delay(1000);
    Particle.disconnect();
    waitCloudStatus(cloud_status_disconnected);

    // Set the interval while the handshake is in progress. Two events should be published during
    // the handshake. Note: At present, the events may be delivered in the wrong order
    Particle.connect();
    waitCloudStatus(cloud_status_connecting);
    // Run one more iteration of the system loop to let the system start the handshake
    Particle.process();
    Particle.keepAlive(30);

    // Disconnect from the cloud
    delay(1000);
    Particle.disconnect();
    waitCloudStatus(cloud_status_disconnected);

    done = true;
}

[m-mcgowan]

The device service presently already has the [spark/particle]/session/timeout event, which was made before we had UDP, so the name is now somewhat confusing, but it serves to feed the IdleChecker about how long to consider the device offline.

[sergeuz]

Good to know, thanks! I also noticed that the device service expects the interval to be in seconds, while the current code sends it in milliseconds. Are we sure it's safe if Device OS will start publishing session/timeout events? cc @JamesHagerman

[sergeuz]

@m-mcgowan @JamesHagerman Pinging here again. Should I change the event name to particle/session/timeout?

[sergeuz]

For visibility: we discussed this internally and decided to use the new event name for now.

[sergeuz]

@m-mcgowan Does the rest of the PR look good to you?

[m-mcgowan]

I agree with this. The comms layer just provides the timeout and the system layer manages the multiple stakeholders that may choose to change it. Similarly to how we manage the LED.