Notify the cloud about planned disconnections

[sergeuz]

Problem

This PR implements a mechanism for graceful disconnection from the cloud on the following events:

• System reset (as part of the firmware update process or via System.reset(), System.dfu() and other APIs).
• Disconnecting via Particle.disconnect().
• Shutting down network interfaces.
• Entering the listening mode.
• Entering one of the sleep modes.

Upon any of the above events, the device first sends a Goodbye message to the cloud, waits for the message to be received by the cloud, and then proceeds to close the connection with the cloud. On UDP platforms the message is sent as a confirmable message and needs to be acknowledged by the server. On TCP platforms the delivery of the message is ensured by half-closing the socket and waiting for the server to close the connection.

The Goodbye message carries the information about the disconnection reason, system reset reason and duration of the sleep (if applicable). The format of the data is described here.

Important: This PR introduces the following changes in the current Device OS behavior:

• Device OS now completely disconnects from the cloud when going into sleep. Previously, it was leaving the comms layer and cloud socket in whatever state they were prior to entering the sleep mode.
• By default, System.reset() and other APIs no longer reset the device immediately if it's connected to the cloud.

This PR also refactors buffer appender classes (BufferAppender, BufferAppender2), so that there's only one BufferAppender class.

Steps to Test

• Run unit tests.
• Run the app/cloud_disconnect test app.

References

• [ch34913]

[m-mcgowan]

All good changes! There are a few areas we need to complete:

1. documentation: the behaviour changes to cloud disconnect and system reset should be documented so that our users are aware of these changes.

2. opt-out: if the developer doesn't want to be sending disconnection reasons to the cloud, perhaps this can be opted out, e.g. via a system flag or feature.

[sergeuz]

opt-out: if the developer doesn't want to be sending disconnection reasons to the cloud, perhaps this can be opted out, e.g. via a system flag or feature.

How about we instead add a feature flags that disables graceful disconnections altogether? I don't see much sense in disabling Goodbye messages alone, but still waiting for other unacknowledged messages when disconnecting from the cloud

[sergeuz]

I noticed that graceful cloud disconnection was implemented in 3 different places, 09ecec3c363555c9d57856bab4c734b4c1e9bf76 and 32b06be653f6b7dce0c0e9a76d631ce00c4fad94 address that

[sergeuz]

opt-out: if the developer doesn't want to be sending disconnection reasons to the cloud, perhaps this can be opted out, e.g. via a system flag or feature

@m-mcgowan It is now possible to disable graceful cloud disconnection either globally (via the SYSTEM_FLAG_DISCONNECT_IMMEDIATELY flag), or by passing the RESET_NO_WAIT flag to System.reset() and other methods that reset the device.

[m-mcgowan]

opt-out: if the developer doesn't want to be sending disconnection reasons to the cloud, perhaps this can be opted out, e.g. via a system flag or feature.

How about we instead add a feature flags that disables graceful disconnections altogether? I don't see much sense in disabling Goodbye messages alone, but still waiting for other unacknowledged messages when disconnecting from the cloud

I was thinking to save data. But we can add it later if needed.

[sergeuz]

I was thinking to save data. But we can add it later if needed.

@m-mcgowan hm, yeah, that would make sense. I'm not entirely happy about the SYSTEM_FLAG_DISCONNECT_IMMEDIATELY flag which I introduced in this PR. It feels that it acts too broadly and may actually cause problems on sleepy devices. Having something like Particle.abort() would be a much more flexible option.

How about I ditch that flag and introduce another one which would disable goodbye messages specifically?

[m-mcgowan]

How about I ditch that flag and introduce another one which would disable goodbye messages specifically?

I guess my main concern is that adding the goobye message adds two key behaviour changes:

1. disconnects take longer since they wait for the message to be ACKed
2. disconnects require more data

When introducing features, it's not always clear how these changes impact customers.

On the basis of this, I'm suggesting adding two flags: one to disable the goodbye message entirely and another to disable waiting for it (so it's sent as a non-confirmable CoAP message.) The state of these flags will be communicated to the cloud so that it knows the device is intentionally not saying goodbye when leaving. Irish Goodbye :-)

[sergeuz]

I'm suggesting adding two flags: one to disable the goodbye message entirely and another to disable waiting for it (so it's sent as a non-confirmable CoAP message.)

It can be my dislike of overly configurable interfaces, but I'd keep it simple. If the overhead of this feature is not desirable, the users are free to disable it. Allowing it to be enabled but work unreliably feels like we're inventing extra work for ourselves.

The state of these flags will be communicated to the cloud so that it knows the device is intentionally not saying goodbye when leaving. Irish Goodbye :-)

That's a good point. I'll add a relevant flag to the Hello message 👍

[sergeuz]

@m-mcgowan I added a system flag that enables/disables sending of Goodbye messages, as well as a Hello message flag that tells the cloud whether it should expect a Goodbye message from the device. Below is the summary of the changes since your last review:

• Protocol flags are now stored persistently in the session data. This allows the protocol implementation to detect changes in its configuration and trigger a new Hello message when the session is resumed.
• App state is no longer calculated as a CRC32 of other CRC32 checksums, instead, all fields comprising the app state are now compared directly. This reduces the chance of a collision.
• SYSTEM_FLAG_DISCONNECT_IMMEDIATELY was replaced with the SYSTEM_FLAG_SEND_GOODBYE flag (set to 1 by default).
• Fixed a bug with truncated describe messages introduced in this PR.

[m-mcgowan]

Looks good. 👍 Just some comments around clarification.