terra-view/docs/MODEM_INTEGRATION.md

Modem Integration System

Overview

The modem integration system allows Sound Level Meters (SLMs) and Seismographs to be deployed with network connectivity modems. Instead of storing IP addresses directly on each device, units are assigned to modems which provide the network connection. This enables:

• Centralized modem management and tracking
• IP address updates in one place
• Future modem API integration for diagnostics
• Proper asset tracking for network equipment

Architecture

Database Design

Modem Units: Stored as RosterUnit with device_type = "modem"

Modem-Specific Fields:

• ip_address: Network IP address or hostname
• phone_number: Cellular phone number (if applicable)
• hardware_model: Modem hardware (e.g., "Raven XTV", "Sierra Wireless AirLink")

Device Assignment:

• Both SLMs and Seismographs use deployed_with_modem_id to reference their modem
• This is a foreign key to another RosterUnit.id where device_type = "modem"

How It Works

1. Create Modem Units

   • Add modems as regular roster units with device_type = "modem"
   • Set IP address, phone number, and hardware model
   • Deploy or bench modems like any other asset

2. Assign Devices to Modems

   • When editing an SLM or Seismograph, select modem from dropdown
   • The deployed_with_modem_id field stores the modem ID
   • IP address is fetched from the assigned modem at runtime

3. Runtime Resolution

   • When SLM dashboard needs to connect to a device:
     1. Load SLM unit data
     2. Check deployed_with_modem_id
     3. Fetch modem unit
     4. Use modem's ip_address for connection
     5. Fallback to legacy slm_host if no modem assigned

Implementation Details

Frontend Changes

Unit Detail Page (templates/unit_detail.html)

SLM Fields (lines 320-375):

• Removed direct "Host (IP Address)" field
• Added "Deployed With Modem" dropdown selector
• Dropdown populated with all active modems via JavaScript
• Shows modem ID, IP address, and hardware model in dropdown

JavaScript (lines 456-485):

async function loadModemsList() {
    // Fetches all modems from /api/roster/modems
    // Populates both seismograph and SLM modem dropdowns
    // Shows format: "modem-001 (192.168.1.100) - Raven XTV"
}

SLM Dashboard (backend/routers/slm_dashboard.py)

Live View Endpoint (lines 84-148):

# Get modem information if assigned
modem = None
modem_ip = None
if unit.deployed_with_modem_id:
    modem = db.query(RosterUnit).filter_by(
        id=unit.deployed_with_modem_id,
        device_type="modem"
    ).first()
    if modem:
        modem_ip = modem.ip_address

# Fallback to direct slm_host (backward compatibility)
if not modem_ip and unit.slm_host:
    modem_ip = unit.slm_host

Live View Template (templates/partials/slm_live_view.html):

• Displays modem information in header
• Shows "via Modem: modem-001 (192.168.1.100)"
• Warning if no modem assigned

Backend Changes

New API Endpoint (backend/routers/roster_edit.py)

GET /api/roster/modems

Returns list of all non-retired modem units:

[
    {
        "id": "modem-001",
        "ip_address": "192.168.1.100",
        "phone_number": "+1-555-0100",
        "hardware_model": "Raven XTV",
        "deployed": true
    }
]

Used by frontend to populate modem selection dropdowns.

Database Schema (backend/models.py)

Modem Assignment Field (line 44):

# Shared by seismographs and SLMs
deployed_with_modem_id = Column(String, nullable=True)

Modem Fields (lines 46-48):

ip_address = Column(String, nullable=True)
phone_number = Column(String, nullable=True)
hardware_model = Column(String, nullable=True)

Legacy SLM Fields (kept for backward compatibility):

slm_host = Column(String, nullable=True)  # Deprecated - use modem instead
slm_tcp_port = Column(Integer, nullable=True)  # Still used

Usage

Creating Modem Units

1. Go to Fleet Roster
2. Click "Add Unit"
3. Set Device Type to "Modem"
4. Fill in:
   • Unit ID (e.g., "modem-001")
   • IP Address (e.g., "192.168.1.100")
   • Phone Number (if cellular)
   • Hardware Model (e.g., "Raven XTV")
   • Address/Coordinates (physical location)
5. Set Deployed status
6. Save

Assigning Modem to SLM

1. Open SLM unit detail page
2. Click "Edit Unit"
3. Ensure Device Type is "Sound Level Meter"
4. In "Deployed With Modem" dropdown, select modem
5. Verify TCP Port (default 2255)
6. Save

Assigning Modem to Seismograph

Same process - both device types use the same modem selection field.

Test Data

Use the included script to create test modems:

python3 add_test_modems.py

This creates:

• modem-001: 192.168.1.100, Raven XTV → assigned to nl43-001
• modem-002: 192.168.1.101, Raven XTV → assigned to nl43-002
• modem-003: 192.168.1.102, Sierra Wireless → assigned to nl53-001
• modem-004: Spare modem (not deployed)

Benefits

For Operations

1. Centralized IP Management

   • Update modem IP once, affects all assigned devices
   • Easy to track which modem serves which devices
   • Inventory management for network equipment

2. Asset Tracking

   • Modems are first-class assets in the roster
   • Track deployment status, location, notes
   • Can bench/retire modems independently

3. Future Capabilities

   • Modem API integration (signal strength, data usage)
   • Automatic IP updates from DHCP/cellular network
   • Modem health monitoring
   • Remote modem diagnostics

For Maintenance

1. Easier Troubleshooting

   • See which modem serves a device
   • Check modem status separately
   • Swap modems without reconfiguring devices

2. Configuration Changes

   • Change IP addresses system-wide
   • Move devices between modems
   • Test with backup modems

Migration from Legacy System

For Existing SLMs with Direct IP

Legacy SLMs with slm_host set still work:

• System checks deployed_with_modem_id first
• Falls back to slm_host if no modem assigned
• Logs fallback usage for visibility

Migration Steps

1. Create modem units for each IP address
2. Assign SLMs to their modems
3. System will use modem IP automatically
4. Legacy slm_host can be cleared (optional)

Script add_test_modems.py demonstrates this:

# Clear legacy field after modem assignment
slm.slm_host = None
slm.deployed_with_modem_id = "modem-001"

Future Enhancements

Near-term

1. Modem Status Dashboard

   • List all modems with connection status
   • Show which devices use each modem
   • Signal strength, data usage indicators

2. Automatic IP Discovery

   • Query cellular provider API for modem IPs
   • Auto-update IP addresses in database
   • Alert on IP changes

3. Modem Health Monitoring

   • Ping modems periodically
   • Check cellular signal quality
   • Data usage tracking

Long-term

1. Modem API Integration

   • Direct modem management (Raven, Sierra APIs)
   • Remote reboot capability
   • Configuration backup/restore
   • Firmware updates

2. Network Topology View

   • Graphical view of modem-device relationships
   • Network health visualization
   • Troubleshooting tools

3. Multi-Modem Support

   • Failover between modems
   • Load balancing
   • Automatic fallback on modem failure

API Reference

Get Modems List

Endpoint: GET /api/roster/modems

Response:

[
    {
        "id": "modem-001",
        "ip_address": "192.168.1.100",
        "phone_number": "+1-555-0100",
        "hardware_model": "Raven XTV",
        "deployed": true
    }
]

Used By:

• Unit detail page (modem dropdown)
• Future modem management dashboard

Get Unit with Modem Info

Endpoint: GET /api/roster/{unit_id}

Response (for SLM):

{
    "id": "nl43-001",
    "device_type": "slm",
    "deployed_with_modem_id": "modem-001",
    "slm_tcp_port": 2255,
    "slm_model": "NL-43",
    ...
}

Then fetch modem separately or use dashboard endpoint which resolves it automatically.

SLM Live View (with modem resolution)

Endpoint: GET /api/slm-dashboard/live-view/{unit_id}

Process:

1. Loads SLM unit
2. Resolves deployed_with_modem_id to modem unit
3. Extracts modem.ip_address
4. Uses IP to connect to SLMM backend
5. Returns live view HTML with modem info

Files Modified/Created

Modified

1. backend/models.py - Clarified modem assignment field
2. templates/unit_detail.html - Added modem selector for SLMs
3. backend/routers/roster_edit.py - Added modems list endpoint
4. backend/routers/slm_dashboard.py - Modem resolution logic
5. templates/partials/slm_live_view.html - Display modem info

Created

1. add_test_modems.py - Script to create test modems and assignments
2. docs/MODEM_INTEGRATION.md - This documentation

Troubleshooting

SLM shows "No modem assigned"

Cause: Unit has no deployed_with_modem_id set

Solution:

1. Edit the SLM unit
2. Select a modem from dropdown
3. Save

Modem dropdown is empty

Cause: No modem units in database

Solution:

1. Create modem units first
2. Set device_type = "modem"
3. Ensure they're not retired

Can't connect to SLM

Possible Causes:

1. Modem IP is incorrect
2. Modem is offline
3. SLM TCP port is wrong
4. Network routing issue

Debug Steps:

1. Check modem unit's IP address
2. Ping the modem IP
3. Check SLM's slm_tcp_port (default 2255)
4. Review logs for connection errors

---

Version: 1.0.0 Date: January 5, 2026 Related: SOUND_LEVEL_METERS_DASHBOARD.md, DEVICE_TYPE_SLM_SUPPORT.md