iot/spore
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README.md

Browse Source
This commit is contained in:
0x1d
2025-08-22 15:51:47 +02:00
parent 30a5f8b8cb
commit 17bdfeaaf0
1 changed files with 36 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

96
README.md
View File

@@ -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