gr-rylr998/docs/BLOCK_REFERENCE.md

gr-rylr998 Block Reference

Overview

gr-rylr998 provides GNU Radio blocks for complete LoRa TX/RX chains compatible with RYLR998 modems.

Block Categories

Modulation/Demodulation

CSS Demodulator (rylr998_css_demod)

FFT-based Chirp Spread Spectrum demodulator.

Parameters:

Name	Type	Default	Description
sf	int	9	Spreading factor (7-12)
sample_rate	float	250e3	Input sample rate (Hz)
bw	float	125e3	Signal bandwidth (Hz)

Input: Complex IQ stream Output: Integer bin values (0 to 2^SF - 1)

CSS Modulator (rylr998_css_mod)

Chirp generator from bin values.

Parameters:

Name	Type	Default	Description
sf	int	9	Spreading factor (7-12)
sample_rate	float	125e3	Output sample rate (Hz)
bw	float	125e3	Signal bandwidth (Hz)

Input: Integer bin values Output: Complex IQ stream

---

PHY Layer

PHY Decoder (rylr998_phy_decode)

Complete RX PHY chain: Gray → Deinterleave → Hamming FEC → Dewhiten → CRC.

Parameters:

Name	Type	Default	Description
sf	int	9	Spreading factor (7-12)
cr	int	1	Coding rate (1=4/5, 2=4/6, 3=4/7, 4=4/8)
has_crc	bool	True	CRC enabled
ldro	bool	False	Low Data Rate Optimization
implicit_header	bool	False	Implicit header mode
payload_len	int	0	Expected payload length (implicit mode)

Decode Method Parameters:

Name	Type	Default	Description
use_grlora_gray	bool	True	Use gr-lora_sdr Gray mapping (for real SDR captures)
soft_decoding	bool	False	Skip -1 bin offset (use True for loopback testing)

Input: Symbol bin values (from Frame Sync) Output: Decoded payload bytes, frame metadata

Usage Notes:

• For real SDR captures (gr-lora_sdr compatible): use_grlora_gray=True, soft_decoding=False (defaults)
• For loopback testing with gr-rylr998 TX: use_grlora_gray=False, soft_decoding=True

PHY Encoder (rylr998_phy_encode)

Complete TX PHY chain: CRC → Whiten → Hamming FEC → Interleave → Gray.

Parameters: Same as PHY Decoder (minus payload_len)

Input: Raw payload bytes Output: Encoded symbol bin values

---

Framing

Frame Sync (rylr998_frame_sync)

Preamble detection, sync word extraction, symbol alignment.

Parameters:

Name	Type	Default	Description
sf	int	9	Spreading factor
sample_rate	float	250e3	Sample rate (Hz)
expected_networkid	int	-1	Filter by NETWORKID (-1 = any)
preamble_min	int	4	Minimum preamble symbols

Input: Complex IQ stream Output: Aligned data symbols, NETWORKID

Note: Detects preamble upchirps, extracts NETWORKID from sync word, identifies SFD downchirps, and outputs aligned data symbols.

Frame Generator (rylr998_frame_gen)

Generates complete frame: Preamble + Sync Word + SFD + Data.

Parameters:

Name	Type	Default	Description
sf	int	9	Spreading factor
sample_rate	float	125e3	Sample rate (Hz)
preamble_len	int	8	Preamble length (symbols)
networkid	int	18	RYLR998 NETWORKID (0-255)

Input: Encoded data symbol bins Output: Complete IQ frame samples

---

Hierarchical Blocks

RYLR998 Receiver (rylr998_rx)

Complete RX chain in one block.

Chain: IQ Source → CSS Demod → Frame Sync → PHY Decode → Payload

Parameters: Combines CSS Demod, Frame Sync, and PHY Decode parameters.

RYLR998 Transmitter (rylr998_tx)

Complete TX chain in one block.

Chain: Payload → PHY Encode → Frame Gen → CSS Mod → IQ Output

Parameters: Combines PHY Encode, Frame Gen, and CSS Mod parameters.

---

Signal Flow

RX Chain

IQ Samples
    ↓
┌─────────────────┐
│  CSS Demod      │  FFT peak detection
└────────┬────────┘
         ↓ bins
┌─────────────────┐
│  Frame Sync     │  Preamble detect, NETWORKID extract
└────────┬────────┘
         ↓ aligned symbols
┌─────────────────┐
│  PHY Decode     │  Gray → Deinter → Hamming → Dewhiten
└────────┬────────┘
         ↓
Payload Bytes

TX Chain

Payload Bytes
    ↓
┌─────────────────┐
│  PHY Encode     │  CRC → Whiten → Hamming → Inter → Gray
└────────┬────────┘
         ↓ symbol bins
┌─────────────────┐
│  Frame Gen      │  Add preamble, sync word, SFD
└────────┬────────┘
         ↓ all bins
┌─────────────────┐
│  CSS Mod        │  Generate chirps
└────────┬────────┘
         ↓
IQ Samples

---

Common Parameters

Spreading Factor (SF)

SF	Chips/Symbol	Data Rate	Sensitivity	Range
7	128	Highest	Lowest	Shortest
8	256	↓	↓	↓
9	512	(default)	(typical)	(typical)
10	1024	↓	↓	↓
11	2048	↓	↓	↓
12	4096	Lowest	Highest	Longest

Coding Rate (CR)

CR Value	Rate	Redundancy	Error Correction
1	4/5	25%	Low
2	4/6	50%	Medium
3	4/7	75%	Good
4	4/8	100%	Best

NETWORKID / Sync Word

The RYLR998 NETWORKID (0-255) maps directly to the LoRa sync word byte. See NETWORKID_MAPPING.md for details.

Common values:

• 18 (0x12): Private networks, RYLR998 default
• 52 (0x34): LoRaWAN public networks

---

Implementation Notes

Fractional SFD Handling

The LoRa SFD (Start Frame Delimiter) is 2.25 downchirps, not an integer. This means data symbols start at a fractional sample offset.

The FrameSync block handles this by:

1. Counting 2 full downchirps in the state machine
2. Adding a 0.25 symbol offset when extracting data

If you see data symbols offset by 1-2 positions, check that fractional SFD handling is correct.

Gray Coding

LoRa uses Gray coding to minimize bit errors when adjacent symbols are confused.

• TX (encode): g = b ^ (b >> 1) — converts binary to Gray
• RX (decode): Iterative XOR unwinding — converts Gray back to binary

The decoder's use_grlora_gray parameter controls which direction:

• True: Applies x ^ (x >> 1) (same as TX encode) — use for gr-lora_sdr captures
• False: Applies iterative Gray decode (inverse) — use for loopback testing

Bin Offset Convention

Different receiver implementations use different bin conventions:

Source	Bin Convention	Decoder Setting
gr-lora_sdr	Raw bins + 1	soft_decoding=False (default)
gr-rylr998 loopback	Raw bins	soft_decoding=True

Troubleshooting

Symptom	Likely Cause	Solution
Data symbols offset by 1-2	Fractional SFD not handled	Check FrameSync version
Payload garbage, CRC fails	Wrong Gray mode	Toggle use_grlora_gray
Payload off by 1 symbol	Wrong bin offset	Toggle soft_decoding
NETWORKID wrong	CFO not subtracted	Check cfo_bin parameter
Preamble not detected	Threshold too high	Lower preamble_min