Node Configuration Protocols

1. Configuration Sources and Priority

Antenna node configuration comes from multiple sources in priority order:

1. HTTP POST (highest priority) , real-time commands from central server
2. Startup configuration file , /etc/node/config.yaml or environment variables
3. Defaults , compile-time or hardcoded sensible defaults
4. Cache , locally cached mission plan (fallback during central outage)

2. Startup Configuration File

Location: /etc/node/config.yaml

Key sections:

• node_id: unique identifier
• location: latitude, longitude, altitude
• hardware: antenna type, RF device, sample rate, frequency, gain
• api: host, port, TLS, API key
• ipc: control and telemetry bus addresses
• streams: telemetry, IQ, metrics output configuration
• gnss: receiver device, baud rate, update rate
• logging: level, file, max size

Example:

node_id: node-001
hardware:
  antenna_type: phased_array
  sample_rate_sps: 40000000
  frequency_hz: 5400000000
api:
  port: 8080
  tls_enabled: false
antenna:
  slew_rate_deg_per_sec: 5.0

3. Runtime Configuration via HTTP

Once running, all configuration is via REST POST. Central server sends commands like:

curl -X POST http://node-001:8080/radio/config \
  -H "Content-Type: application/json" \
  -d '{
    "frequency_hz": 5400000000,
    "gain_db": 32
  }'

Validation steps:

1. Schema validation: does the request match expected field types?
2. Hardware capability check: is this frequency/sample rate supported?
3. Resource availability: are there enough CPU/FPGA resources?
4. Current state compatibility: is a reconfiguration safe right now?

Response on success: HTTP 200 with status: "accepted" and command_id.
Response on failure: HTTP 400 or 409 with error detail and legal value ranges.

4. Command Acknowledgment and Ordering

1. Client sends POST /radio/config with command_id: "cmd-001"
2. FastAPI publishes {command_id: "cmd-001", ...} to control IPC bus
3. Each affected subsystem reads, validates, and applies
4. Worker publishes {command_id: "cmd-001", status: "done"} to status bus
5. FastAPI aggregates and emits in GET /status

Central server can check: GET /status → look for last_command_id: "cmd-001" and last_command_status: "done".

5. Frequency Hold and Doppler Compensation

Dedicated RF feature separate from tracking modes. Can be toggled independently at runtime.

Start request:

POST /frequency-hold/start
{
  "enabled": true,
  "center_frequency_hz": 5400000000,
  "search_window_hz": 50000,
  "max_track_rate_hz_per_s": 8000,
  "loop_bandwidth_hz": 40,
  "doppler_feedforward": {
    "enabled": true,
    "source": "trajectory",
    "radial_velocity_mps": 1200
  }
}

Status response:

{
  "state": "locked",
  "carrier_offset_hz": -18250,
  "afc_correction_hz": -18100,
  "estimated_track_rate_hz_per_s": 4200
}

Recommended operational thresholds:

• search_window_hz: 10-200 kHz
• loop_bandwidth_hz: 10-80 Hz
• max_track_rate_hz_per_s: from worst-case radial acceleration model

Related: See System-APIs-Contracts for complete endpoint specifications.