Notify the cloud about keepalive interval changes

communication/inc/communication_dynalib.h

@@ -68,7 +68,7 @@ DYNALIB_FN(BASE_IDX + 2, communication, extract_public_ec_key, int(uint8_t*, siz
 #define BASE_IDX2 (BASE_IDX + 1)
 #endif
 
-DYNALIB_FN(BASE_IDX2 + 0, communication, spark_protocol_set_connection_property, int(ProtocolFacade*, unsigned, unsigned, particle::protocol::connection_properties_t*, void*))
+DYNALIB_FN(BASE_IDX2 + 0, communication, spark_protocol_set_connection_property, int(ProtocolFacade*, unsigned, unsigned, const void*, void*))
 DYNALIB_FN(BASE_IDX2 + 1, communication, spark_protocol_command, int(ProtocolFacade* protocol, ProtocolCommands::Enum cmd, uint32_t data, void* reserved))
 DYNALIB_FN(BASE_IDX2 + 2, communication, spark_protocol_time_request_pending, bool(ProtocolFacade*, void*))
 DYNALIB_FN(BASE_IDX2 + 3, communication, spark_protocol_time_last_synced, system_tick_t(ProtocolFacade*, time_t*, void*))
@@ -84,6 +84,7 @@ DYNALIB_FN(BASE_IDX3 + 0, communication, spark_protocol_get_describe_data, int(P
 DYNALIB_FN(BASE_IDX3 + 1, communication, spark_protocol_post_description, int(ProtocolFacade*, int, void*))
 DYNALIB_FN(BASE_IDX3 + 2, communication, spark_protocol_to_system_error, int(int))
 DYNALIB_FN(BASE_IDX3 + 3, communication, spark_protocol_get_status, int(ProtocolFacade*, protocol_status*, void*))
+DYNALIB_FN(BASE_IDX3 + 4, communication, spark_protocol_get_connection_property, int(ProtocolFacade*, unsigned, unsigned*, void*, void*))
 
 DYNALIB_END(communication)
 

communication/inc/protocol.h

@@ -317,14 +317,24 @@ class Protocol
  pinger.init(interval, timeout);
  }
 
- void set_keepalive(system_tick_t interval, keepalive_source_t source)
+ bool set_keepalive(system_tick_t interval, keepalive_source_t source)
  {
- pinger.set_interval(interval, source);
+ return pinger.set_interval(interval, source);
  }
 
- void set_fast_ota(unsigned data)
+ system_tick_t get_keepalive(keepalive_source_t* source = nullptr) const
  {
- chunkedTransfer.set_fast_ota(data);
+ return pinger.get_interval(source);
+ }
+
+ void set_fast_ota(bool enabled)
+ {
+ chunkedTransfer.set_fast_ota(enabled);
+ }
+
+ bool get_fast_ota() const
+ {
+ return chunkedTransfer.get_fast_ota();
  }
 
  void set_handlers(CommunicationsHandlers& handlers)

communication/inc/protocol_defs.h

@@ -50,6 +50,8 @@ enum ProtocolError
  /* 24 */ IO_ERROR_LIGHTSSL_HANDSHAKE_NONCE,
  /* 25 */ IO_ERROR_LIGHTSSL_HANDSHAKE_RECV_KEY,
  /* 26 */ NOT_IMPLEMENTED,
+ /* 27 */ INVALID_PARAM,
+ /* 28 */ NOT_CHANGED,
 
  /*
  * NOTE: when adding more ProtocolError codes, be sure to update toSystemError() in protocol_defs.cpp

communication/inc/spark_protocol_functions.h

@@ -188,7 +188,8 @@ void spark_protocol_set_product_id(ProtocolFacade* protocol, product_id_t produc
 void spark_protocol_set_product_firmware_version(ProtocolFacade* protocol, product_firmware_version_t product_firmware_version, unsigned int param=0, void* reserved = NULL);
 void spark_protocol_get_product_details(ProtocolFacade* protocol, product_details_t* product_details, void* reserved=NULL);
 
-int spark_protocol_set_connection_property(ProtocolFacade* protocol, unsigned property_id, unsigned data, particle::protocol::connection_properties_t* conn_prop, void* reserved);
+int spark_protocol_set_connection_property(ProtocolFacade* protocol, unsigned property_id, unsigned value, const void* data, void* reserved);
+int spark_protocol_get_connection_property(ProtocolFacade* protocol, unsigned property_id, unsigned* value, void* data, void* reserved);
 bool spark_protocol_time_request_pending(ProtocolFacade* protocol, void* reserved=NULL);
 system_tick_t spark_protocol_time_last_synced(ProtocolFacade* protocol, time_t* tm, void* reserved=NULL);
 

communication/src/chunked_transfer.h

@@ -144,12 +144,17 @@ class ChunkedTransfer
 
  ProtocolError idle(MessageChannel& channel);
 
- void set_fast_ota(unsigned data)
+ void set_fast_ota(bool enabled)
  {
- fast_ota_value = (data > 0) ? true : false;
+ fast_ota_value = enabled;
  fast_ota_override = true;
  }
 
+ bool get_fast_ota() const
+ {
+ return fast_ota_value;
+ }
+
  bool is_updating()
  {
  return updating;

communication/src/ping.h

@@ -24,7 +24,15 @@ class Pinger
  this->keepalive_source = KeepAliveSource::SYSTEM;
  }
 
- void set_interval(system_tick_t interval, keepalive_source_t source)
+ /**
+ * Sets the ping interval.
+ *
+ * @param interval New interval in milliseconds.
+ * @param source Source of the interval change. The interval set by the user application takes
+ * precedence over the interval set by the system.
+ * @return `true` if the current interval has been changed or `false` otherwise.
+ */
+ bool set_interval(system_tick_t interval, keepalive_source_t source)
  {
  /**
  * LAST CURRENT UPDATE?
@@ -34,11 +42,30 @@ class Pinger
  * USER SYS NO
  * USER USER YES
  */
+ // TODO: It feels that this logic should have been implemented in the system layer
  if ( !(this->keepalive_source == KeepAliveSource::USER && source == KeepAliveSource::SYSTEM) )
  {
- this->ping_interval = interval;
  this->keepalive_source = source;
+ if (this->ping_interval != interval) {
+ this->ping_interval = interval;
+ return true;
+ }
+ }
+ return false;
+ }
+
+ /**
+ * Returns the current ping interval.
+ *
+ * @param source[out] Source of the last interval change.
+ * @return Interval in milliseconds.
+ */
+ system_tick_t get_interval(keepalive_source_t* source = nullptr) const
+ {
+ if (source) {
+ *source = keepalive_source;
  }
+ return ping_interval;
  }
 
  void reset()

communication/src/protocol_defs.cpp

@@ -49,6 +49,10 @@ system_error_t particle::protocol::toSystemError(ProtocolError error) {
  return SYSTEM_ERROR_TOO_LARGE;
  case NOT_IMPLEMENTED:
  return SYSTEM_ERROR_NOT_SUPPORTED;
+ case INVALID_PARAM:
+ return SYSTEM_ERROR_INVALID_ARGUMENT;
+ case NOT_CHANGED:
+ return SYSTEM_ERROR_NOT_CHANGED;
  default:
  return SYSTEM_ERROR_PROTOCOL; // Generic protocol error
  }

communication/src/spark_protocol_functions.cpp

@@ -190,19 +190,60 @@ void spark_protocol_get_product_details(ProtocolFacade* protocol, product_detail
  protocol->get_product_details(*details);
 }
 
-int spark_protocol_set_connection_property(ProtocolFacade* protocol, unsigned property_id,
-  unsigned data, particle::protocol::connection_properties_t* conn_prop, void* reserved)
+int spark_protocol_set_connection_property(ProtocolFacade* protocol, unsigned property_id, unsigned value,
+ const void* data, void* reserved)
 {
  ASSERT_ON_SYSTEM_THREAD();
- if (property_id == particle::protocol::Connection::PING)
- {
- protocol->set_keepalive(data, conn_prop->keepalive_source);
- } else if (property_id == particle::protocol::Connection::FAST_OTA)
- {
- protocol->set_fast_ota(data);
+ switch (property_id) {
+ case particle::protocol::Connection::PING: {
+ particle::protocol::keepalive_source_t source = particle::protocol::KeepAliveSource::SYSTEM;
+ if (data) {
+ const auto d = static_cast<const particle::protocol::connection_properties_t*>(data);
+ source = d->keepalive_source;
+ }
+ const bool changed = protocol->set_keepalive(value, source);
+ if (!changed) {
+ return particle::protocol::NOT_CHANGED;
+ }
+ return 0;
+ }
+ case particle::protocol::Connection::FAST_OTA: {
+ protocol->set_fast_ota(value);
+ return 0;
+ }
+ default:
+ return particle::protocol::INVALID_PARAM;
+ }
+}
+
+int spark_protocol_get_connection_property(ProtocolFacade* protocol, unsigned property_id, unsigned* value, void* data,
+ void* reserved)
+{
+ ASSERT_ON_SYSTEM_THREAD();
+ switch (property_id) {
+ case particle::protocol::Connection::PING: {
+ particle::protocol::keepalive_source_t source = particle::protocol::KeepAliveSource::SYSTEM;
+ const system_tick_t interval = protocol->get_keepalive(&source);
+ if (value) {
+ *value = interval;
+ }
+ if (data) {
+ const auto d = static_cast<particle::protocol::connection_properties_t*>(data);
+ d->keepalive_source = source;
+ }
+ return 0;
+ }
+ case particle::protocol::Connection::FAST_OTA: {
+ if (value) {
+ *value = protocol->get_fast_ota();
+ }
+ return 0;
+ }
+ default:
+ return particle::protocol::INVALID_PARAM;
  }
- return 0;
 }
+
 int spark_protocol_command(ProtocolFacade* protocol, ProtocolCommands::Enum cmd, uint32_t data, void* reserved)
 {
  ASSERT_ON_SYSTEM_THREAD();
@@ -214,6 +255,7 @@ bool spark_protocol_time_request_pending(ProtocolFacade* protocol, void* reserve
  (void)reserved;
  return protocol->time_request_pending();
 }
+
 system_tick_t spark_protocol_time_last_synced(ProtocolFacade* protocol, time_t* tm, void* reserved)
 {
  (void)reserved;
@@ -348,10 +390,16 @@ void spark_protocol_get_product_details(CoreProtocol* protocol, product_details_
  protocol->get_product_details(*details);
 }
 
-int spark_protocol_set_connection_property(CoreProtocol* protocol, unsigned property_id,
- unsigned data, particle::protocol::connection_properties_t* conn_prop, void* reserved)
+int spark_protocol_set_connection_property(CoreProtocol* protocol, unsigned property_id, unsigned value, const void* data,
+ void* reserved)
+{
+ return particle::protocol::NOT_IMPLEMENTED;
+}
+
+int spark_protocol_get_connection_property(CoreProtocol* protocol, unsigned property_id, unsigned* value, void* data,
+ void* reserved)
 {
- return 0;
+ return particle::protocol::NOT_IMPLEMENTED;
 }
 
 int spark_protocol_command(CoreProtocol* protocol, ProtocolCommands::Enum cmd, uint32_t data, void* reserved)

services/inc/system_error.h

@@ -27,6 +27,7 @@
  (BUSY, "Resource busy", -110), \
  (NOT_SUPPORTED, "Not supported", -120), \
  (NOT_ALLOWED, "Not allowed", -130), \
+ (NOT_CHANGED, "Not changed", -131), \
  (CANCELLED, "Operation cancelled", -140), \
  (ABORTED, "Operation aborted", -150), \
  (TIMEOUT, "Timeout error", -160), \

system/inc/system_cloud.h

@@ -242,7 +242,7 @@ bool spark_cloud_flag_auto_connect(void);
 
 ProtocolFacade* system_cloud_protocol_instance(void);
 
-int spark_set_connection_property(unsigned property_id, unsigned data, particle::protocol::connection_properties_t* conn_prop, void* reserved);
+int spark_set_connection_property(unsigned property_id, unsigned value, const void* data, void* reserved);
 
 int spark_set_random_seed_from_cloud_handler(void (*handler)(unsigned int), void* reserved);
 

system/inc/system_dynalib_cloud.h

@@ -48,7 +48,7 @@ DYNALIB_FN(10, system_cloud, spark_unsubscribe, void(void*))
 DYNALIB_FN(11, system_cloud, spark_sync_time, bool(void*))
 DYNALIB_FN(12, system_cloud, spark_sync_time_pending, bool(void*))
 DYNALIB_FN(13, system_cloud, spark_sync_time_last, system_tick_t(time_t*, void*))
-DYNALIB_FN(14, system_cloud, spark_set_connection_property, int(unsigned, unsigned, particle::protocol::connection_properties_t*, void*))
+DYNALIB_FN(14, system_cloud, spark_set_connection_property, int(unsigned, unsigned, const void*, void*))
 DYNALIB_FN(15, system_cloud, spark_set_random_seed_from_cloud_handler, int(void (*handler)(unsigned int), void*))
 DYNALIB_FN(16, system_cloud, spark_publish_vitals, int(system_tick_t, void*))
 

system/src/system_cloud.cpp

@@ -53,6 +53,7 @@ extern void (*random_seed_from_cloud_handler)(unsigned int);
 namespace
 {
 
+using namespace particle;
 using namespace particle::system;
 
 #if PLATFORM_THREADING
@@ -245,10 +246,21 @@ String spark_deviceID(void)
  return bytes2hex(id, len);
 }
 
-int spark_set_connection_property(unsigned property_id, unsigned data, particle::protocol::connection_properties_t* conn_prop, void* reserved)
+int spark_set_connection_property(unsigned property_id, unsigned value, const void* data, void* reserved)
 {
- SYSTEM_THREAD_CONTEXT_SYNC(spark_set_connection_property(property_id, data, conn_prop, reserved));
- return spark_protocol_set_connection_property(sp, property_id, data, conn_prop, reserved);
+ SYSTEM_THREAD_CONTEXT_SYNC(spark_set_connection_property(property_id, value, data, reserved));
+ const auto r = spark_protocol_set_connection_property(sp, property_id, value, data, reserved);
+ if (r != 0) {
+ return spark_protocol_to_system_error(r);
+ }
+ // Publish the new keepalive interval if the connection to the cloud is established or the
+ // system handshake is in progress
+ if (property_id == protocol::Connection::PING && (spark_cloud_flag_connected() || SPARK_CLOUD_HANDSHAKE_PENDING)) {
+ if (!publishKeepaliveInterval(value)) {
+ LOG(WARN, "Unable to publish the keepalive interval");
+ }
+ }
+ return 0;
 }
 
 int spark_set_random_seed_from_cloud_handler(void (*handler)(unsigned int), void* reserved)

system/src/system_cloud_internal.cpp

@@ -54,6 +54,7 @@
 
 using particle::CloudDiagnostics;
 using particle::publishEvent;
+using particle::publishKeepaliveInterval;
 
 #ifndef SPARK_NO_CLOUD
 
@@ -358,6 +359,7 @@ constexpr const char KEY_RESTORE_EVENT[] = "spark/device/key/restore";
 constexpr const char DEVICE_UPDATES_EVENT[] = "particle/device/updates/";
 constexpr const char FORCED_EVENT[] = "forced";
 constexpr const char UPDATES_PENDING_EVENT[] = "pending";
+constexpr const char KEEPALIVE_INTERVAL_EVENT[] = "particle/device/keepalive";
 
 inline bool is_suffix(const char* eventName, const char* prefix, const char* suffix) {
  // todo - sanity check parameters?
@@ -1001,6 +1003,7 @@ int Spark_Handshake(bool presence_announce)
  }
 
  Send_Firmware_Update_Flags();
+ publishKeepaliveInterval();
 
  if (presence_announce) {
  Multicast_Presence_Announcement();
@@ -1018,6 +1021,7 @@ int Spark_Handshake(bool presence_announce)
 
  publishSafeModeEventIfNeeded();
  Send_Firmware_Update_Flags();
+ publishKeepaliveInterval();
 
  if (!HAL_RTC_Time_Is_Valid(nullptr) && spark_sync_time_last(nullptr, nullptr) == 0) {
  spark_protocol_send_time_request(sp);
@@ -1114,3 +1118,28 @@ void Spark_Wake(void)
 CloudDiagnostics* CloudDiagnostics::instance() {
  return &g_cloudDiagnostics;
 }
+
+namespace particle {
+
+#ifndef SPARK_NO_CLOUD
+
+bool publishKeepaliveInterval(unsigned interval) {
+ if (!interval) {
+ // Get the current interval
+ const auto r = spark_protocol_get_connection_property(spark_protocol_instance(), protocol::Connection::PING,
+ &interval, nullptr, nullptr);
+ if (r != 0) {
+ return false;
+ }
+ }
+ // TODO: Even though the keepalive interval is not supposed to be changed frequently, it would be
+ // nice to make sure the previously published event is either sent or cancelled before publishing
+ // a new event. This would help to mitigate the effect of possible out of order delivery
+ char buf[16] = {};
+ snprintf(buf, sizeof(buf), "%u", interval);
+ return publishEvent(KEEPALIVE_INTERVAL_EVENT, buf);
+}
+
+#endif // !defined(SPARK_NO_CLOUD)
+
+} // particle

system/src/system_cloud_internal.h

@@ -136,6 +136,8 @@ inline bool publishEvent(const char* event, const char* data = nullptr, unsigned
  return spark_send_event(event, data, DEFAULT_CLOUD_EVENT_TTL, flags | PUBLISH_EVENT_FLAG_PRIVATE, nullptr);
 }
 
+bool publishKeepaliveInterval(unsigned interval = 0);
+
 } // namespace particle
 
 #ifdef __cplusplus