From c90544a7126e3e64e40e937d03a6f5dbee2cb1b3 Mon Sep 17 00:00:00 2001 From: serversdwn Date: Wed, 24 Dec 2025 07:21:04 +0000 Subject: [PATCH] readme expanded --- README.md | 371 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 358 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index de238b0..edc286e 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,362 @@ -# slmm -Standalone NL43 addon module (keep separate from the SFM/terra-view codebase). +# SLMM - Sound Level Meter Manager -Run the addon API: -```bash -pip install -r requirements.txt -uvicorn app.main:app --reload --port 8100 +Backend API service for controlling and monitoring Rion NL-43/NL-53 Sound Level Meters via TCP and FTP protocols. + +## Overview + +SLMM is a standalone backend module that provides REST API routing and command translation for NL43/NL53 sound level meters. This service acts as a bridge between the hardware devices and frontend applications, handling all device communication, data persistence, and protocol management. + +**Note:** This is a backend-only service. Actual user interfacing is done via [SFM/Terra-View](https://github.com/your-org/terra-view) frontend applications. + +## Features + +- **Device Management**: Configure and manage multiple NL43/NL53 devices +- **Real-time Monitoring**: Stream live measurement data via WebSocket +- **Measurement Control**: Start, stop, pause, resume, and reset measurements +- **Data Retrieval**: Access current and historical measurement snapshots +- **FTP Integration**: Download measurement files directly from devices +- **Device Configuration**: Manage frequency/time weighting, clock sync, and more +- **Rate Limiting**: Automatic 1-second delay enforcement between device commands +- **Persistent Storage**: SQLite database for device configs and measurement cache + +## Architecture + +``` +┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐ +│ Terra-View UI │◄───────►│ SLMM API │◄───────►│ NL43/NL53 │ +│ (Frontend) │ HTTP │ (Backend) │ TCP │ Sound Meters │ +└─────────────────┘ └──────────────┘ └─────────────────┘ + │ + ▼ + ┌──────────────┐ + │ SQLite DB │ + │ (Cache) │ + └──────────────┘ ``` -Endpoints: -- `GET /health` -- `GET /api/nl43/{unit_id}/config` -- `PUT /api/nl43/{unit_id}/config` -- `GET /api/nl43/{unit_id}/status` -- `POST /api/nl43/{unit_id}/status` +## Quick Start -Use `app/services.py` to wire in the TCP connector and call `persist_snapshot` with parsed DOD/DRD data. +### Prerequisites + +- Python 3.10+ +- pip package manager + +### Installation + +1. Clone the repository: +```bash +git clone +cd slmm +``` + +2. Install dependencies: +```bash +pip install -r requirements.txt +``` + +### Running the Server + +```bash +# Development mode with auto-reload +uvicorn app.main:app --reload --port 8100 + +# Production mode +uvicorn app.main:app --host 0.0.0.0 --port 8100 +``` + +The API will be available at `http://localhost:8100` + +### API Documentation + +Once running, visit: +- Swagger UI: `http://localhost:8100/docs` +- ReDoc: `http://localhost:8100/redoc` +- Health Check: `http://localhost:8100/health` + +## Configuration + +### Environment Variables + +- `PORT`: Server port (default: 8100) +- `CORS_ORIGINS`: Comma-separated list of allowed origins (default: "*") + +### Database + +The SQLite database is automatically created at [data/slmm.db](data/slmm.db) on first run. + +### Logging + +Logs are written to: +- Console output (stdout) +- [data/slmm.log](data/slmm.log) file + +## API Endpoints + +### Device Configuration + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/nl43/{unit_id}/config` | Get device configuration | +| PUT | `/api/nl43/{unit_id}/config` | Update device configuration | + +### Device Status + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/nl43/{unit_id}/status` | Get cached measurement snapshot | +| GET | `/api/nl43/{unit_id}/live` | Request fresh DOD data from device | +| WS | `/api/nl43/{unit_id}/stream` | WebSocket stream for real-time DRD data | + +### Measurement Control + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/nl43/{unit_id}/start` | Start measurement | +| POST | `/api/nl43/{unit_id}/stop` | Stop measurement | +| POST | `/api/nl43/{unit_id}/pause` | Pause measurement | +| POST | `/api/nl43/{unit_id}/resume` | Resume paused measurement | +| POST | `/api/nl43/{unit_id}/reset` | Reset measurement data | +| POST | `/api/nl43/{unit_id}/store` | Manually store data to SD card | + +### Device Information + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/nl43/{unit_id}/battery` | Get battery level | +| GET | `/api/nl43/{unit_id}/clock` | Get device clock time | +| PUT | `/api/nl43/{unit_id}/clock` | Set device clock time | +| GET | `/api/nl43/{unit_id}/results` | Get final calculation results (DLC) | + +### Measurement Settings + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/nl43/{unit_id}/frequency-weighting` | Get frequency weighting (A/C/Z) | +| PUT | `/api/nl43/{unit_id}/frequency-weighting` | Set frequency weighting | +| GET | `/api/nl43/{unit_id}/time-weighting` | Get time weighting (F/S/I) | +| PUT | `/api/nl43/{unit_id}/time-weighting` | Set time weighting | + +### Sleep Mode + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/nl43/{unit_id}/sleep` | Put device into sleep mode | +| POST | `/api/nl43/{unit_id}/wake` | Wake device from sleep | +| GET | `/api/nl43/{unit_id}/sleep/status` | Get sleep mode status | + +### FTP File Management + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/nl43/{unit_id}/ftp/enable` | Enable FTP server on device | +| POST | `/api/nl43/{unit_id}/ftp/disable` | Disable FTP server on device | +| GET | `/api/nl43/{unit_id}/ftp/status` | Get FTP server status | +| GET | `/api/nl43/{unit_id}/ftp/files` | List files on device | +| POST | `/api/nl43/{unit_id}/ftp/download` | Download file from device | + +For detailed API documentation and examples, see [API.md](API.md). + +## Project Structure + +``` +slmm/ +├── app/ +│ ├── __init__.py # Package initialization +│ ├── main.py # FastAPI application and startup +│ ├── routers.py # API route definitions +│ ├── models.py # SQLAlchemy database models +│ ├── services.py # NL43Client and business logic +│ └── database.py # Database configuration +├── data/ +│ ├── slmm.db # SQLite database (auto-created) +│ ├── slmm.log # Application logs +│ └── downloads/ # Downloaded files from devices +├── templates/ +│ └── index.html # Simple web interface (optional) +├── manuals/ # Device documentation +├── API.md # Detailed API documentation +├── COMMUNICATION_GUIDE.md # NL43 protocol documentation +├── NL43_COMMANDS.md # Command reference +├── requirements.txt # Python dependencies +└── README.md # This file +``` + +## Database Schema + +### NL43Config Table +Stores device connection configuration: +- `unit_id` (PK): Unique device identifier +- `host`: Device IP address or hostname +- `tcp_port`: TCP control port (default: 80) +- `tcp_enabled`: Enable/disable TCP communication +- `ftp_enabled`: Enable/disable FTP functionality +- `ftp_username`: FTP authentication username +- `ftp_password`: FTP authentication password +- `web_enabled`: Enable/disable web interface access + +### NL43Status Table +Caches latest measurement snapshot: +- `unit_id` (PK): Unique device identifier +- `last_seen`: Timestamp of last update +- `measurement_state`: Current state (Measure/Stop) +- `lp`: Instantaneous sound pressure level +- `leq`: Equivalent continuous sound level +- `lmax`: Maximum sound level +- `lmin`: Minimum sound level +- `lpeak`: Peak sound level +- `battery_level`: Battery percentage +- `power_source`: Current power source +- `sd_remaining_mb`: Free SD card space (MB) +- `sd_free_ratio`: SD card free space ratio +- `raw_payload`: Raw device response data + +## Protocol Details + +### TCP Communication +- Uses ASCII command protocol over TCP +- Enforces ≥1 second delay between commands to same device +- Two-line response format: + - Line 1: Result code (R+0000 for success) + - Line 2: Data payload (for query commands) + +### FTP Communication +- Uses active mode FTP (requires device to connect back) +- TCP and FTP are mutually exclusive on the device +- Credentials configurable per device + +### Data Formats + +**DOD (Data Output Display)**: Snapshot of current display values +**DRD (Data Real-time Display)**: Continuous streaming data +**DLC (Data Last Calculation)**: Final stored measurement results + +## Example Usage + +### Configure a Device +```bash +curl -X PUT http://localhost:8100/api/nl43/meter-001/config \ + -H "Content-Type: application/json" \ + -d '{ + "host": "192.168.1.100", + "tcp_port": 2255, + "tcp_enabled": true, + "ftp_username": "admin", + "ftp_password": "password" + }' +``` + +### Start Measurement +```bash +curl -X POST http://localhost:8100/api/nl43/meter-001/start +``` + +### Get Live Status +```bash +curl http://localhost:8100/api/nl43/meter-001/live +``` + +### Stream Real-time Data (JavaScript) +```javascript +const ws = new WebSocket('ws://localhost:8100/api/nl43/meter-001/stream'); + +ws.onmessage = (event) => { + const data = JSON.parse(event.data); + console.log('Live measurement:', data); +}; +``` + +### Download Files via FTP +```bash +# Enable FTP +curl -X POST http://localhost:8100/api/nl43/meter-001/ftp/enable + +# List files +curl http://localhost:8100/api/nl43/meter-001/ftp/files?path=/NL43_DATA + +# Download file +curl -X POST http://localhost:8100/api/nl43/meter-001/ftp/download \ + -H "Content-Type: application/json" \ + -d '{"remote_path": "/NL43_DATA/measurement.wav"}' \ + --output measurement.wav + +# Disable FTP +curl -X POST http://localhost:8100/api/nl43/meter-001/ftp/disable +``` + +## Integration with Terra-View + +This backend is designed to be consumed by the Terra-View frontend application. The frontend should: + +1. Use the config endpoints to register and configure devices +2. Poll or stream live status for real-time monitoring +3. Use control endpoints to manage measurements +4. Download files via FTP endpoints for analysis + +See [API.md](API.md) for detailed integration examples. + +## Troubleshooting + +### Connection Issues +- Verify device IP address and port in configuration +- Ensure device is on the same network +- Check firewall rules allow TCP/FTP connections +- Verify RX55 network adapter is properly configured on device + +### Rate Limiting +- API automatically enforces 1-second delay between commands +- If experiencing delays, this is normal device behavior +- Multiple devices can be controlled in parallel + +### FTP Active Mode +- Ensure server can accept incoming connections from device +- FTP uses active mode (device connects back to server) +- May require firewall configuration for data channel + +### WebSocket Disconnects +- WebSocket streams maintain persistent connection +- Limit concurrent streams to avoid device overload +- Connection will auto-close if device stops responding + +## Development + +### Running Tests +```bash +# Add test commands when implemented +pytest +``` + +### Database Migrations +```bash +# Migrate existing database to add FTP credentials +python migrate_add_ftp_credentials.py + +# Set FTP credentials for a device +python set_ftp_credentials.py +``` + +## Contributing + +This is a standalone module kept separate from the SFM/Terra-View codebase. When contributing: + +1. Maintain separation from frontend code +2. Follow existing API patterns and error handling +3. Update API documentation for new endpoints +4. Ensure rate limiting is enforced for device commands + +## License + +[Specify license here] + +## Related Documentation + +- [API.md](API.md) - Complete API reference with examples +- [COMMUNICATION_GUIDE.md](COMMUNICATION_GUIDE.md) - NL43 protocol details +- [NL43_COMMANDS.md](NL43_COMMANDS.md) - Device command reference +- [manuals/](manuals/) - Device manufacturer documentation + +## Support + +For issues and questions: +- Backend API issues: This repository +- Frontend/UI issues: Terra-View repository +- Device protocol questions: See COMMUNICATION_GUIDE.md