Supports a callback with OTA status change #325

Author: Hieromon

src/AutoConnect.cpp

@@ -2,8 +2,8 @@
  *  AutoConnect class implementation.
  *  @file   AutoConnect.cpp
  *  @author [email protected]
- *  @version    1.2.3
- *  @date   2021-01-13
+ *  @version    1.3.0
+ *  @date   2021-03-29
  *  @copyright  MIT license.
  */
 
@@ -642,12 +642,14 @@ void AutoConnect::handleRequest(void) {
       _ota->attach(*this);
       _ota->authentication(_apConfig.auth);
       _ota->setTicker(_apConfig.tickerPort, _apConfig.tickerOn);
+      if (_onOTAStatusChangeExit)
+        _ota->onStatusChange(_onOTAStatusChangeExit);
     }
   }
 
   // Post-process for AutoConnectOTA
   if (_ota) {
-    if (_ota->status() == AutoConnectOTA::OTA_RIP) {
+    if (_ota->status() == AC_OTA_RIP) {
       // Indicate the reboot at the next handleClient turn
       // with on completion of the update via OTA.
       if (_webServer->client().connected()) {
@@ -659,7 +661,7 @@ void AutoConnect::handleRequest(void) {
         // OTA for firmware update requires module reset.
         _rfReset = true;
     }
-    else if (_ota->status() == AutoConnectOTA::OTA_PROGRESS)
+    else if (_ota->status() == AC_OTA_PROGRESS)
       skipPostTicker = true;
     // Reflect the menu display specifier from AutoConnectConfig to
     // AutoConnectOTA page
@@ -860,6 +862,14 @@ void AutoConnect::whileCaptivePortal(WhileCaptivePortalExit_ft fn) {
   _whileCaptivePortal = fn;
 }
 
+/**
+ *  Register a status change notification callback function
+ *  @param  fn  A status change notification callback function.
+ */
+void AutoConnect::onOTAStatusChange(OTAStatusChangeExit_ft fn) {
+  _onOTAStatusChangeExit = fn;
+}
+
 /**
  *  Load current available credential
  *  @param  ssid      A pointer to the buffer that SSID should be stored.

src/AutoConnect.h

@@ -2,8 +2,8 @@
  *	Declaration of AutoConnect class and accompanying AutoConnectConfig class.
  *	@file	AutoConnect.h
  *	@author	[email protected]
- *	@version	1.2.3
- *	@date	2021-01-13
+ *	@version	1.3.0
+ *	@date	2021-03-29
  *	@copyright	MIT license.
  */
 
@@ -29,11 +29,11 @@ using WebServerClass = WebServer;
 #include <EEPROM.h>
 #include <PageBuilder.h>
 #include "AutoConnectDefs.h"
+#include "AutoConnectTypes.h"
 #include "AutoConnectPage.h"
 #include "AutoConnectCredential.h"
 #include "AutoConnectTicker.h"
 #include "AutoConnectAux.h"
-#include "AutoConnectTypes.h"
 
 // The realization of AutoConnectOTA is effective only by the explicit
 #include "AutoConnectOTA.h"
@@ -264,10 +264,12 @@ class AutoConnect {
   typedef std::function<bool(IPAddress&)>  DetectExit_ft;
   typedef std::function<void(IPAddress&)>  ConnectExit_ft;
   typedef std::function<bool(void)>        WhileCaptivePortalExit_ft;
+  typedef std::function<bool(const AC_OTAStatus_t)> OTAStatusChangeExit_ft;
   void  onDetect(DetectExit_ft fn);
   void  onConnect(ConnectExit_ft fn);
   void  onNotFound(WebServerClass::THandlerFunction fn);
   void  whileCaptivePortal(WhileCaptivePortalExit_ft fn);
+  void  onOTAStatusChange(OTAStatusChangeExit_ft fn);
 
  protected:
   typedef enum {
@@ -329,6 +331,7 @@ class AutoConnect {
   DetectExit_ft        _onDetectExit;
   WhileCaptivePortalExit_ft _whileCaptivePortal;
   WebServerClass::THandlerFunction _notFoundHandler;
+  OTAStatusChangeExit_ft  _onOTAStatusChangeExit;
   size_t               _freeHeapSize;
 
   /** Servers which works in concert. */

src/AutoConnectOTA.cpp

@@ -2,8 +2,8 @@
  * AutoConnectOTA class implementation.
  * @file   AutoConnectOTA.cpp
  * @author [email protected]
- * @version    1.2.3
- * @date   2021-01-23
+ * @version    1.3.0
+ * @date   2021-03-29
  * @copyright  MIT license.
  */
 
@@ -230,8 +230,16 @@ bool AutoConnectOTA::_open(const char* filename, const char* mode) {
   if (bc) {
     if (_tickerPort != -1)
       pinMode(static_cast<uint8_t>(_tickerPort), OUTPUT);
-    _status = OTA_START;
+    _status = AC_OTA_START;
     AC_DBG("%s up%s start\n", filename, _dest == OTA_DEST_FIRM ? "dating" : "loading");
+
+    // Notify an OTA status change
+    if (_onStatusChange) {
+      if (!_onStatusChange(_status)) {
+        _setError("OTA cancellation requested");
+        bc = false;
+      }
+    }
   }
   return bc;
 }
@@ -244,11 +252,21 @@ bool AutoConnectOTA::_open(const char* filename, const char* mode) {
  * @return      the amount written
  */
 size_t AutoConnectOTA::_write(const uint8_t *buf, const size_t size) {
+  AC_OTAStatus_t  ps = _status;
   size_t  wsz = 0;
   if (_tickerPort != -1)
     digitalWrite(_tickerPort, digitalRead(_tickerPort) ^ 0x01);
   if (!_err.length()) {
-    _status = OTA_PROGRESS;
+    _status = AC_OTA_PROGRESS;
+    if (ps != _status) {
+      // Notify an OTA status change
+      if (_onStatusChange) {
+        if (!_onStatusChange(_status)) {
+          _setError("OTA cancellation requested");
+          return 0;
+        }
+      }
+    }
 
     if (_dest == OTA_DEST_FIRM) {
       wsz = Update.write(const_cast<uint8_t*>(buf), size);
@@ -282,8 +300,10 @@ void AutoConnectOTA::_close(const HTTPUploadStatus status) {
         _file.close();
       }
       if (ec) {
-        _status = OTA_SUCCESS;
+        _status = AC_OTA_SUCCESS;
         AC_DBG_DUMB("succeeds");
+        if (_onStatusChange)  // Notify an OTA status change
+          _onStatusChange(_status);
       }
       else {
         _setError();
@@ -315,11 +335,15 @@ String AutoConnectOTA::_updated(AutoConnectAux& result, PageArgument& args) {
 
   // Build an updating result caption.
   // Change the color of the bin name depending on the result of the update.
-  if (_status == OTA_SUCCESS) {
+  if (_status == AC_OTA_SUCCESS) {
     st = _dest == OTA_DEST_FIRM ? String(F(AUTOCONNECT_TEXT_OTASUCCESS)) : String(F(AUTOCONNECT_TEXT_OTAUPLOADED));
     stColor = PSTR("3d7e9a");
     // Notify to the handleClient of loop() thread that it can reboot.
-    _status = OTA_RIP;
+    _status = AC_OTA_RIP;
+    if (_onStatusChange) { // Notify an OTA status change
+      if (!_onStatusChange(_status))
+        _status = AC_OTA_IDLE;
+    }
   }
   else {
     st = String(F(AUTOCONNECT_TEXT_OTAFAILURE)) + _err;
@@ -347,11 +371,12 @@ String AutoConnectOTA::_updated(AutoConnectAux& result, PageArgument& args) {
 void AutoConnectOTA::_setError(void) {
   StreamString  eStr;
   Update.printError(eStr);
-  _err = String(eStr.c_str());
-  _status = OTA_FAIL;
+  _setError(eStr.c_str());
 }
 
 void AutoConnectOTA::_setError(const char* err) {
   _err = String(err);
-  _status = OTA_FAIL;
+  _status = AC_OTA_FAIL;
+  if (_onStatusChange)
+    _onStatusChange(_status);
 }

src/AutoConnectOTA.h

@@ -9,16 +9,18 @@
  * binary file.
  * @file AutoConnectOTA.h
  * @author [email protected]
- * @version  1.2.3
- * @date 2021-01-23
+ * @version  1.3.0
+ * @date 2021-03-29
  * @copyright  MIT license.
  */
 
 #ifndef _AUTOCONNECTOTA_H_
 #define _AUTOCONNECTOTA_H_
 
+#include <functional>
 #include <memory>
 #include "AutoConnect.h"
+#include "AutoConnectTypes.h"
 #include "AutoConnectUpload.h"
 
 #include <FS.h>
@@ -34,32 +36,26 @@ typedef fs::SPIFFSFS  SPIFFST;
 
 class AutoConnectOTA : public AutoConnectUploadHandler {
 public:
-  // Updating process status
-  typedef enum  {
-    OTA_IDLE,               /**< Update process has not started */
-    OTA_START,              /**< Update process has started */
-    OTA_PROGRESS,           /**< Update process in progress */
-    OTA_SUCCESS,            /**< A binary updater has uploaded fine */
-    OTA_RIP,                /**< Ready for module restart */
-    OTA_FAIL                /**< Failed to save binary updater by Update class */
-  } AC_OTAStatus_t;
+  // Type declaration of callback function to notify OTA status change
+  typedef std::function<bool(const AC_OTAStatus_t)> StatusChange_ft;
 
   // The treating destination of OTA transferred data
   typedef enum {
     OTA_DEST_FILE, /**< To be upload the file */
     OTA_DEST_FIRM  /**< To update the firmware */
   } AC_OTADest_t;
 
-  AutoConnectOTA() : _dest(OTA_DEST_FIRM), _status(OTA_IDLE), _tickerPort(-1), _tickerOn(LOW) {};
+  AutoConnectOTA() : _dest(OTA_DEST_FIRM), _status(AC_OTA_IDLE), _tickerPort(-1), _tickerOn(LOW) {};
   ~AutoConnectOTA();
   void  attach(AutoConnect& portal);                        /**< Attach itself to AutoConnect */
   void  authentication(const AC_AUTH_t auth);               /**< Set certain page authentication */
   String  error(void) const { return _err; }                /**< Returns current error string */
   void  menu(const bool post) { _auxUpdate->menu(post); }   /**< Enabel or disable arranging a created AutoConnectOTA page in the menu. */
-  void  reset(void) { _status = OTA_IDLE; }                 /**< Reset the status */
+  void  reset(void) { _status = AC_OTA_IDLE; }              /**< Reset the status */
   AC_OTAStatus_t  status(void) const { return _status; }    /**< Return a current error status of the Update class */ 
   AC_OTADest_t  dest(void) const { return _dest; }          /**< Return a current uploading destination */
   void  setTicker(int8_t pin, uint8_t on) { _tickerPort = pin, _tickerOn = on; }  /**< Set ticker LED port */
+  void  onStatusChange(StatusChange_ft fn) { _onStatusChange = fn; }  /**< Register a status change notification callback function */
 
 protected:
   template <typename T, size_t N> constexpr size_t lengthOf(T (&)[N]) noexcept {
@@ -74,6 +70,8 @@ class AutoConnectOTA : public AutoConnectUploadHandler {
   std::unique_ptr<AutoConnectAux> _auxUpdate;   /**< An update operation page */
   std::unique_ptr<AutoConnectAux> _auxResult;   /**< An update result page */
 
+  StatusChange_ft _onStatusChange;              /**< A status change notification callback function */
+
  private:
   void  _setError(void);
   void  _setError(const char* err);

src/AutoConnectTypes.h

@@ -2,8 +2,8 @@
  *  AutoConnect quoted type declarations.
  *  @file AutoConnectTypes.h
  *  @author [email protected]
- *  @version  1.2.0
- *  @date 2020-04-17
+ *  @version  1.3.0
+ *  @date 2021-03-29
  *  @copyright  MIT license.
  */
 
@@ -62,4 +62,14 @@ typedef enum AC_AUTH {
   AC_AUTH_BASIC
 } AC_AUTH_t;
 
+/**< OTA Updating process status */
+typedef enum  {
+  AC_OTA_IDLE,          /**< Update process has not started */
+  AC_OTA_START,         /**< Update process has started */
+  AC_OTA_PROGRESS,      /**< Update process in progress */
+  AC_OTA_SUCCESS,       /**< A binary updater has uploaded fine */
+  AC_OTA_RIP,           /**< Ready for module restart */
+  AC_OTA_FAIL           /**< Failed to save binary updater by Update class */
+} AC_OTAStatus_t;
+
 #endif // !_AUTOCONNECTTYPES_H_