feat: Add comprehensive NL-43/NL-53 Communication Guide and command references
- Introduced a new communication guide detailing protocol basics, transport modes, and a quick startup checklist. - Added a detailed list of commands with their functions and usage for NL-43/NL-53 devices. - Created a verified quick reference for command formats to prevent common mistakes. - Implemented an improvements document outlining critical fixes, security enhancements, reliability upgrades, and code quality improvements for the SLMM project. - Enhanced the frontend with a new button to retrieve all device settings, along with corresponding JavaScript functionality. - Added a test script for the new settings retrieval API endpoint to demonstrate its usage and validate functionality.
This commit is contained in:
serversdwn
258
SETTINGS_ENDPOINT.md
Normal file
258
SETTINGS_ENDPOINT.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# Device Settings Verification Endpoint
|
||||
|
||||
## Overview
|
||||
|
||||
The new `GET /api/nl43/{unit_id}/settings` endpoint provides a comprehensive view of all current device settings. This allows you to quickly verify the configuration of your NL43/NL53 sound level meter before starting measurements, ensuring the device is configured correctly for your testing requirements.
|
||||
|
||||
## Endpoint Details
|
||||
|
||||
**URL:** `GET /api/nl43/{unit_id}/settings`
|
||||
|
||||
**Description:** Retrieves all queryable settings from the device in a single request.
|
||||
|
||||
**Response Time:** Approximately 10-15 seconds (due to required 1-second delay between device commands)
|
||||
|
||||
## Settings Retrieved
|
||||
|
||||
The endpoint queries the following categories of settings:
|
||||
|
||||
### Measurement Configuration
|
||||
- **measurement_state**: Current state (Measure, Stop, Pause)
|
||||
- **frequency_weighting**: Frequency weighting (A, C, or Z)
|
||||
- **time_weighting**: Time weighting (F=Fast, S=Slow, I=Impulse)
|
||||
|
||||
### Timing and Intervals
|
||||
- **measurement_time**: Total measurement duration setting
|
||||
- **leq_interval**: Leq calculation interval
|
||||
- **lp_interval**: Lp sampling interval
|
||||
- **index_number**: Current index/file number for storage
|
||||
|
||||
### Device Information
|
||||
- **battery_level**: Current battery percentage
|
||||
- **clock**: Device clock time (format: YYYY/MM/DD,HH:MM:SS)
|
||||
|
||||
### Operational Status
|
||||
- **sleep_mode**: Sleep mode status (On/Off)
|
||||
- **ftp_status**: FTP server status (On/Off)
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Request
|
||||
|
||||
```bash
|
||||
curl http://localhost:8100/api/nl43/NL43-001/settings
|
||||
```
|
||||
|
||||
### Response Format
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"unit_id": "NL43-001",
|
||||
"settings": {
|
||||
"measurement_state": "Stop",
|
||||
"frequency_weighting": "A",
|
||||
"time_weighting": "F",
|
||||
"measurement_time": "00:01:00",
|
||||
"leq_interval": "1s",
|
||||
"lp_interval": "125ms",
|
||||
"index_number": "0",
|
||||
"battery_level": "100%",
|
||||
"clock": "2025/12/24,20:45:30",
|
||||
"sleep_mode": "Off",
|
||||
"ftp_status": "On"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
Individual settings that fail to query will show an error message instead of a value:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"unit_id": "NL43-001",
|
||||
"settings": {
|
||||
"measurement_state": "Stop",
|
||||
"frequency_weighting": "A",
|
||||
"time_weighting": "Error: Status error - device is in wrong state for this command",
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This partial error handling ensures you get as much information as possible even if some settings fail to query.
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### Pre-Measurement Verification
|
||||
|
||||
Before starting a measurement session, verify all critical settings:
|
||||
|
||||
```bash
|
||||
# Get all settings
|
||||
SETTINGS=$(curl -s http://localhost:8100/api/nl43/meter-001/settings)
|
||||
|
||||
# Extract specific values (using jq)
|
||||
FREQ_WEIGHT=$(echo $SETTINGS | jq -r '.settings.frequency_weighting')
|
||||
TIME_WEIGHT=$(echo $SETTINGS | jq -r '.settings.time_weighting')
|
||||
|
||||
echo "Frequency: $FREQ_WEIGHT, Time: $TIME_WEIGHT"
|
||||
```
|
||||
|
||||
### Configuration Audit
|
||||
|
||||
Document device configuration for quality assurance:
|
||||
|
||||
```bash
|
||||
# Save settings snapshot
|
||||
curl http://localhost:8100/api/nl43/meter-001/settings > config_snapshot_$(date +%Y%m%d_%H%M%S).json
|
||||
```
|
||||
|
||||
### Multi-Device Comparison
|
||||
|
||||
Compare settings across multiple devices:
|
||||
|
||||
```bash
|
||||
# Compare two devices
|
||||
curl http://localhost:8100/api/nl43/meter-001/settings > device1.json
|
||||
curl http://localhost:8100/api/nl43/meter-002/settings > device2.json
|
||||
diff device1.json device2.json
|
||||
```
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
import requests
|
||||
|
||||
def verify_device_settings(unit_id: str) -> dict:
|
||||
"""Retrieve and verify device settings."""
|
||||
response = requests.get(f"http://localhost:8100/api/nl43/{unit_id}/settings")
|
||||
response.raise_for_status()
|
||||
|
||||
data = response.json()
|
||||
settings = data["settings"]
|
||||
|
||||
# Verify critical settings
|
||||
assert settings["frequency_weighting"] == "A", "Wrong frequency weighting!"
|
||||
assert settings["time_weighting"] == "F", "Wrong time weighting!"
|
||||
|
||||
return settings
|
||||
|
||||
# Usage
|
||||
settings = verify_device_settings("NL43-001")
|
||||
print(f"Battery: {settings['battery_level']}")
|
||||
print(f"Clock: {settings['clock']}")
|
||||
```
|
||||
|
||||
### JavaScript/TypeScript
|
||||
|
||||
```typescript
|
||||
interface DeviceSettings {
|
||||
measurement_state: string;
|
||||
frequency_weighting: string;
|
||||
time_weighting: string;
|
||||
measurement_time: string;
|
||||
leq_interval: string;
|
||||
lp_interval: string;
|
||||
index_number: string;
|
||||
battery_level: string;
|
||||
clock: string;
|
||||
sleep_mode: string;
|
||||
ftp_status: string;
|
||||
}
|
||||
|
||||
async function getDeviceSettings(unitId: string): Promise<DeviceSettings> {
|
||||
const response = await fetch(`http://localhost:8100/api/nl43/${unitId}/settings`);
|
||||
const data = await response.json();
|
||||
|
||||
if (data.status !== "ok") {
|
||||
throw new Error("Failed to retrieve settings");
|
||||
}
|
||||
|
||||
return data.settings;
|
||||
}
|
||||
|
||||
// Usage
|
||||
const settings = await getDeviceSettings("NL43-001");
|
||||
console.log(`Frequency weighting: ${settings.frequency_weighting}`);
|
||||
console.log(`Battery level: ${settings.battery_level}`);
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Query Duration
|
||||
|
||||
The endpoint queries multiple settings sequentially with required 1-second delays between commands. Total query time depends on:
|
||||
- Number of settings queried (~10-12 settings)
|
||||
- Network latency
|
||||
- Device response time
|
||||
|
||||
**Expected duration:** 10-15 seconds
|
||||
|
||||
### Caching Strategy
|
||||
|
||||
For applications that need frequent access to settings:
|
||||
|
||||
1. **Cache results** - Settings don't change frequently unless you modify them
|
||||
2. **Refresh periodically** - Query every 5-10 minutes or on-demand
|
||||
3. **Track changes** - Re-query after sending configuration commands
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
The endpoint respects device rate limiting (1-second delay between commands). Concurrent requests to the same device will be serialized automatically.
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Pre-flight check**: Always verify settings before starting critical measurements
|
||||
2. **Document configuration**: Save settings snapshots for audit trails
|
||||
3. **Monitor battery**: Check battery level to avoid measurement interruption
|
||||
4. **Sync clocks**: Verify device clock is accurate for timestamped data
|
||||
5. **Error handling**: Check for "Error:" prefixes in individual setting values
|
||||
|
||||
## Related Endpoints
|
||||
|
||||
- `GET /api/nl43/{unit_id}/frequency-weighting` - Get single frequency weighting setting
|
||||
- `PUT /api/nl43/{unit_id}/frequency-weighting` - Set frequency weighting
|
||||
- `GET /api/nl43/{unit_id}/time-weighting` - Get single time weighting setting
|
||||
- `PUT /api/nl43/{unit_id}/time-weighting` - Set time weighting
|
||||
- `GET /api/nl43/{unit_id}/battery` - Get battery level only
|
||||
- `GET /api/nl43/{unit_id}/clock` - Get device clock only
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Slow Response
|
||||
|
||||
**Problem:** Endpoint takes longer than expected
|
||||
|
||||
**Solutions:**
|
||||
- Normal behavior due to rate limiting (1 second between commands)
|
||||
- Check network connectivity
|
||||
- Verify device is not in sleep mode
|
||||
|
||||
### Partial Errors
|
||||
|
||||
**Problem:** Some settings show "Error:" messages
|
||||
|
||||
**Solutions:**
|
||||
- Device may be in wrong state for certain queries
|
||||
- Check if measurement is running (some settings require stopped state)
|
||||
- Verify firmware version supports all queried commands
|
||||
|
||||
### Connection Timeout
|
||||
|
||||
**Problem:** 504 Gateway Timeout error
|
||||
|
||||
**Solutions:**
|
||||
- Verify device IP address and port in configuration
|
||||
- Check if device is powered on and connected
|
||||
- Ensure TCP communication is enabled in device config
|
||||
|
||||
## See Also
|
||||
|
||||
- [README.md](README.md) - Main documentation
|
||||
- [API.md](API.md) - Complete API reference
|
||||
- [COMMUNICATION_GUIDE.md](COMMUNICATION_GUIDE.md) - NL43 protocol details
|
||||
Reference in New Issue
Block a user