id: rylr998_frame_sync
label: RYLR998 Frame Sync
category: '[RYLR998]/Synchronization'
flags: [python, cpp]

documentation: |-
  LoRa frame synchronization block.

  Detects preamble, extracts sync word (NETWORKID), locates SFD,
  and outputs aligned data symbols.

  Frame structure:
    [Preamble: N upchirps at bin 0]
    [Sync Word: 2 upchirps encoding NETWORKID nibbles]
    [SFD: 2.25 downchirps]
    [Data: encoded payload symbols]

  Input: CSS-demodulated bin values
  Output: Aligned data symbol bins + NETWORKID message

  The NETWORKID is extracted from the sync word and can be used to
  filter frames or identify the source device.

templates:
  imports: from rylr998 import frame_sync
  make: rylr998.frame_sync(sf=${sf}, sample_rate=${sample_rate}, expected_networkid=${expected_networkid})

parameters:
  - id: sf
    label: Spreading Factor
    dtype: int
    default: 9
    options: [7, 8, 9, 10, 11, 12]
    option_labels: ['SF7', 'SF8', 'SF9', 'SF10', 'SF11', 'SF12']

  - id: sample_rate
    label: Sample Rate (Hz)
    dtype: real
    default: 250e3

  - id: expected_networkid
    label: Expected NETWORKID
    dtype: int
    default: -1
    hide: ${ 'part' if expected_networkid < 0 else 'none' }

  - id: preamble_min
    label: Min Preamble Symbols
    dtype: int
    default: 4
    hide: part

inputs:
  - label: in
    domain: stream
    dtype: complex

outputs:
  - label: symbols
    domain: message
    dtype: int
    optional: false

  - label: networkid
    domain: message
    dtype: int
    optional: true

file_format: 1