Add roster management interface and related API endpoints
- Implemented a new `/roster` endpoint to retrieve and manage device configurations. - Added HTML template for the roster page with a table to display device status and actions. - Introduced functionality to add, edit, and delete devices via the roster interface. - Enhanced `ConfigPayload` model to include polling options. - Updated the main application to serve the new roster page and link to it from the index. - Added validation for polling interval in the configuration payload. - Created detailed documentation for the roster management features and API endpoints.
This commit is contained in:
serversdwn
246
docs/ROSTER.md
Normal file
246
docs/ROSTER.md
Normal file
@@ -0,0 +1,246 @@
|
||||
# SLMM Roster Management
|
||||
|
||||
The SLMM standalone application now includes a roster management interface for viewing and configuring all Sound Level Meter devices.
|
||||
|
||||
## Features
|
||||
|
||||
### Web Interface
|
||||
|
||||
Access the roster at: **http://localhost:8100/roster**
|
||||
|
||||
The roster page provides:
|
||||
|
||||
- **Device List Table**: View all configured SLMs with their connection details
|
||||
- **Real-time Status**: See device connectivity status (Online/Offline/Stale)
|
||||
- **Add Device**: Create new device configurations with a user-friendly modal form
|
||||
- **Edit Device**: Modify existing device configurations
|
||||
- **Delete Device**: Remove device configurations (does not affect physical devices)
|
||||
- **Test Connection**: Run diagnostics on individual devices
|
||||
|
||||
### Table Columns
|
||||
|
||||
| Column | Description |
|
||||
|--------|-------------|
|
||||
| Unit ID | Unique identifier for the device |
|
||||
| Host / IP | Device IP address or hostname |
|
||||
| TCP Port | TCP control port (default: 2255) |
|
||||
| FTP Port | FTP file transfer port (default: 21) |
|
||||
| TCP | Whether TCP control is enabled |
|
||||
| FTP | Whether FTP file transfer is enabled |
|
||||
| Polling | Whether background polling is enabled |
|
||||
| Status | Device connectivity status (Online/Offline/Stale) |
|
||||
| Actions | Test, Edit, Delete buttons |
|
||||
|
||||
### Status Indicators
|
||||
|
||||
- **Online** (green): Device responded within the last 5 minutes
|
||||
- **Stale** (yellow): Device hasn't responded recently but was seen before
|
||||
- **Offline** (red): Device is unreachable or has consecutive failures
|
||||
- **Unknown** (gray): No status data available yet
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### List All Devices
|
||||
|
||||
```bash
|
||||
GET /api/nl43/roster
|
||||
```
|
||||
|
||||
Returns all configured devices with their status information.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"devices": [
|
||||
{
|
||||
"unit_id": "SLM-43-01",
|
||||
"host": "192.168.1.100",
|
||||
"tcp_port": 2255,
|
||||
"ftp_port": 21,
|
||||
"tcp_enabled": true,
|
||||
"ftp_enabled": true,
|
||||
"ftp_username": "USER",
|
||||
"ftp_password": "0000",
|
||||
"web_enabled": false,
|
||||
"poll_enabled": true,
|
||||
"poll_interval_seconds": 60,
|
||||
"status": {
|
||||
"last_seen": "2026-01-16T20:00:00",
|
||||
"measurement_state": "Start",
|
||||
"is_reachable": true,
|
||||
"consecutive_failures": 0,
|
||||
"last_success": "2026-01-16T20:00:00",
|
||||
"last_error": null
|
||||
}
|
||||
}
|
||||
],
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
### Create New Device
|
||||
|
||||
```bash
|
||||
POST /api/nl43/roster
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"unit_id": "SLM-43-01",
|
||||
"host": "192.168.1.100",
|
||||
"tcp_port": 2255,
|
||||
"ftp_port": 21,
|
||||
"tcp_enabled": true,
|
||||
"ftp_enabled": false,
|
||||
"poll_enabled": true,
|
||||
"poll_interval_seconds": 60
|
||||
}
|
||||
```
|
||||
|
||||
**Required Fields:**
|
||||
- `unit_id`: Unique device identifier
|
||||
- `host`: IP address or hostname
|
||||
|
||||
**Optional Fields:**
|
||||
- `tcp_port`: TCP control port (default: 2255)
|
||||
- `ftp_port`: FTP port (default: 21)
|
||||
- `tcp_enabled`: Enable TCP control (default: true)
|
||||
- `ftp_enabled`: Enable FTP transfers (default: false)
|
||||
- `ftp_username`: FTP username (only if ftp_enabled)
|
||||
- `ftp_password`: FTP password (only if ftp_enabled)
|
||||
- `poll_enabled`: Enable background polling (default: true)
|
||||
- `poll_interval_seconds`: Polling interval 10-3600 seconds (default: 60)
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"message": "Device SLM-43-01 created successfully",
|
||||
"data": {
|
||||
"unit_id": "SLM-43-01",
|
||||
"host": "192.168.1.100",
|
||||
"tcp_port": 2255,
|
||||
"tcp_enabled": true,
|
||||
"ftp_enabled": false,
|
||||
"poll_enabled": true,
|
||||
"poll_interval_seconds": 60
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Update Device
|
||||
|
||||
```bash
|
||||
PUT /api/nl43/{unit_id}/config
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"host": "192.168.1.101",
|
||||
"tcp_port": 2255,
|
||||
"poll_interval_seconds": 120
|
||||
}
|
||||
```
|
||||
|
||||
All fields are optional. Only include fields you want to update.
|
||||
|
||||
### Delete Device
|
||||
|
||||
```bash
|
||||
DELETE /api/nl43/{unit_id}/config
|
||||
```
|
||||
|
||||
Removes the device configuration and associated status data. Does not affect the physical device.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"message": "Deleted device SLM-43-01"
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Via Web Interface
|
||||
|
||||
1. Navigate to http://localhost:8100/roster
|
||||
2. Click "Add Device" to create a new configuration
|
||||
3. Fill in the device details (unit ID, IP address, ports)
|
||||
4. Configure TCP, FTP, and polling settings
|
||||
5. Click "Save Device"
|
||||
6. Use "Test" button to verify connectivity
|
||||
7. Edit or delete devices as needed
|
||||
|
||||
### Via API (curl)
|
||||
|
||||
**Add a new device:**
|
||||
```bash
|
||||
curl -X POST http://localhost:8100/api/nl43/roster \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"unit_id": "slm-site-a",
|
||||
"host": "192.168.1.100",
|
||||
"tcp_port": 2255,
|
||||
"tcp_enabled": true,
|
||||
"ftp_enabled": true,
|
||||
"ftp_username": "USER",
|
||||
"ftp_password": "0000",
|
||||
"poll_enabled": true,
|
||||
"poll_interval_seconds": 60
|
||||
}'
|
||||
```
|
||||
|
||||
**Update device host:**
|
||||
```bash
|
||||
curl -X PUT http://localhost:8100/api/nl43/slm-site-a/config \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"host": "192.168.1.101"}'
|
||||
```
|
||||
|
||||
**Delete device:**
|
||||
```bash
|
||||
curl -X DELETE http://localhost:8100/api/nl43/slm-site-a/config
|
||||
```
|
||||
|
||||
**List all devices:**
|
||||
```bash
|
||||
curl http://localhost:8100/api/nl43/roster | python3 -m json.tool
|
||||
```
|
||||
|
||||
## Integration with Terra-View
|
||||
|
||||
When SLMM is used as a module within Terra-View:
|
||||
|
||||
1. Terra-View manages device configurations in its own database
|
||||
2. Terra-View syncs configurations to SLMM via `PUT /api/nl43/{unit_id}/config`
|
||||
3. Terra-View can query device status via `GET /api/nl43/{unit_id}/status`
|
||||
4. SLMM's roster page can be used for standalone testing and diagnostics
|
||||
|
||||
## Background Polling
|
||||
|
||||
Devices with `poll_enabled: true` are automatically polled at their configured interval:
|
||||
|
||||
- Polls device status every `poll_interval_seconds` (10-3600 seconds)
|
||||
- Updates `NL43Status` table with latest measurements
|
||||
- Tracks device reachability and failure counts
|
||||
- Provides real-time status updates in the roster
|
||||
|
||||
**Note**: Polling respects the NL43 protocol's 1-second rate limit between commands.
|
||||
|
||||
## Validation
|
||||
|
||||
The roster system validates:
|
||||
|
||||
- **Unit ID**: Must be unique across all devices
|
||||
- **Host**: Valid IP address or hostname format
|
||||
- **Ports**: Must be between 1-65535
|
||||
- **Poll Interval**: Must be between 10-3600 seconds
|
||||
- **Duplicate Check**: Returns 409 Conflict if unit_id already exists
|
||||
|
||||
## Notes
|
||||
|
||||
- Deleting a device from the roster does NOT affect the physical device
|
||||
- Device configurations are stored in the SLMM database (`data/slmm.db`)
|
||||
- Status information is updated by the background polling system
|
||||
- The roster page auto-refreshes status indicators
|
||||
- Test button runs full diagnostics (connectivity, TCP, FTP if enabled)
|
||||
Reference in New Issue
Block a user