From bf17684dc6f925bb66d0464404ace2c0da38c7a7 Mon Sep 17 00:00:00 2001 From: Patrick Balsiger Date: Sat, 13 Sep 2025 21:17:54 +0200 Subject: [PATCH] feat: implement Spore framework class as main orchestration layer - Add Spore class as unified interface for all core framework functionality - Implement setup() and begin() methods for flexible initialization pattern - Add service registration with addService() for both raw and smart pointers - Provide accessor methods for core components (getTaskManager, getContext, etc.) - Automatically include core services (Node, Network, Cluster, Task) - Update all examples to use simplified Spore framework approach - Fix circular dependency issues in include structure - Remove setHostname and setApiPort configuration methods - Add comprehensive documentation and usage examples The Spore class encapsulates all core functionality from the base example and provides a clean, unified API for the entire framework. Examples now use just spore.setup() -> add services -> spore.begin() -> spore.loop(). --- README.md | 45 +++++++++++ examples/base/main.cpp | 53 +++--------- examples/neopattern/main.cpp | 62 +++++--------- examples/neopixel/main.cpp | 62 +++++--------- examples/relay/README.md | 46 ++++++++++- examples/relay/main.cpp | 64 +++++---------- include/ClusterManager.h | 1 - include/NodeInfo.h | 1 - include/Spore.h | 51 ++++++++++++ src/ClusterManager.cpp | 1 + src/NodeInfo.cpp | 1 + src/Spore.cpp | 153 +++++++++++++++++++++++++++++++++++ 12 files changed, 356 insertions(+), 184 deletions(-) create mode 100644 include/Spore.h create mode 100644 src/Spore.cpp diff --git a/README.md b/README.md index 3f11511..a98dba7 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,7 @@ SPORE is a cluster engine for ESP8266 microcontrollers that provides automatic n SPORE uses a modular architecture with automatic node discovery, health monitoring, and distributed task management. **Core Components:** +- **Spore Framework**: Main framework class that orchestrates all components - **Network Manager**: WiFi connection handling and hostname configuration - **Cluster Manager**: Node discovery, member list management, and health monitoring - **API Server**: HTTP API server with dynamic endpoint registration @@ -58,6 +59,50 @@ SPORE uses a modular architecture with automatic node discovery, health monitori 📖 **Detailed Architecture:** See [`docs/Architecture.md`](./docs/Architecture.md) for comprehensive system design and implementation details. +## Quick Start + +The Spore framework provides a simple, unified interface for all core functionality: + +```cpp +#include +#include "Spore.h" + +// Create Spore instance with custom labels +Spore spore({ + {"app", "my_app"}, + {"role", "controller"} +}); + +void setup() { + spore.setup(); + spore.begin(); +} + +void loop() { + spore.loop(); +} +``` + +**Adding Custom Services:** +```cpp +void setup() { + spore.setup(); + + // Create and register custom services + RelayService* relayService = new RelayService(spore.getTaskManager(), 2); + spore.addService(relayService); + + // Or using smart pointers + auto sensorService = std::make_shared(); + spore.addService(sensorService); + + // Start the API server and complete initialization + spore.begin(); +} +``` + +**Examples:** See [`examples/base/`](./examples/base/) for basic usage and [`examples/relay/`](./examples/relay/) for custom service integration. + ## API Reference The system provides a comprehensive RESTful API for monitoring and controlling the embedded device. All endpoints return JSON responses and support standard HTTP status codes. diff --git a/examples/base/main.cpp b/examples/base/main.cpp index 4f2d6dc..86f9811 100644 --- a/examples/base/main.cpp +++ b/examples/base/main.cpp @@ -1,56 +1,21 @@ #include -#include -#include "Globals.h" -#include "NodeContext.h" -#include "NetworkManager.h" -#include "ClusterManager.h" -#include "ApiServer.h" -#include "TaskManager.h" +#include "Spore.h" -// Services -#include "services/NodeService.h" -#include "services/NetworkService.h" -#include "services/ClusterService.h" -#include "services/TaskService.h" - -using namespace std; - -NodeContext ctx({ +// Create Spore instance with custom labels +Spore spore({ {"app", "base"}, {"role", "demo"} }); -NetworkManager network(ctx); -TaskManager taskManager(ctx); -ClusterManager cluster(ctx, taskManager); -ApiServer apiServer(ctx, taskManager, ctx.config.api_server_port); - -// Create services -NodeService nodeService(ctx, apiServer); -NetworkService networkService(network); -ClusterService clusterService(ctx); -TaskService taskService(taskManager); void setup() { - Serial.begin(115200); - - // Setup WiFi first - network.setupWiFi(); - - // Initialize and start all tasks - taskManager.initialize(); + // Initialize the Spore framework + spore.setup(); - // Register services and start API server - apiServer.addService(nodeService); - apiServer.addService(networkService); - apiServer.addService(clusterService); - apiServer.addService(taskService); - apiServer.begin(); - - // Print initial task status - taskManager.printTaskStatus(); + // Start the API server and complete initialization + spore.begin(); } void loop() { - taskManager.execute(); - yield(); + // Run the Spore framework loop + spore.loop(); } diff --git a/examples/neopattern/main.cpp b/examples/neopattern/main.cpp index be4588a..8d27069 100644 --- a/examples/neopattern/main.cpp +++ b/examples/neopattern/main.cpp @@ -1,17 +1,5 @@ #include -#include -#include "Globals.h" -#include "NodeContext.h" -#include "NetworkManager.h" -#include "ClusterManager.h" -#include "ApiServer.h" -#include "TaskManager.h" - -// Services -#include "services/NodeService.h" -#include "services/NetworkService.h" -#include "services/ClusterService.h" -#include "services/TaskService.h" +#include "Spore.h" #include "NeoPatternService.h" #ifndef LED_STRIP_PIN @@ -26,46 +14,32 @@ #define LED_STRIP_TYPE (NEO_GRB + NEO_KHZ800) #endif -NodeContext ctx({ +// Create Spore instance with custom labels +Spore spore({ {"app", "neopattern"}, {"device", "light"}, {"pixels", String(LED_STRIP_LENGTH)}, {"pin", String(LED_STRIP_PIN)} }); -NetworkManager network(ctx); -TaskManager taskManager(ctx); -ClusterManager cluster(ctx, taskManager); -ApiServer apiServer(ctx, taskManager, ctx.config.api_server_port); -// Create services -NodeService nodeService(ctx, apiServer); -NetworkService networkService(network); -ClusterService clusterService(ctx); -TaskService taskService(taskManager); -NeoPatternService neoPatternService(taskManager, LED_STRIP_LENGTH, LED_STRIP_PIN, LED_STRIP_TYPE); +// Create custom service +NeoPatternService* neoPatternService = nullptr; void setup() { - Serial.begin(115200); - - // Setup WiFi first - network.setupWiFi(); - - // Initialize and start all tasks - taskManager.initialize(); - - // Register services and start API server - apiServer.addService(nodeService); - apiServer.addService(networkService); - apiServer.addService(clusterService); - apiServer.addService(taskService); - apiServer.addService(neoPatternService); - apiServer.begin(); - - // Print initial task status - taskManager.printTaskStatus(); + // Initialize the Spore framework + spore.setup(); + + // Create and add custom service + neoPatternService = new NeoPatternService(spore.getTaskManager(), LED_STRIP_LENGTH, LED_STRIP_PIN, LED_STRIP_TYPE); + spore.addService(neoPatternService); + + // Start the API server and complete initialization + spore.begin(); + + Serial.println("[Main] NeoPattern service registered and ready!"); } void loop() { - taskManager.execute(); - yield(); + // Run the Spore framework loop + spore.loop(); } \ No newline at end of file diff --git a/examples/neopixel/main.cpp b/examples/neopixel/main.cpp index 3e939ed..4ae0f2a 100644 --- a/examples/neopixel/main.cpp +++ b/examples/neopixel/main.cpp @@ -1,17 +1,5 @@ #include -#include -#include "Globals.h" -#include "NodeContext.h" -#include "NetworkManager.h" -#include "ClusterManager.h" -#include "ApiServer.h" -#include "TaskManager.h" - -// Services -#include "services/NodeService.h" -#include "services/NetworkService.h" -#include "services/ClusterService.h" -#include "services/TaskService.h" +#include "Spore.h" #include "NeoPixelService.h" #ifndef NEOPIXEL_PIN @@ -26,46 +14,32 @@ #define NEOPIXEL_TYPE (NEO_GRB + NEO_KHZ800) #endif -NodeContext ctx({ +// Create Spore instance with custom labels +Spore spore({ {"app", "neopixel"}, {"device", "light"}, {"pixels", String(NEOPIXEL_COUNT)}, {"pin", String(NEOPIXEL_PIN)} }); -NetworkManager network(ctx); -TaskManager taskManager(ctx); -ClusterManager cluster(ctx, taskManager); -ApiServer apiServer(ctx, taskManager, ctx.config.api_server_port); -// Create services -NodeService nodeService(ctx, apiServer); -NetworkService networkService(network); -ClusterService clusterService(ctx); -TaskService taskService(taskManager); -NeoPixelService neoPixelService(taskManager, NEOPIXEL_COUNT, NEOPIXEL_PIN, NEOPIXEL_TYPE); +// Create custom service +NeoPixelService* neoPixelService = nullptr; void setup() { - Serial.begin(115200); - - // Setup WiFi first - network.setupWiFi(); - - // Initialize and start all tasks - taskManager.initialize(); - - // Register services and start API server - apiServer.addService(nodeService); - apiServer.addService(networkService); - apiServer.addService(clusterService); - apiServer.addService(taskService); - apiServer.addService(neoPixelService); - apiServer.begin(); - - // Print initial task status - taskManager.printTaskStatus(); + // Initialize the Spore framework + spore.setup(); + + // Create and add custom service + neoPixelService = new NeoPixelService(spore.getTaskManager(), NEOPIXEL_COUNT, NEOPIXEL_PIN, NEOPIXEL_TYPE); + spore.addService(neoPixelService); + + // Start the API server and complete initialization + spore.begin(); + + Serial.println("[Main] NeoPixel service registered and ready!"); } void loop() { - taskManager.execute(); - yield(); + // Run the Spore framework loop + spore.loop(); } \ No newline at end of file diff --git a/examples/relay/README.md b/examples/relay/README.md index 16351ca..3ef3421 100644 --- a/examples/relay/README.md +++ b/examples/relay/README.md @@ -1,10 +1,48 @@ # Relay Service Example -A minimal example that uses the framework's `NodeContext`, `NetworkManager`, `TaskManager`, and `ApiServer` to control a relay via REST and log status periodically as a task. +A minimal example that demonstrates the Spore framework with a custom RelayService. The Spore framework automatically handles all core functionality (WiFi, clustering, API server, task management) while allowing easy registration of custom services. - Default relay pin: `GPIO0` (ESP-01). Override with `-DRELAY_PIN=`. - WiFi and API port are configured in `src/Config.cpp`. +## Spore Framework Usage + +This example demonstrates the simplified Spore framework approach: + +```cpp +#include +#include "Spore.h" +#include "RelayService.h" + +Spore spore({ + {"app", "relay"}, + {"device", "actuator"}, + {"pin", String(RELAY_PIN)} +}); + +RelayService* relayService = nullptr; + +void setup() { + spore.setup(); + + relayService = new RelayService(spore.getTaskManager(), RELAY_PIN); + spore.addService(relayService); + + spore.begin(); +} + +void loop() { + spore.loop(); +} +``` + +The Spore framework automatically provides: +- WiFi connectivity management +- Cluster discovery and management +- REST API server with core endpoints +- Task scheduling and execution +- Node status monitoring + ## Build & Upload - ESP‑01S: @@ -32,17 +70,17 @@ curl http://192.168.1.50/api/relay/status - Turn relay ON ```bash -curl -X POST http://192.168.1.50/api/relay/set -d state=on +curl -X POST http://192.168.1.50/api/relay -d state=on ``` - Turn relay OFF ```bash -curl -X POST http://192.168.1.50/api/relay/set -d state=off +curl -X POST http://192.168.1.50/api/relay -d state=off ``` - Toggle relay ```bash -curl -X POST http://192.168.1.50/api/relay/set -d state=toggle +curl -X POST http://192.168.1.50/api/relay -d state=toggle ``` Notes: diff --git a/examples/relay/main.cpp b/examples/relay/main.cpp index 97964a4..5fe6ef1 100644 --- a/examples/relay/main.cpp +++ b/examples/relay/main.cpp @@ -1,65 +1,37 @@ #include -#include -#include "Globals.h" -#include "NodeContext.h" -#include "NetworkManager.h" -#include "ClusterManager.h" -#include "ApiServer.h" -#include "TaskManager.h" - -// Services -#include "services/NodeService.h" -#include "services/NetworkService.h" -#include "services/ClusterService.h" -#include "services/TaskService.h" +#include "Spore.h" #include "RelayService.h" -using namespace std; - // Choose a default relay pin. For ESP-01 this is GPIO0. Adjust as needed for your board. #ifndef RELAY_PIN #define RELAY_PIN 0 #endif -NodeContext ctx({ +// Create Spore instance with custom labels +Spore spore({ {"app", "relay"}, {"device", "actuator"}, {"pin", String(RELAY_PIN)} }); -NetworkManager network(ctx); -TaskManager taskManager(ctx); -ClusterManager cluster(ctx, taskManager); -ApiServer apiServer(ctx, taskManager, ctx.config.api_server_port); -// Create services -NodeService nodeService(ctx, apiServer); -NetworkService networkService(network); -ClusterService clusterService(ctx); -TaskService taskService(taskManager); -RelayService relayService(taskManager, RELAY_PIN); +// Create custom service +RelayService* relayService = nullptr; void setup() { - Serial.begin(115200); - - // Setup WiFi first - network.setupWiFi(); - - // Initialize and start all tasks - taskManager.initialize(); - - // Register services and start API server - apiServer.addService(nodeService); - apiServer.addService(networkService); - apiServer.addService(clusterService); - apiServer.addService(taskService); - apiServer.addService(relayService); - apiServer.begin(); - - // Print initial task status - taskManager.printTaskStatus(); + // Initialize the Spore framework + spore.setup(); + + // Create and add custom service + relayService = new RelayService(spore.getTaskManager(), RELAY_PIN); + spore.addService(relayService); + + // Start the API server and complete initialization + spore.begin(); + + Serial.println("[Main] Relay service registered and ready!"); } void loop() { - taskManager.execute(); - yield(); + // Run the Spore framework loop + spore.loop(); } \ No newline at end of file diff --git a/include/ClusterManager.h b/include/ClusterManager.h index 725b040..c878a9c 100644 --- a/include/ClusterManager.h +++ b/include/ClusterManager.h @@ -1,5 +1,4 @@ #pragma once -#include "Globals.h" #include "NodeContext.h" #include "NodeInfo.h" #include "TaskManager.h" diff --git a/include/NodeInfo.h b/include/NodeInfo.h index a7cda0a..66ae6cb 100644 --- a/include/NodeInfo.h +++ b/include/NodeInfo.h @@ -1,5 +1,4 @@ #pragma once -#include "Globals.h" #include #include #include diff --git a/include/Spore.h b/include/Spore.h new file mode 100644 index 0000000..630012e --- /dev/null +++ b/include/Spore.h @@ -0,0 +1,51 @@ +#pragma once + +#include +#include +#include +#include +#include "NodeContext.h" +#include "NetworkManager.h" +#include "ClusterManager.h" +#include "ApiServer.h" +#include "TaskManager.h" +#include "services/Service.h" + +class Spore { +public: + Spore(); + Spore(std::initializer_list> initialLabels); + ~Spore(); + + // Core lifecycle methods + void setup(); + void begin(); + void loop(); + + // Service management + void addService(std::shared_ptr service); + void addService(Service* service); + + // Access to core components + NodeContext& getContext() { return ctx; } + NetworkManager& getNetwork() { return network; } + TaskManager& getTaskManager() { return taskManager; } + ClusterManager& getCluster() { return cluster; } + ApiServer& getApiServer() { return apiServer; } + + +private: + void initializeCore(); + void registerCoreServices(); + void startApiServer(); + + NodeContext ctx; + NetworkManager network; + TaskManager taskManager; + ClusterManager cluster; + ApiServer apiServer; + + std::vector> services; + bool initialized; + bool apiServerStarted; +}; diff --git a/src/ClusterManager.cpp b/src/ClusterManager.cpp index 564116d..8daee5a 100644 --- a/src/ClusterManager.cpp +++ b/src/ClusterManager.cpp @@ -1,4 +1,5 @@ #include "ClusterManager.h" +#include "Globals.h" ClusterManager::ClusterManager(NodeContext& ctx, TaskManager& taskMgr) : ctx(ctx), taskManager(taskMgr) { // Register callback for node_discovered event diff --git a/src/NodeInfo.cpp b/src/NodeInfo.cpp index 2aa8f88..ac53755 100644 --- a/src/NodeInfo.cpp +++ b/src/NodeInfo.cpp @@ -1,4 +1,5 @@ #include "NodeInfo.h" +#include "Globals.h" const char* statusToStr(NodeInfo::Status status) { switch (status) { diff --git a/src/Spore.cpp b/src/Spore.cpp new file mode 100644 index 0000000..635dc35 --- /dev/null +++ b/src/Spore.cpp @@ -0,0 +1,153 @@ +#include "Spore.h" +#include "services/NodeService.h" +#include "services/NetworkService.h" +#include "services/ClusterService.h" +#include "services/TaskService.h" +#include + +Spore::Spore() : ctx(), network(ctx), taskManager(ctx), cluster(ctx, taskManager), + apiServer(ctx, taskManager, ctx.config.api_server_port), + initialized(false), apiServerStarted(false) { +} + +Spore::Spore(std::initializer_list> initialLabels) + : ctx(initialLabels), network(ctx), taskManager(ctx), cluster(ctx, taskManager), + apiServer(ctx, taskManager, ctx.config.api_server_port), + initialized(false), apiServerStarted(false) { +} + +Spore::~Spore() { + // Services will be automatically cleaned up by shared_ptr +} + +void Spore::setup() { + if (initialized) { + Serial.println("[Spore] Already initialized, skipping setup"); + return; + } + + Serial.begin(115200); + Serial.println("[Spore] Starting Spore framework..."); + + // Initialize core components + initializeCore(); + + // Register core services + registerCoreServices(); + + initialized = true; + Serial.println("[Spore] Framework setup complete - call begin() to start API server"); +} + +void Spore::begin() { + if (!initialized) { + Serial.println("[Spore] Framework not initialized, call setup() first"); + return; + } + + if (apiServerStarted) { + Serial.println("[Spore] API server already started"); + return; + } + + Serial.println("[Spore] Starting API server..."); + + // Start API server + startApiServer(); + + // Print initial task status + taskManager.printTaskStatus(); + + Serial.println("[Spore] Framework ready!"); +} + +void Spore::loop() { + if (!initialized) { + Serial.println("[Spore] Framework not initialized, call setup() first"); + return; + } + + taskManager.execute(); + yield(); +} + +void Spore::addService(std::shared_ptr service) { + if (!service) { + Serial.println("[Spore] Warning: Attempted to add null service"); + return; + } + + services.push_back(service); + + if (apiServerStarted) { + // If API server is already started, register the service immediately + apiServer.addService(*service); + Serial.printf("[Spore] Added service '%s' to running API server\n", service->getName()); + } else { + Serial.printf("[Spore] Registered service '%s' (will be added to API server when begin() is called)\n", service->getName()); + } +} + +void Spore::addService(Service* service) { + if (!service) { + Serial.println("[Spore] Warning: Attempted to add null service"); + return; + } + + // Wrap raw pointer in shared_ptr with no-op deleter to avoid double-delete + addService(std::shared_ptr(service, [](Service*){})); +} + + +void Spore::initializeCore() { + Serial.println("[Spore] Initializing core components..."); + + // Setup WiFi first + network.setupWiFi(); + + // Initialize task manager + taskManager.initialize(); + + Serial.println("[Spore] Core components initialized"); +} + +void Spore::registerCoreServices() { + Serial.println("[Spore] Registering core services..."); + + // Create core services + auto nodeService = std::make_shared(ctx, apiServer); + auto networkService = std::make_shared(network); + auto clusterService = std::make_shared(ctx); + auto taskService = std::make_shared(taskManager); + + // Add to services list + services.push_back(nodeService); + services.push_back(networkService); + services.push_back(clusterService); + services.push_back(taskService); + + Serial.println("[Spore] Core services registered"); +} + +void Spore::startApiServer() { + if (apiServerStarted) { + Serial.println("[Spore] API server already started"); + return; + } + + Serial.println("[Spore] Starting API server..."); + + // Register all services with API server + for (auto& service : services) { + if (service) { + apiServer.addService(*service); + Serial.printf("[Spore] Added service '%s' to API server\n", service->getName()); + } + } + + // Start the API server + apiServer.begin(); + apiServerStarted = true; + + Serial.println("[Spore] API server started"); +}