From 17bdfeaaf0540ebe11eff6df632764cd49a3c07e Mon Sep 17 00:00:00 2001 From: Patrick Balsiger Date: Fri, 22 Aug 2025 15:51:47 +0200 Subject: [PATCH] docs: update README.md --- README.md | 96 +++++++++++++++++++++---------------------------------- 1 file changed, 36 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 0db78d0..5428fdc 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,21 @@ SPORE is a cluster engine for ESP8266 microcontrollers that provides automatic node discovery, health monitoring, and over-the-air updates in a distributed network environment. +## Table of Contents + +- [Features](#features) +- [Supported Hardware](#supported-hardware) +- [Architecture](#architecture) +- [API Reference](#api-reference) +- [Configuration](#configuration) +- [Development](#development) +- [Current Limitations](#current-limitations) +- [Troubleshooting](#troubleshooting) +- [Documentation](#documentation) +- [Contributing](#contributing) +- [License](#license) +- [Acknowledgments](#acknowledgments) + ## Features - **WiFi Management**: Automatic WiFi STA/AP configuration with MAC-based hostname generation @@ -36,24 +51,32 @@ SPORE uses a modular architecture with automatic node discovery, health monitori - **Health Monitoring**: Continuous status checking via HTTP API - **Task Scheduling**: Background tasks at configurable intervals - **Event System**: Local and cluster-wide event publishing/subscription +- **Status Tracking**: Automatic node categorization (ACTIVE, INACTIVE, DEAD) +- **Resource Monitoring**: Memory, CPU, flash, and API endpoint tracking +- **WiFi Fallback**: Automatic access point creation if connection fails 📖 **Detailed Architecture:** See [`docs/Architecture.md`](./docs/Architecture.md) for comprehensive system design and implementation details. -## API Endpoints +## API Reference -The system provides a comprehensive RESTful API for monitoring and controlling the embedded device. +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. **Core Endpoints:** -- **`/api/node/status`** - System resources and API endpoint registry -- **`/api/cluster/members`** - Cluster membership and health status -- **`/api/node/update`** - OTA firmware updates -- **`/api/node/restart`** - System restart -- **`/api/tasks/status`** - Task management and monitoring -- **`/api/tasks/control`** - Task control operations + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/api/node/status` | GET | System resources and API endpoint registry | +| `/api/cluster/members` | GET | Cluster membership and health status | +| `/api/node/update` | POST | OTA firmware updates | +| `/api/node/restart` | POST | System restart | +| `/api/tasks/status` | GET | Task management and monitoring | +| `/api/tasks/control` | POST | Task control operations | **Response Format:** All endpoints return JSON with standardized error handling and HTTP status codes. -📖 **Complete API Reference:** See [`docs/API.md`](./docs/API.md) for detailed endpoint documentation, examples, and integration guides. +📖 **Complete API Documentation:** See [`docs/API.md`](./docs/API.md) for detailed endpoint documentation, examples, and integration guides. + +🔧 **OpenAPI Specification:** Machine-readable API spec available in [`api/`](./api/) folder for code generation and tooling integration. ## Configuration @@ -71,8 +94,6 @@ The project uses PlatformIO with Arduino framework and supports multiple ESP8266 **Environment Setup:** Create `.env` file for cluster configuration and API node settings. -📖 **Development Guide:** See [`docs/Development.md`](./docs/Development.md) for comprehensive build, deployment, and configuration instructions. - ## Development **Quick Commands:** @@ -92,52 +113,7 @@ The project uses PlatformIO with Arduino framework and supports multiple ESP8266 **Prerequisites:** PlatformIO Core, ESP8266 tools, `jq` for JSON processing -📖 **Complete Development Guide:** See [`docs/Development.md`](./docs/Development.md) for detailed build, deployment, and troubleshooting instructions. - -## API Reference - -The SPORE system provides a comprehensive RESTful API for monitoring and controlling the embedded device. All endpoints return JSON responses and support standard HTTP status codes. - -### Quick Reference - -| Endpoint | Method | Description | -|----------|--------|-------------| -| `/api/tasks/status` | GET | Get comprehensive task status | -| `/api/tasks/control` | POST | Control individual tasks | -| `/api/node/status` | GET | System resource information | -| `/api/cluster/members` | GET | Cluster membership | -| `/api/node/update` | POST | OTA firmware updates | -| `/api/node/restart` | POST | System restart | - -**Available Task Actions:** `enable`, `disable`, `start`, `stop`, `status` - -📖 **Detailed API Documentation:** See [`docs/API.md`](./docs/API.md) for complete API reference, examples, and integration guides. - -🔧 **OpenAPI Specification:** Machine-readable API spec available in [`api/`](./api/) folder for code generation and tooling integration. - -## Implementation Details - -The system uses an event-driven architecture with automatic resource monitoring and WiFi fallback capabilities. - -**Key Systems:** -- **Event System**: Local and cluster-wide event publishing/subscription -- **Status Tracking**: Automatic node categorization (ACTIVE, INACTIVE, DEAD) -- **Resource Monitoring**: Memory, CPU, flash, and API endpoint tracking -- **WiFi Fallback**: Automatic access point creation if connection fails - -📖 **Architecture Details:** See [`docs/Architecture.md`](./docs/Architecture.md) for comprehensive system design and implementation information. - -## Task Management - -The SPORE system includes a comprehensive TaskManager for background task management with runtime control and monitoring. - -**Key Features:** -- **Easy Registration**: Simple API for adding tasks with configurable intervals -- **Dynamic Control**: Enable/disable tasks at runtime without restart -- **Status Monitoring**: Real-time task health and performance tracking -- **Remote Management**: REST API for cluster-wide task control - -📖 **Complete Task Management Guide:** See [`docs/TaskManagement.md`](./docs/TaskManagement.md) for detailed usage examples, best practices, and advanced features. +📖 **Complete Development Guide:** See [`docs/Development.md`](./docs/Development.md) for comprehensive build, deployment, and troubleshooting instructions. ## Current Limitations @@ -164,14 +140,14 @@ Enable serial monitoring to see cluster activity: pio device monitor ``` -📖 **For detailed task management examples and workflows, see [`docs/API.md`](./docs/API.md).** - ## Documentation 📚 **Comprehensive documentation is available in the [`docs/`](./docs/) folder:** - **[API Reference](./docs/API.md)** - Complete API documentation with examples -- **[TaskManager Guide](./docs/TaskManager.md)** - Background task management system +- **[Architecture Guide](./docs/Architecture.md)** - System design and implementation details +- **[Development Guide](./docs/Development.md)** - Build, deployment, and configuration +- **[Task Management Guide](./docs/TaskManagement.md)** - Background task management system - **[OpenAPI Spec](./api/)** - Machine-readable API specification ## Contributing