External config

Allow config to be accessed from outside the framework core code.

Author: rjwats

README.md

@@ -349,10 +349,22 @@ Alternatively you can extend [AdminSettingsService.h](lib/framework/AdminSetting
 
 ## Extending the framework
 
+It is recommend that you explore the framework code to gain a better understanding of how to use it's features. The framework provides APIs so you can add your own services or features or, if required, directly configure or observe changes to core framework features. Some of these capabilities are detailed below.
+
+### Adding a service with persistant settings
+
+The following code demonstrates how you might extend the framework with a feature which requires a username and password to be configured to drive an unspecified feature. 
+
 ```cpp
 #include <SettingsService.h>
 
-class ExampleSettingsService : public SettingsService {
+class ExampleSettings {
+ public:  
+    String username;
+    String password;
+};
+
+class ExampleSettingsService : public SettingsService<ExampleSettings> {
 
   public:
 
@@ -364,20 +376,15 @@ class ExampleSettingsService : public SettingsService {
   protected:
 
     void readFromJsonObject(JsonObject& root) {
-      _username = root["username"] | "";
-      _password = root["password"] | "";
+      _settings.username = root["username"] | "";
+      _settings.password = root["password"] | "";
     }
 
     void writeToJsonObject(JsonObject& root) {
-      root["username"] = _username;
-      root["password"] = _password;
+      root["username"] = _settings.username;
+      root["password"] = _settings.password;
     }
 
-  private:
-
-    String _username;
-    String _password;
-
 };
 ```
 
@@ -391,7 +398,7 @@ exampleSettingsService.begin();
 
 There will now be a REST service exposed on "/exampleSettings" for reading and writing (GET/POST) the settings. Any modifications will be persisted in SPIFFS, in this case to "/config/exampleSettings.json"
 
-Sometimes you need to perform an action when the settings are updated, you can achieve this by overriding the onConfigUpdated() function which gets called every time the settings are updated. You can also perform an action when the service starts by overriding the begin() function, being sure to call SettingsService::begin():
+Sometimes you need to perform an action when the settings are updated, you can achieve this by overriding the onConfigUpdated() function which gets called every time the settings are updated. You can also perform an action when the service starts by overriding the begin() function, being sure to call SettingsService::begin(). You can also provide a "loop" function in order to allow your service class continuously perform an action, calling this from the main loop.
 
 ```cpp
 
@@ -409,14 +416,56 @@ void reconfigureTheService() {
   // do whatever is required to react to the new settings
 }
 
+void loop() {
+  // execute somthing as part of the main loop
+}
+
+```
+
+### Accessing settings and services
+
+The framework supplies access to it's SettingsService instances and the SecurityManager via getter functions:
+
+SettingsService               | Description
+---------------------------- | ----------------------------------------------
+getSecurityManager()         | The security manager - detailed above
+getSecuritySettingsService() | Configures the users and other security settings
+getWiFiSettingsService()     | Configures and manages the WiFi network connection
+getAPSettingsService()       | Configures and manages the Access Point
+getNTPSettingsService()      | Configures and manages the network time
+getOTASettingsService()      | Configures and manages the Over-The-Air update feature
+
+These can be used to observe changes to settings. They can also be used to fetch or update settings directly via objects, JSON strings and JsonObjects. Here are some examples of how you may use this.
+
+Inspect the current WiFi settings:
+
+```cpp
+WiFiSettings wifiSettings = esp8266React.getWiFiSettingsService()->fetch();
+Serial.print("The ssid is:");
+Serial.println(wifiSettings.ssid);
+```
+
+Configure the SSID and password:
+
+```cpp
+WiFiSettings wifiSettings = esp8266React->getWiFiSettingsService()->fetch();
+wifiSettings.ssid = "MyNetworkSSID";
+wifiSettings.password = "MySuperSecretPassword";
+esp8266React.getWiFiSettingsService()->update(wifiSettings);
+```
+
+Observe changes to the WiFiSettings:
+
+```cpp
+esp8266React.getWiFiSettingsService()->addUpdateHandler([]() {
+   Serial.println("The WiFi Settings were updated!");
+});
 ```
 
 ## Libraries Used
 
 * [React](https://reactjs.org/)
 * [Material-UI](https://material-ui-next.com/)
 * [notistack](https://github.com/iamhosseindhv/notistack)
-* [Time](https://github.com/PaulStoffregen/Time)
-* [NtpClient](https://github.com/gmag11/NtpClient)
 * [ArduinoJson](https://github.com/bblanchon/ArduinoJson)
 * [ESPAsyncWebServer](https://github.com/me-no-dev/ESPAsyncWebServer)

lib/framework/APSettingsService.cpp

@@ -9,7 +9,11 @@ APSettingsService::~APSettingsService() {
 
 void APSettingsService::begin() {
   SettingsService::begin();
-  onConfigUpdated();
+  reconfigureAP();
+}
+
+void APSettingsService::reconfigureAP() {
+  _lastManaged = millis() - MANAGE_NETWORK_DELAY;
 }
 
 void APSettingsService::loop() {
@@ -24,7 +28,8 @@ void APSettingsService::loop() {
 
 void APSettingsService::manageAP() {
   WiFiMode_t currentWiFiMode = WiFi.getMode();
-  if (_provisionMode == AP_MODE_ALWAYS || (_provisionMode == AP_MODE_DISCONNECTED && WiFi.status() != WL_CONNECTED)) {
+  if (_settings.provisionMode == AP_MODE_ALWAYS ||
+      (_settings.provisionMode == AP_MODE_DISCONNECTED && WiFi.status() != WL_CONNECTED)) {
     if (currentWiFiMode == WIFI_OFF || currentWiFiMode == WIFI_STA) {
       startAP();
     }
@@ -37,7 +42,7 @@ void APSettingsService::manageAP() {
 
 void APSettingsService::startAP() {
   Serial.println("Starting software access point");
-  WiFi.softAP(_ssid.c_str(), _password.c_str());
+  WiFi.softAP(_settings.ssid.c_str(), _settings.password.c_str());
   if (!_dnsServer) {
     IPAddress apIp = WiFi.softAPIP();
     Serial.print("Starting captive portal on ");
@@ -65,25 +70,25 @@ void APSettingsService::handleDNS() {
 }
 
 void APSettingsService::readFromJsonObject(JsonObject& root) {
-  _provisionMode = root["provision_mode"] | AP_MODE_ALWAYS;
-  switch (_provisionMode) {
+  _settings.provisionMode = root["provision_mode"] | AP_MODE_ALWAYS;
+  switch (_settings.provisionMode) {
     case AP_MODE_ALWAYS:
     case AP_MODE_DISCONNECTED:
     case AP_MODE_NEVER:
       break;
     default:
-      _provisionMode = AP_MODE_ALWAYS;
+      _settings.provisionMode = AP_MODE_ALWAYS;
   }
-  _ssid = root["ssid"] | AP_DEFAULT_SSID;
-  _password = root["password"] | AP_DEFAULT_PASSWORD;
+  _settings.ssid = root["ssid"] | AP_DEFAULT_SSID;
+  _settings.password = root["password"] | AP_DEFAULT_PASSWORD;
 }
 
 void APSettingsService::writeToJsonObject(JsonObject& root) {
-  root["provision_mode"] = _provisionMode;
-  root["ssid"] = _ssid;
-  root["password"] = _password;
+  root["provision_mode"] = _settings.provisionMode;
+  root["ssid"] = _settings.ssid;
+  root["password"] = _settings.password;
 }
 
 void APSettingsService::onConfigUpdated() {
-  _lastManaged = millis() - MANAGE_NETWORK_DELAY;
-}
+  reconfigureAP();
+}

lib/framework/APSettingsService.h

@@ -19,7 +19,14 @@
 #define AP_SETTINGS_FILE "/config/apSettings.json"
 #define AP_SETTINGS_SERVICE_PATH "/rest/apSettings"
 
-class APSettingsService : public AdminSettingsService {
+class APSettings {
+ public:
+  uint8_t provisionMode;
+  String ssid;
+  String password;
+};
+
+class APSettingsService : public AdminSettingsService<APSettings> {
  public:
   APSettingsService(AsyncWebServer* server, FS* fs, SecurityManager* securityManager);
   ~APSettingsService();
@@ -33,17 +40,13 @@ class APSettingsService : public AdminSettingsService {
   void onConfigUpdated();
 
  private:
-  // access point settings
-  uint8_t _provisionMode;
-  String _ssid;
-  String _password;
-
   // for the mangement delay loop
   unsigned long _lastManaged;
 
   // for the captive portal
   DNSServer* _dnsServer;
 
+  void reconfigureAP();
   void manageAP();
   void startAP();
   void stopAP();

lib/framework/AdminSettingsService.h

@@ -3,14 +3,15 @@
 
 #include <SettingsService.h>
 
-class AdminSettingsService : public SettingsService {
+template <class T>
+class AdminSettingsService : public SettingsService<T> {
  public:
   AdminSettingsService(AsyncWebServer* server,
                        FS* fs,
                        SecurityManager* securityManager,
                        char const* servicePath,
                        char const* filePath) :
-      SettingsService(server, fs, servicePath, filePath),
+      SettingsService<T>(server, fs, servicePath, filePath),
       _securityManager(securityManager) {
   }
 
@@ -26,7 +27,7 @@ class AdminSettingsService : public SettingsService {
       return;
     }
     // delegate to underlying implemetation
-    SettingsService::fetchConfig(request);
+    SettingsService<T>::fetchConfig(request);
   }
 
   void updateConfig(AsyncWebServerRequest* request, JsonDocument& jsonDocument) {
@@ -37,7 +38,7 @@ class AdminSettingsService : public SettingsService {
       return;
     }
     // delegate to underlying implemetation
-    SettingsService::updateConfig(request, jsonDocument);
+    SettingsService<T>::updateConfig(request, jsonDocument);
   }
 
   // override this to replace the default authentication predicate, IS_ADMIN

lib/framework/AuthenticationService.cpp

@@ -21,7 +21,7 @@ AuthenticationService::~AuthenticationService() {
  */
 void AuthenticationService::verifyAuthorization(AsyncWebServerRequest* request) {
   Authentication authentication = _securityManager->authenticateRequest(request);
-  request->send(authentication.isAuthenticated() ? 200 : 401);
+  request->send(authentication.authenticated ? 200 : 401);
 }
 
 /**
@@ -33,8 +33,8 @@ void AuthenticationService::signIn(AsyncWebServerRequest* request, JsonDocument&
     String username = jsonDocument["username"];
     String password = jsonDocument["password"];
     Authentication authentication = _securityManager->authenticate(username, password);
-    if (authentication.isAuthenticated()) {
-      User* user = authentication.getUser();
+    if (authentication.authenticated) {
+      User* user = authentication.user;
       AsyncJsonResponse* response = new AsyncJsonResponse(false, MAX_AUTHENTICATION_SIZE);
       JsonObject jsonObject = response->getRoot();
       jsonObject["access_token"] = _securityManager->generateJWT(user);

lib/framework/ESP8266React.h

@@ -41,22 +41,41 @@ class ESP8266React {
     return &_securitySettingsService;
   }
 
+   SettingsService<SecuritySettings>* getSecuritySettingsService() {
+    return &_securitySettingsService;
+  }
+
+  SettingsService<WiFiSettings>* getWiFiSettingsService() {
+    return &_wifiSettingsService;
+  }
+
+  SettingsService<APSettings>* getAPSettingsService() {
+    return &_apSettingsService;
+  }
+
+  SettingsService<NTPSettings>* getNTPSettingsService() {
+    return &_ntpSettingsService;
+  }
+
+  SettingsService<OTASettings>* getOTASettingsService() {
+    return &_otaSettingsService;
+  }
+
  private:
   SecuritySettingsService _securitySettingsService;
-
   WiFiSettingsService _wifiSettingsService;
   APSettingsService _apSettingsService;
   NTPSettingsService _ntpSettingsService;
   OTASettingsService _otaSettingsService;
   RestartService _restartService;
+
   AuthenticationService _authenticationService;
 
   WiFiScanner _wifiScanner;
   WiFiStatus _wifiStatus;
   NTPStatus _ntpStatus;
   APStatus _apStatus;
   SystemStatus _systemStatus;
-
 };
 
 #endif

lib/framework/NTPSettingsService.cpp

@@ -28,17 +28,17 @@ void NTPSettingsService::loop() {
 }
 
 void NTPSettingsService::readFromJsonObject(JsonObject& root) {
-  _enabled = root["enabled"] | NTP_SETTINGS_SERVICE_DEFAULT_ENABLED;
-  _server = root["server"] | NTP_SETTINGS_SERVICE_DEFAULT_SERVER;
-  _tzLabel = root["tz_label"] | NTP_SETTINGS_SERVICE_DEFAULT_TIME_ZONE_LABEL;
-  _tzFormat = root["tz_format"] | NTP_SETTINGS_SERVICE_DEFAULT_TIME_ZONE_FORMAT;
+  _settings.enabled = root["enabled"] | NTP_SETTINGS_SERVICE_DEFAULT_ENABLED;
+  _settings.server = root["server"] | NTP_SETTINGS_SERVICE_DEFAULT_SERVER;
+  _settings.tzLabel = root["tz_label"] | NTP_SETTINGS_SERVICE_DEFAULT_TIME_ZONE_LABEL;
+  _settings.tzFormat = root["tz_format"] | NTP_SETTINGS_SERVICE_DEFAULT_TIME_ZONE_FORMAT;
 }
 
 void NTPSettingsService::writeToJsonObject(JsonObject& root) {
-  root["enabled"] = _enabled;
-  root["server"] = _server;
-  root["tz_label"] = _tzLabel;
-  root["tz_format"] = _tzFormat;
+  root["enabled"] = _settings.enabled;
+  root["server"] = _settings.server;
+  root["tz_label"] = _settings.tzLabel;
+  root["tz_format"] = _settings.tzFormat;
 }
 
 void NTPSettingsService::onConfigUpdated() {
@@ -47,37 +47,37 @@ void NTPSettingsService::onConfigUpdated() {
 
 #ifdef ESP32
 void NTPSettingsService::onStationModeGotIP(WiFiEvent_t event, WiFiEventInfo_t info) {
-  Serial.printf("Got IP address, starting NTP Synchronization\n");
+  Serial.println("Got IP address, starting NTP Synchronization");
   _reconfigureNTP = true;
 }
 
 void NTPSettingsService::onStationModeDisconnected(WiFiEvent_t event, WiFiEventInfo_t info) {
-  Serial.printf("WiFi connection dropped, stopping NTP.\n");
+  Serial.println("WiFi connection dropped, stopping NTP.");
   _reconfigureNTP = false;
   sntp_stop();
 }
 #elif defined(ESP8266)
 void NTPSettingsService::onStationModeGotIP(const WiFiEventStationModeGotIP& event) {
-  Serial.printf("Got IP address, starting NTP Synchronization\n");
+  Serial.println("Got IP address, starting NTP Synchronization");
   _reconfigureNTP = true;
 }
 
 void NTPSettingsService::onStationModeDisconnected(const WiFiEventStationModeDisconnected& event) {
-  Serial.printf("WiFi connection dropped, stopping NTP.\n");
+  Serial.println("WiFi connection dropped, stopping NTP.");
   _reconfigureNTP = false;
   sntp_stop();
 }
 #endif
 
 void NTPSettingsService::configureNTP() {
   Serial.println("Configuring NTP...");
-  if (_enabled) {
+  if (_settings.enabled) {
 #ifdef ESP32
-    configTzTime(_tzFormat.c_str(), _server.c_str());
+    configTzTime(_settings.tzFormat.c_str(), _settings.server.c_str());
 #elif defined(ESP8266)
-    configTime(_tzFormat.c_str(), _server.c_str());
+    configTime(_settings.tzFormat.c_str(), _settings.server.c_str());
 #endif
   } else {
-     sntp_stop();
+    sntp_stop();
   }
 }