chore: refactoring and docs

README.md

@@ -1,27 +1,57 @@
 # SPORE
 
-SProcket ORchestration Engine
+> SProcket ORchestration Engine
+
+SPORE is a simple cluster engine for ESP8266 microcontrollers.
 
 ## Features
 
 - WiFi STA / AP
-- node auto discovery over UDP
+- auto discovery over UDP
 - service registry
 - pub/sub event system
 - Over-The-Air updates
 
 ## Supported Hardware
 
-- ESP8266
+- ESP-01
 
-## Configuration
+## Architecture
+
+### Components
+
+The core architecture consists for following components:
+
+- Network Manager: WiFi connection handling
+- Cluster Manager: node discovery and memberlist management
+- API Server: HTTP API for interacting with node and cluster
+- Task Scheduler: internal scheduler used for system and user defined tasks
+
+### Auto Discovery
+
+A node periodically executes 2 tasks responsible for auto discovery:
+
+- send discovery: send UDP packet on broadcast address to discover nodes
+- listen for discovery: receive UDP packets and send response back to the node who initiated discovery
+
+Discovered nodes are added to the so clusters memberlist.  
+Another periodic task will then call the `/api/node/status` endpoint over HTTP on each node in the memberlist to get system resources and available API endpoints.  
+
+### Event System
+
+The `NodeContext` implements an event system for publishing and subscribing to local and cluster wide events (TODO).  
+It is used internally for communication between different components and tasks.  
+
+## Develop
+
+### Configuration
 
 Choose one of your nodes as the API node to interact with the cluster and configure it in `.env`:
 ```sh
 export API_NODE=10.0.1.x
 ```
 
-## Build
+### Build
 
 Build the firmware:
 
@@ -29,14 +59,14 @@ Build the firmware:
 ./ctl.sh build
 ```
 
-## Flash
+### Flash
 
 Flash firmware to a connected device:
 
 ```sh
 ./ctl.sh flash
 ```
-## OTA
+### OTA
 
 Update one nodes:
 

src/ApiServer.cpp

@@ -1,8 +1,8 @@
-#include "RestApiServer.h"
+#include "ApiServer.h"
 
-RestApiServer::RestApiServer(ClusterContext& ctx, uint16_t port) : server(port), ctx(ctx) {}
+ApiServer::ApiServer(NodeContext& ctx, uint16_t port) : server(port), ctx(ctx) {}
 
-void RestApiServer::addEndpoint(const String& uri, int method, std::function<void(AsyncWebServerRequest*)> requestHandler) {
+void ApiServer::addEndpoint(const String& uri, int method, std::function<void(AsyncWebServerRequest*)> requestHandler) {
     serviceRegistry.push_back(std::make_tuple(uri, method));
     // Store in NodeInfo for local node
     if (ctx.memberList && !ctx.memberList->empty()) {
@@ -11,7 +11,7 @@ void RestApiServer::addEndpoint(const String& uri, int method, std::function<voi
     server.on(uri.c_str(), method, requestHandler);
 }
 
-void RestApiServer::addEndpoint(const String& uri, int method, std::function<void(AsyncWebServerRequest*)> requestHandler,
+void ApiServer::addEndpoint(const String& uri, int method, std::function<void(AsyncWebServerRequest*)> requestHandler,
                                 std::function<void(AsyncWebServerRequest*, const String&, size_t, uint8_t*, size_t, bool)> uploadHandler) {
     serviceRegistry.push_back(std::make_tuple(uri, method));
     if (ctx.memberList && !ctx.memberList->empty()) {
@@ -20,21 +20,21 @@ void RestApiServer::addEndpoint(const String& uri, int method, std::function<voi
     server.on(uri.c_str(), method, requestHandler, uploadHandler);
 }
 
-void RestApiServer::begin() {
+void ApiServer::begin() {
     addEndpoint("/api/node/status", HTTP_GET,
-        std::bind(&RestApiServer::getSystemStatusJson, this, std::placeholders::_1));
+        std::bind(&ApiServer::onSystemStatusRequest, this, std::placeholders::_1));
     addEndpoint("/api/cluster/members", HTTP_GET,
-        std::bind(&RestApiServer::getClusterMembersJson, this, std::placeholders::_1));
+        std::bind(&ApiServer::onClusterMembersRequest, this, std::placeholders::_1));
     addEndpoint("/api/node/update", HTTP_POST,
-        std::bind(&RestApiServer::onFirmwareUpdateRequest, this, std::placeholders::_1),
-        std::bind(&RestApiServer::onFirmwareUpload, this, std::placeholders::_1, std::placeholders::_2, std::placeholders::_3, std::placeholders::_4, std::placeholders::_5, std::placeholders::_6)
+        std::bind(&ApiServer::onFirmwareUpdateRequest, this, std::placeholders::_1),
+        std::bind(&ApiServer::onFirmwareUpload, this, std::placeholders::_1, std::placeholders::_2, std::placeholders::_3, std::placeholders::_4, std::placeholders::_5, std::placeholders::_6)
     );
     addEndpoint("/api/node/restart", HTTP_POST,
-        std::bind(&RestApiServer::onRestartRequest, this, std::placeholders::_1));
+        std::bind(&ApiServer::onRestartRequest, this, std::placeholders::_1));
     server.begin();
 }
 
-void RestApiServer::getSystemStatusJson(AsyncWebServerRequest *request) {
+void ApiServer::onSystemStatusRequest(AsyncWebServerRequest *request) {
     JsonDocument doc;
     doc["freeHeap"] = ESP.getFreeHeap();
     doc["chipId"] = ESP.getChipId();
@@ -52,7 +52,7 @@ void RestApiServer::getSystemStatusJson(AsyncWebServerRequest *request) {
     request->send(200, "application/json", json);
 }
 
-void RestApiServer::getClusterMembersJson(AsyncWebServerRequest *request) {
+void ApiServer::onClusterMembersRequest(AsyncWebServerRequest *request) {
     JsonDocument doc;
     JsonArray arr = doc["members"].to<JsonArray>();
     for (const auto& node : *ctx.memberList) {
@@ -79,7 +79,7 @@ void RestApiServer::getClusterMembersJson(AsyncWebServerRequest *request) {
     request->send(200, "application/json", json);
 }
 
-void RestApiServer::methodToStr(const std::tuple<String, int> &endpoint, ArduinoJson::V742PB22::JsonObject &apiObj)
+void ApiServer::methodToStr(const std::tuple<String, int> &endpoint, ArduinoJson::V742PB22::JsonObject &apiObj)
 {
     int method = std::get<1>(endpoint);
     const char *methodStr = nullptr;
@@ -107,7 +107,7 @@ void RestApiServer::methodToStr(const std::tuple<String, int> &endpoint, Arduino
     apiObj["method"] = methodStr;
 }
 
-void RestApiServer::onFirmwareUpdateRequest(AsyncWebServerRequest *request) {
+void ApiServer::onFirmwareUpdateRequest(AsyncWebServerRequest *request) {
     bool hasError = !Update.hasError();
     AsyncWebServerResponse *response = request->beginResponse(200, "application/json", hasError ? "{\"status\": \"OK\"}" : "{\"status\": \"FAIL\"}");
     response->addHeader("Connection", "close");
@@ -119,7 +119,7 @@ void RestApiServer::onFirmwareUpdateRequest(AsyncWebServerRequest *request) {
     });
 }
 
-void RestApiServer::onFirmwareUpload(AsyncWebServerRequest *request, const String &filename, size_t index, uint8_t *data, size_t len, bool final) {
+void ApiServer::onFirmwareUpload(AsyncWebServerRequest *request, const String &filename, size_t index, uint8_t *data, size_t len, bool final) {
     if (!index) {
         Serial.print("[OTA] Update Start ");
         Serial.println(filename);
@@ -157,7 +157,7 @@ void RestApiServer::onFirmwareUpload(AsyncWebServerRequest *request, const Strin
     return;
 }
 
-void RestApiServer::onRestartRequest(AsyncWebServerRequest *request) {
+void ApiServer::onRestartRequest(AsyncWebServerRequest *request) {
     AsyncWebServerResponse *response = request->beginResponse(200, "application/json", "{\"status\": \"restarting\"}");
     response->addHeader("Connection", "close");
     request->send(response);

src/ApiServer.h

@@ -7,28 +7,26 @@
 #include <vector>
 #include <tuple>
 
-#include "ClusterContext.h"
+#include "NodeContext.h"
 #include "NodeInfo.h"
 
-#define DEBUG_UPDATER 1
-
 using namespace std;
 using namespace std::placeholders;
 
-class RestApiServer {
+class ApiServer {
 public:
-    RestApiServer(ClusterContext& ctx, uint16_t port = 80);
+    ApiServer(NodeContext& ctx, uint16_t port = 80);
     void begin();
     void addEndpoint(const String& uri, int method, std::function<void(AsyncWebServerRequest*)> requestHandler);
     void addEndpoint(const String& uri, int method, std::function<void(AsyncWebServerRequest*)> requestHandler,
                     std::function<void(AsyncWebServerRequest*, const String&, size_t, uint8_t*, size_t, bool)> uploadHandler);
 private:
     AsyncWebServer server;
-    ClusterContext& ctx;
+    NodeContext& ctx;
     std::vector<std::tuple<String, int>> serviceRegistry;
-    void getClusterMembersJson(AsyncWebServerRequest *request);
+    void onClusterMembersRequest(AsyncWebServerRequest *request);
     void methodToStr(const std::tuple<String, int> &endpoint, ArduinoJson::V742PB22::JsonObject &apiObj);
-    void getSystemStatusJson(AsyncWebServerRequest *request);
+    void onSystemStatusRequest(AsyncWebServerRequest *request);
     void onFirmwareUpdateRequest(AsyncWebServerRequest *request);
     void onFirmwareUpload(AsyncWebServerRequest *request, const String &filename, size_t index, uint8_t *data, size_t len, bool final);
     void onRestartRequest(AsyncWebServerRequest *request);

src/ClusterManager.cpp

@@ -1,8 +1,8 @@
 #include "ClusterManager.h"
 
-ClusterManager::ClusterManager(ClusterContext& ctx) : ctx(ctx) {
+ClusterManager::ClusterManager(NodeContext& ctx) : ctx(ctx) {
     // Register callback for node_discovered event
-    ctx.registerEvent("node_discovered", [this](void* data) {
+    ctx.on("node_discovered", [this](void* data) {
         NodeInfo* node = static_cast<NodeInfo*>(data);
         this->addOrUpdateNode(node->hostname, node->ip);
     });
@@ -111,7 +111,7 @@ void ClusterManager::heartbeatTaskCallback() {
             node.lastSeen = millis();
             node.status = NodeInfo::ACTIVE;
             updateLocalNodeResources();
-            ctx.triggerEvent("node_discovered", &node);
+            ctx.fire("node_discovered", &node);
             break;
         }
     }

src/ClusterManager.h

@@ -1,6 +1,6 @@
 #pragma once
 #include "Globals.h"
-#include "ClusterContext.h"
+#include "NodeContext.h"
 #include "NodeInfo.h"
 #include <Arduino.h>
 #include <ESP8266WiFi.h>
@@ -9,7 +9,7 @@
 
 class ClusterManager {
 public:
-    ClusterManager(ClusterContext& ctx);
+    ClusterManager(NodeContext& ctx);
     void sendDiscovery();
     void listenForDiscovery();
     void addOrUpdateNode(const String& nodeHost, IPAddress nodeIP);
@@ -22,5 +22,5 @@ public:
     void heartbeatTaskCallback();
     void updateAllMembersInfoTaskCallback();
 private:
-    ClusterContext& ctx;
+    NodeContext& ctx;
 };

src/NetworkManager.cpp

@@ -3,7 +3,7 @@
 const char* STA_SSID = "shroud";
 const char* STA_PASS = "th3r31sn0sp00n";
 
-NetworkManager::NetworkManager(ClusterContext& ctx) : ctx(ctx) {}
+NetworkManager::NetworkManager(NodeContext& ctx) : ctx(ctx) {}
 
 void NetworkManager::setHostnameFromMac() {
     uint8_t mac[6];
@@ -55,5 +55,5 @@ void NetworkManager::setupWiFi() {
     }
     self.lastSeen = millis();
     self.status = NodeInfo::ACTIVE;
-    ctx.triggerEvent("node_discovered", &self);
+    ctx.fire("node_discovered", &self);
 }

src/NetworkManager.h

@@ -1,12 +1,12 @@
 #pragma once
-#include "ClusterContext.h"
+#include "NodeContext.h"
 #include <ESP8266WiFi.h>
 
 class NetworkManager {
 public:
-    NetworkManager(ClusterContext& ctx);
+    NetworkManager(NodeContext& ctx);
     void setupWiFi();
     void setHostnameFromMac();
 private:
-    ClusterContext& ctx;
+    NodeContext& ctx;
 };

src/NodeContext..cpp

@@ -1,23 +1,23 @@
-#include "ClusterContext.h"
+#include "NodeContext.h"
 
-ClusterContext::ClusterContext() {
+NodeContext::NodeContext() {
     scheduler = new Scheduler();
     udp = new WiFiUDP();
     memberList = new std::vector<NodeInfo>();
     hostname = "";
 }
 
-ClusterContext::~ClusterContext() {
+NodeContext::~NodeContext() {
     delete scheduler;
     delete udp;
     delete memberList;
 }
 
-void ClusterContext::registerEvent(const std::string& event, EventCallback cb) {
+void NodeContext::on(const std::string& event, EventCallback cb) {
     eventRegistry[event].push_back(cb);
 }
 
-void ClusterContext::triggerEvent(const std::string& event, void* data) {
+void NodeContext::fire(const std::string& event, void* data) {
     for (auto& cb : eventRegistry[event]) {
         cb(data);
     }

src/NodeContext.h

@@ -7,10 +7,10 @@
 #include <map>
 #include <string>
 
-class ClusterContext {
+class NodeContext {
 public:
-    ClusterContext();
-    ~ClusterContext();
+    NodeContext();
+    ~NodeContext();
     Scheduler* scheduler;
     WiFiUDP* udp;
     String hostname;
@@ -20,6 +20,6 @@ public:
     using EventCallback = std::function<void(void*)>;
     std::map<std::string, std::vector<EventCallback>> eventRegistry;
 
-    void registerEvent(const std::string& event, EventCallback cb);
-    void triggerEvent(const std::string& event, void* data);
+    void on(const std::string& event, EventCallback cb);
+    void fire(const std::string& event, void* data);
 };

src/main.cpp

@@ -1,14 +1,14 @@
 #include <Arduino.h>
 #include "Globals.h"
-#include "ClusterContext.h"
+#include "NodeContext.h"
 #include "NetworkManager.h"
 #include "ClusterManager.h"
-#include "RestApiServer.h"
+#include "ApiServer.h"
 
-ClusterContext ctx;
+NodeContext ctx;
 NetworkManager network(ctx);
 ClusterManager cluster(ctx);
-RestApiServer apiServer(ctx);
+ApiServer apiServer(ctx);
 
 Task tSendDiscovery(TaskIntervals::SEND_DISCOVERY, TASK_FOREVER, [](){ cluster.sendDiscovery(); });
 Task tListenForDiscovery(TaskIntervals::LISTEN_FOR_DISCOVERY, TASK_FOREVER, [](){ cluster.listenForDiscovery(); });