Node Frame Configuration and Payload Typing

1. Frame Configuration and Sync Word Management

1.1 Multi-Payload Sync Word Strategy

On a single RF channel, support multiple downlink protocols via different sync words.

Configure via API:

curl -X POST http://node-001:8080/frame/config \
  -d '{
    "profiles": [
      {
        "payload_id": "flight_computer",
        "sync_word": "0x1ACFFC1D",
        "sync_word_length_bits": 32,
        "confidence_threshold": 0.95,
        "frame_structure": {
          "header_bytes": 8,
          "max_payload_bytes": 256,
          "crc_type": "CRC16_CCITT",
          "fec_type": "VITERBI_1_2"
        }
      },
      {
        "payload_id": "experiment_data",
        "sync_word": "0xF8726B19",
        "sync_word_length_bits": 32,
        "confidence_threshold": 0.95,
        "frame_structure": {
          "header_bytes": 4,
          "max_payload_bytes": 512,
          "crc_type": "CRC32",
          "fec_type": "none"
        }
      }
    ],
    "output_mode": "decoded",
    "routing_mode": "by_payload_id"
  }'

1.2 Frame Processing Flow

Raw demodulated bitstream
    |
    v
Sync Word Detector (monitor multiple words in parallel)
    |
    ├─ Found sync_word_1 → Extract frame type 1 → Verify CRC → Decode FEC → Emit frame
    |
    ├─ Found sync_word_2 → Extract frame type 2 → Verify CRC >> (no FEC) → Emit frame
    |
    └─ No match → Keep scanning, advance by 1 bit

1.3 Sync Word Collision Avoidance

Ensure sync words differ in ≥8 bits (Hamming distance ≥8)
Use high confidence threshold (0.95 or higher)
Log every false lock and report to central

2. TM Payload Typing and Pre-decode Configuration

Node accepts payload type definitions and applies them to incoming frames.

2.1 Payload Type Schema

Each payload type defines:

Parameter definitions: name, type (uint/int/float/bool/enum/bitfield), offset, length, endianness, scale, offset_value, unit, valid_range
Pre-decode mode: predecode_enabled: true/false (toggleable at runtime without DSP restart)
Output: Typed parameter values + raw frame bytes

Pre-decode is optional and applies to the node's configured payloads. When enabled, the node emits typed parameter values alongside raw frame bytes. Central source selection is a separate routing decision handled by the central server, and the node does not know which stream the server will prefer.

2.2 Field Type Support

Minimum field types:

uint: unsigned integer (8, 16, 32, 64-bit)
int: signed integer (8, 16, 32, 64-bit)
float: IEEE 754 float (32, 64-bit)
bool: single bit
enum: enumerated value with string labels
bitfield: sub-byte bit-packed fields
timestamp: absolute or relative time values

2.3 Multi-Target Payload Typing

Node preserves target_id through full pipeline
Each decoded event includes target_id, payload_type_id, and decoded_values
Central server applies per-target binding rules

2.4 Example Payload Type Definition

{
  "payload_type_id": "fc_primary",
  "sync_words": ["0x1ACFFC1D"],
  "predecode_enabled": true,
  "field_schema": [
    {
      "path": "latitude",
      "type": "float32",
      "offset_bytes": 0,
      "length_bits": 32,
      "endianness": "little",
      "scale": 1.0,
      "offset_value": 0.0,
      "unit": "deg",
      "valid_range": [-90, 90]
    },
    {
      "path": "longitude",
      "type": "float32",
      "offset_bytes": 4,
      "length_bits": 32,
      "endianness": "little",
      "scale": 1.0,
      "offset_value": 0.0,
      "unit": "deg",
      "valid_range": [-180, 180]
    },
    {
      "path": "altitude_m",
      "type": "uint32",
      "offset_bytes": 8,
      "length_bits": 32,
      "endianness": "little",
      "scale": 1.0,
      "offset_value": 0.0,
      "unit": "m"
    },
    {
      "path": "speed_mps",
      "type": "uint16",
      "offset_bytes": 12,
      "length_bits": 16,
      "endianness": "little",
      "scale": 0.1,
      "offset_value": 0.0,
      "unit": "m/s"
    }
  ]
}

2.5 Decoded Event Output

Node emits events with structure:

{
  "target_id": "rocket_001",
  "payload_type_id": "fc_primary",
  "payload_instance_id": null,
  "raw_payload": "...hex...",
  "decoded_values": {
    "latitude": {"value": 28.4, "unit": "deg", "quality": "ok"},
    "longitude": {"value": -80.6, "unit": "deg", "quality": "ok"},
    "altitude_m": {"value": 5000, "unit": "m", "quality": "ok"},
    "speed_mps": {"value": 1200.5, "unit": "m/s", "quality": "ok"}
  },
  "quality": {
    "crc_ok": true,
    "fec_confidence": 0.99,
    "lock_state": "frame_lock"
  },
  "timestamp_node_us": 1234567890123456,
  "timestamp_node_gps_week": 1234,
  "timestamp_node_gps_tow_seconds": 123456.789
}

Related: See System-APIs-Contracts for how central server applies binding rules to these decoded parameters.

Node Frame Configuration and Payload Typing

On this page