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

feat: task manager endpoint, updated documentation

Browse Source
This commit is contained in:
0x1d
2025-08-22 15:47:08 +02:00
parent d7d307e3ce
commit 30a5f8b8cb
14 changed files with 2550 additions and 551 deletions
Download Patch File Download Diff File Expand all files Collapse all files

279
docs/API.md Normal file
View File

@@ -0,0 +1,279 @@
# SPORE API Documentation
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
### Task Management API
| Endpoint | Method | Description | Parameters | Response |
|----------|--------|-------------|------------|----------|
| `/api/tasks/status` | GET | Get comprehensive status of all tasks and system information | None | Task status overview with system metrics |
| `/api/tasks/control` | POST | Control individual task operations | `task`, `action` | Operation result with task details |
### System Status API
| Endpoint | Method | Description | Response |
|----------|--------|-------------|----------|
| `/api/node/status` | GET | System resource information and API endpoint registry | System metrics and API catalog |
| `/api/cluster/members` | GET | Cluster membership and node health information | Cluster topology and health status |
| `/api/node/update` | POST | Handle firmware updates via OTA | Update progress and status |
| `/api/node/restart` | POST | Trigger system restart | Restart confirmation |
## Detailed API Reference
### Task Management
#### GET /api/tasks/status
Returns comprehensive status information for all registered tasks, including system resource metrics and task execution details.
**Response Fields:**
| Field | Type | Description |
|-------|------|-------------|
| `summary.totalTasks` | integer | Total number of registered tasks |
| `summary.activeTasks` | integer | Number of currently enabled tasks |
| `tasks[].name` | string | Unique task identifier |
| `tasks[].interval` | integer | Execution frequency in milliseconds |
| `tasks[].enabled` | boolean | Whether task is currently enabled |
| `tasks[].running` | boolean | Whether task is actively executing |
| `tasks[].autoStart` | boolean | Whether task starts automatically |
| `system.freeHeap` | integer | Available RAM in bytes |
| `system.uptime` | integer | System uptime in milliseconds |
**Example Response:**
```json
{
"summary": {
"totalTasks": 6,
"activeTasks": 5
},
"tasks": [
{
"name": "discovery_send",
"interval": 1000,
"enabled": true,
"running": true,
"autoStart": true
}
],
"system": {
"freeHeap": 48748,
"uptime": 12345
}
}
```
#### POST /api/tasks/control
Controls the execution state of individual tasks. Supports enabling, disabling, starting, stopping, and getting detailed status for specific tasks.
**Parameters:**
- `task` (required): Name of the task to control
- `action` (required): Action to perform
**Available Actions:**
| Action | Description | Use Case |
|--------|-------------|----------|
| `enable` | Enable a disabled task | Resume background operations |
| `disable` | Disable a running task | Pause resource-intensive tasks |
| `start` | Start a stopped task | Begin task execution |
| `stop` | Stop a running task | Halt task execution |
| `status` | Get detailed status for a specific task | Monitor individual task health |
**Example Response:**
```json
{
"success": true,
"message": "Task enabled",
"task": "heartbeat",
"action": "enable"
}
```
**Task Status Response:**
```json
{
"success": true,
"message": "Task status retrieved",
"task": "discovery_send",
"action": "status",
"taskDetails": {
"name": "discovery_send",
"enabled": true,
"running": true,
"interval": 1000,
"system": {
"freeHeap": 48748,
"uptime": 12345
}
}
}
```
### System Status
#### GET /api/node/status
Returns comprehensive system resource information including memory usage, chip details, and a registry of all available API endpoints.
**Response Fields:**
- `freeHeap`: Available RAM in bytes
- `chipId`: ESP8266 chip ID
- `sdkVersion`: ESP8266 SDK version
- `cpuFreqMHz`: CPU frequency in MHz
- `flashChipSize`: Flash chip size in bytes
- `api`: Array of registered API endpoints
#### GET /api/cluster/members
Returns information about all nodes in the cluster, including their health status, resources, and API endpoints.
**Response Fields:**
- `members[]`: Array of cluster node information
- `hostname`: Node hostname
- `ip`: Node IP address
- `lastSeen`: Timestamp of last communication
- `latency`: Network latency in milliseconds
- `status`: Node health status (ACTIVE, INACTIVE, DEAD)
- `resources`: System resource information
- `api`: Available API endpoints
### System Management
#### POST /api/node/update
Initiates an over-the-air firmware update. The firmware file should be uploaded as multipart/form-data.
**Parameters:**
- `firmware`: Firmware binary file (.bin)
#### POST /api/node/restart
Triggers a system restart. The response will be sent before the restart occurs.
## HTTP Status Codes
| Code | Description | Use Case |
|------|-------------|----------|
| 200 | Success | Operation completed successfully |
| 400 | Bad Request | Invalid parameters or action |
| 404 | Not Found | Task or endpoint not found |
| 500 | Internal Server Error | System error occurred |
## OpenAPI Specification
A complete OpenAPI 3.0 specification is available in the [`api/`](../api/) folder. This specification can be used to:
- Generate client libraries in multiple programming languages
- Create interactive API documentation
- Validate API requests and responses
- Generate mock servers for testing
- Integrate with API management platforms
See [`api/README.md`](../api/README.md) for detailed usage instructions.
## Usage Examples
### Basic Task Status Check
```bash
curl -s http://10.0.1.60/api/tasks/status | jq '.'
```
### Task Control
```bash
# Disable a task
curl -X POST http://10.0.1.60/api/tasks/control \
-d "task=heartbeat&action=disable"
# Get detailed status
curl -X POST http://10.0.1.60/api/tasks/control \
-d "task=discovery_send&action=status"
```
### System Monitoring
```bash
# Check system resources
curl -s http://10.0.1.60/api/node/status | jq '.freeHeap'
# Monitor cluster health
curl -s http://10.0.1.60/api/cluster/members | jq '.members[].status'
```
## Integration Examples
### Python Client
```python
import requests
# Get task status
response = requests.get('http://10.0.1.60/api/tasks/status')
tasks = response.json()
# Check active tasks
active_count = tasks['summary']['activeTasks']
print(f"Active tasks: {active_count}")
# Control a task
control_data = {'task': 'heartbeat', 'action': 'disable'}
response = requests.post('http://10.0.1.60/api/tasks/control', data=control_data)
```
### JavaScript Client
```javascript
// Get task status
fetch('http://10.0.1.60/api/tasks/status')
.then(response => response.json())
.then(data => {
console.log(`Total tasks: ${data.summary.totalTasks}`);
console.log(`Active tasks: ${data.summary.activeTasks}`);
});
// Control a task
fetch('http://10.0.1.60/api/tasks/control', {
method: 'POST',
headers: {'Content-Type': 'application/x-www-form-urlencoded'},
body: 'task=heartbeat&action=disable'
});
```
## Task Management Examples
### Monitoring Task Health
```bash
# Check overall task status
curl -s http://10.0.1.60/api/tasks/status | jq '.'
# Monitor specific task
curl -s -X POST http://10.0.1.60/api/tasks/control \
-d "task=heartbeat&action=status" | jq '.'
# Watch for low memory conditions
watch -n 5 'curl -s http://10.0.1.60/api/tasks/status | jq ".system.freeHeap"'
```
### Task Control Workflows
```bash
# Temporarily disable discovery to reduce network traffic
curl -X POST http://10.0.1.60/api/tasks/control \
-d "task=discovery_send&action=disable"
# Check if it's disabled
curl -s -X POST http://10.0.1.60/api/tasks/control \
-d "task=discovery_send&action=status" | jq '.taskDetails.enabled'
# Re-enable when needed
curl -X POST http://10.0.1.60/api/tasks/control \
-d "task=discovery_send&action=enable"
```
### Cluster Health Monitoring
```bash
# Monitor all nodes in cluster
for ip in 10.0.1.60 10.0.1.61 10.0.1.62; do
echo "=== Node $ip ==="
curl -s "http://$ip/api/tasks/status" | jq '.summary'
done
```