continue documenting new features

Author: rjwats

README.md

@@ -415,12 +415,14 @@ static LightSettingsDeserializer DESERIALIZER;
 
 #### Endpoints
 
-The framework provides a [SettingsEndpoint.h](lib/framework/SettingsEndpoint.h) class which may be used to register GET and POST handlers to read and update the settings over HTTP. You may construct a SettingsEndpoint as a part of the SettingsService or separately if you prefer. The code below demonstrates how to extend the LightSettingsService class to provide an unsecured endpoint:
+The framework provides a [SettingsEndpoint.h](lib/framework/SettingsEndpoint.h) class which may be used to register GET and POST handlers to read and update the settings over HTTP. You may construct a SettingsEndpoint as a part of the SettingsService or separately if you prefer. 
+
+The code below demonstrates how to extend the LightSettingsService class to provide an unsecured endpoint:
 
 ```cpp
 class LightSettingsService : public SettingsService<LightSettings> {
  public:
-  LightSettingsService(AsyncWebServer* server, SecurityManager* securityManager) :
+  LightSettingsService(AsyncWebServer* server) :
       _settingsEndpoint(&SERIALIZER, &DESERIALIZER, this, server, "/rest/lightSettings") {
   }
 
@@ -429,28 +431,79 @@ class LightSettingsService : public SettingsService<LightSettings> {
 };
 ```
 
-Endpoint security is provided by authentication predicates which are [documented below](#security-features). A security manager and authentication predicate may be provided if an secure endpoint is required. The demo app shows how endpoints can be secured.
+Endpoint security is provided by authentication predicates which are [documented below](#security-features). The SecurityManager and authentication predicate may be provided if a secure endpoint is required. The demo project shows how endpoints can be secured.
 
 #### Persistence
 
-[SettingsPersistence.h](lib/framework/SettingsPersistence.h) allows you to save settings to the filesystem. SettingsPersistence automatically writes changes to the file system when settings are updated. This feature can be disabled by calling `disableAutomatic()` if manual control of persistence is required.
+[SettingsPersistence.h](lib/framework/SettingsPersistence.h) allows you to save settings to the filesystem. SettingsPersistence automatically writes changes to the file system when settings are updated. This feature can be disabled by calling `disableUpdateHandler()` if manual control of persistence is required.
 
-As with SettingsEndpoint you may elect to construct this as a part of a SettingsService class or separately. The code below demonstrates how to extend the LightSettingsService class to provide persistence:
+The code below demonstrates how to extend the LightSettingsService class to provide persistence:
 
 ```cpp
 class LightSettingsService : public SettingsService<LightSettings> {
  public:
-  LightSettingsService(AsyncWebServer* server, FS* fs, SecurityManager* securityManager) :
-      _settingsEndpoint(&SERIALIZER, &DESERIALIZER, this, server, "/rest/lightSettings"),
+  LightSettingsService(FS* fs) :
       _settingsPersistence(&SERIALIZER, &DESERIALIZER, this, fs, "/config/lightSettings.json") {
   }
 
  private:
-  SettingsEndpoint<LightSettings> _settingsEndpoint;
   SettingsPersistence<LightSettings> _settingsPersistence;
 };
 ```
 
+#### WebSockets
+
+[SettingsSocket.h](lib/framework/SettingsSocket.h) allows you to read and update settings over a WebSocket connection. SettingsSocket automatically pushes changes to all connected clients when settings are updated.
+
+The code below demonstrates how to extend the LightSettingsService class to provide an unsecured websocket:
+
+```cpp
+class LightSettingsService : public SettingsService<LightSettings> {
+ public:
+  LightSettingsService(AsyncWebServer* server) :
+      _settingsSocket(&SERIALIZER, &DESERIALIZER, this, server, "/ws/lightSettings"), {
+  }
+
+ private:
+  SettingsSocket<LightSettings> _settingsSocket;
+};
+```
+
+WebSocket security is provided by authentication predicates which are [documented below](#security-features). The SecurityManager and authentication predicate may be provided if a secure WebSocket is required. The demo project shows how WebSockets can be secured.
+
+#### MQTT
+
+The framework includes an MQTT client which can be configured via the UI. MQTT requirements will differ from project to project so the framework exposes the client for you to use as you see fit. The framework does however provide a utility to interface SettingsService to a pair of pub/sub (state/set) topics. This utility can be used to synchronize state with software such as Home Assistant.
+
+[SettingsBroker.h](lib/framework/SettingsBroker.h) allows you to read and update settings over a pair of MQTT topics. SettingsBroker automatically pushes changes to the pub topic and reads updates from the sub topic.
+
+The code below demonstrates how to extend the LightSettingsService class to interface with MQTT:
+
+```cpp
+class LightSettingsService : public SettingsService<LightSettings> {
+ public:
+  LightSettingsService(AsyncMqttClient* mqttClient) :
+    _settingsBroker(&SERIALIZER,
+                    &DESERIALIZER,
+                    this,
+                    mqttClient,
+                    "homeassistant/light/my_light/set",
+                    "homeassistant/light/my_light/state") {
+  }
+
+ private:
+  SettingsBroker<LightSettings> _settingsBroker;
+};
+```
+
+You can also re-configure the pub/sub topics at runtime as required:
+
+```cpp
+_settingsBroker.configureBroker("homeassistant/light/desk_lamp/set", "homeassistant/light/desk_lamp/state");
+```
+
+The demo project allows the user to modify the MQTT topics via the UI so they can be changed without re-flashing the firmware.
+
 ### Security features
 
 The framework has security features to prevent unauthorized use of the device. This is driven by [SecurityManager.h](lib/framework/SecurityManager.h).

lib/framework/SettingsBroker.h

@@ -28,11 +28,15 @@ class SettingsBroker {
   SettingsBroker(SettingsSerializer<T>* settingsSerializer,
                  SettingsDeserializer<T>* settingsDeserializer,
                  SettingsService<T>* settingsService,
-                 AsyncMqttClient* mqttClient) :
+                 AsyncMqttClient* mqttClient,
+                 String setTopic = "",
+                 String stateTopic = "") :
       _settingsSerializer(settingsSerializer),
       _settingsDeserializer(settingsDeserializer),
       _settingsService(settingsService),
-      _mqttClient(mqttClient) {
+      _mqttClient(mqttClient),
+      _setTopic(setTopic),
+      _stateTopic(stateTopic) {
     _settingsService->addUpdateHandler([&](String originId) { publish(); }, false);
     _mqttClient->onConnect(std::bind(&SettingsBroker::configureMQTT, this));
     _mqttClient->onMessage(std::bind(&SettingsBroker::onMqttMessage,
@@ -98,7 +102,8 @@ class SettingsBroker {
     DeserializationError error = deserializeJson(json, payload, len);
     if (!error && json.is<JsonObject>()) {
       _settingsService->update(
-          [&](T& settings) { _settingsDeserializer->deserialize(settings, json.as<JsonObject>()); }, SETTINGS_BROKER_ORIGIN_ID);
+          [&](T& settings) { _settingsDeserializer->deserialize(settings, json.as<JsonObject>()); },
+          SETTINGS_BROKER_ORIGIN_ID);
     }
   }
 };

lib/framework/SettingsPersistence.h

@@ -27,7 +27,7 @@ class SettingsPersistence {
       _settingsService(settingsManager),
       _fs(fs),
       _filePath(filePath) {
-    enableAutomatic();
+    enableUpdateHandler();
   }
 
   void readFromFS() {
@@ -71,14 +71,14 @@ class SettingsPersistence {
     return true;
   }
 
-  void disableAutomatic() {
+  void disableUpdateHandler() {
     if (_updateHandlerId) {
       _settingsService->removeUpdateHandler(_updateHandlerId);
       _updateHandlerId = 0;
     }
   }
 
-  void enableAutomatic() {
+  void enableUpdateHandler() {
     if (!_updateHandlerId) {
       _updateHandlerId = _settingsService->addUpdateHandler([&](String originId) { writeToFS(); });
     }

platformio.ini

@@ -6,7 +6,7 @@ default_envs = esp12e
 build_flags=
   -D NO_GLOBAL_ARDUINOOTA
   ; Uncomment ENABLE_CORS to enable Cross-Origin Resource Sharing (required for local React development)
-  -D ENABLE_CORS
+  ;-D ENABLE_CORS
   -D CORS_ORIGIN=\"http://localhost:3000\"
   ; Uncomment PROGMEM_WWW to enable the storage of the WWW data in PROGMEM
   ;-D PROGMEM_WWW

src/LightBrokerSettingsService.cpp

@@ -3,8 +3,16 @@
 static LightBrokerSettingsSerializer SERIALIZER;
 static LightBrokerSettingsDeserializer DESERIALIZER;
 
-LightBrokerSettingsService::LightBrokerSettingsService(AsyncWebServer* server, FS* fs, SecurityManager* securityManager) :
-    _settingsEndpoint(&SERIALIZER, &DESERIALIZER, this, server, LIGHT_BROKER_SETTINGS_PATH, securityManager),
+LightBrokerSettingsService::LightBrokerSettingsService(AsyncWebServer* server,
+                                                       FS* fs,
+                                                       SecurityManager* securityManager) :
+    _settingsEndpoint(&SERIALIZER,
+                      &DESERIALIZER,
+                      this,
+                      server,
+                      LIGHT_BROKER_SETTINGS_PATH,
+                      securityManager,
+                      AuthenticationPredicates::IS_AUTHENTICATED),
     _settingsPersistence(&SERIALIZER, &DESERIALIZER, this, fs, LIGHT_BROKER_SETTINGS_FILE) {
 }
 

src/LightSettingsService.cpp

@@ -10,9 +10,21 @@ LightSettingsService::LightSettingsService(AsyncWebServer* server,
                                            SecurityManager* securityManager,
                                            AsyncMqttClient* mqttClient,
                                            LightBrokerSettingsService* lightBrokerSettingsService) :
-    _settingsEndpoint(&SERIALIZER, &DESERIALIZER, this, server, LIGHT_SETTINGS_ENDPOINT_PATH, securityManager),
+    _settingsEndpoint(&SERIALIZER,
+                      &DESERIALIZER,
+                      this,
+                      server,
+                      LIGHT_SETTINGS_ENDPOINT_PATH,
+                      securityManager,
+                      AuthenticationPredicates::IS_AUTHENTICATED),
     _settingsBroker(&HA_SERIALIZER, &HA_DESERIALIZER, this, mqttClient),
-    _settingsSocket(&SERIALIZER, &DESERIALIZER, this, server, LIGHT_SETTINGS_SOCKET_PATH, securityManager),
+    _settingsSocket(&SERIALIZER,
+                    &DESERIALIZER,
+                    this,
+                    server,
+                    LIGHT_SETTINGS_SOCKET_PATH,
+                    securityManager,
+                    AuthenticationPredicates::IS_AUTHENTICATED),
     _mqttClient(mqttClient),
     _lightBrokerSettingsService(lightBrokerSettingsService) {
   // configure blink led to be output