slmm/docs/features/SETTINGS_ENDPOINT.md

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

curl http://localhost:8100/api/nl43/NL43-001/settings

Response Format

{
  "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:

{
  "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:

# 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:

# 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:

# 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

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

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 - Main documentation
• API.md - Complete API reference
• COMMUNICATION_GUIDE.md - NL43 protocol details