gr-rylr998/docs/GRC_FLOWGRAPHS.md

GRC Flowgraph Guide

GNU Radio Companion (GRC) integration for gr-rylr998.

Installation

After installing gr-rylr998, the blocks appear in GRC under the [RYLR998] category.

# Install the module
cd gr-rylr998
pip install -e .

# Refresh GRC block tree
grcc --help  # or restart GRC

Block Palette

Block	Category	Description
RYLR998 Receiver	[RYLR998]	Complete RX chain (hier block)
RYLR998 Transmitter	[RYLR998]	Complete TX chain (hier block)
CSS Demodulator	[RYLR998]	FFT-based chirp demodulation
CSS Modulator	[RYLR998]	Chirp generation from bins
Frame Sync	[RYLR998]	Preamble/sync word detection
Frame Generator	[RYLR998]	Preamble/SFD/sync word generation
PHY Decoder	[RYLR998]	Gray → deinterleave → Hamming → dewhiten
PHY Encoder	[RYLR998]	Whiten → Hamming → interleave → Gray

---

Quick Start Flowgraphs

1. Basic Receiver (BladeRF → Decoded Payload)

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  osmocom Source │────▶│  RYLR998 Receiver │────▶│  Message Debug  │
│  (BladeRF)      │ IQ  │  SF9, NID=18     │ msg │  (or File Sink) │
└─────────────────┘     └──────────────────┘     └─────────────────┘

GRC Setup:

1. Add osmocom Source (or your SDR source)

   • Device Arguments: bladerf=0
   • Sample Rate: 250e3
   • Center Freq: 915e6 (or your frequency)

2. Add RYLR998 Receiver

   • Spreading Factor: 9
   • Sample Rate: 250e3
   • Bandwidth: 125e3
   • Expected NETWORKID: 18 (or -1 for any)

3. Add Message Debug (or PDU to Tagged Stream → File Sink)

4. Connect: Source → RYLR998 RX → Debug

---

2. Basic Transmitter (Payload → BladeRF)

┌─────────────────┐     ┌──────────────────────┐     ┌─────────────────┐
│  Message Strobe │────▶│  RYLR998 Transmitter │────▶│  osmocom Sink   │
│  "Hello"        │ msg │  SF9, NID=18         │ IQ  │  (BladeRF)      │
└─────────────────┘     └──────────────────────┘     └─────────────────┘

GRC Setup:

1. Add Message Strobe (or PDU Generator)

   • Message: pmt.intern("Hello, LoRa!")
   • Period: 1000 (ms)

2. Add RYLR998 Transmitter

   • Spreading Factor: 9
   • Sample Rate: 125e3
   • Bandwidth: 125e3
   • NETWORKID: 18
   • Preamble Length: 8

3. Add osmocom Sink

   • Device Arguments: bladerf=0
   • Sample Rate: 125e3
   • Center Freq: 915e6

4. Connect: Strobe → RYLR998 TX → Sink

---

3. Loopback Test (No Hardware)

┌─────────────────┐     ┌────────────┐     ┌─────────────┐     ┌─────────────────┐
│  Message Strobe │────▶│ RYLR998 TX │────▶│ Channel Sim │────▶│  RYLR998 RX     │
│  "Test"         │     │ NID=18     │     │ (optional)  │     │  NID=18         │
└─────────────────┘     └────────────┘     └─────────────┘     └────────┬────────┘
                                                                        │
                                                                        ▼
                                                               ┌─────────────────┐
                                                               │  Message Debug  │
                                                               └─────────────────┘

GRC Setup:

1. TX chain as above (but no SDR sink)
2. Optionally add Channel Model for noise/fading
3. Add RYLR998 Receiver
4. Add Message Debug to see decoded payloads
5. Connect: TX IQ → (Channel) → RX → Debug

---

Advanced Flowgraphs

4. Multi-Channel Scanner

Scan multiple LoRa channels and decode any detected frames:

                         ┌────────────────┐     ┌──────────────┐
                    ┌───▶│ Freq Xlating   │────▶│ RYLR998 RX   │───┐
                    │    │ Filter (ch 0)  │     │ SF9          │   │
┌─────────────┐     │    └────────────────┘     └──────────────┘   │
│  SDR Source │─────┤                                              │   ┌─────────────┐
│  Wideband   │     │    ┌────────────────┐     ┌──────────────┐   ├──▶│ Msg Mux/    │
└─────────────┘     ├───▶│ Freq Xlating   │────▶│ RYLR998 RX   │───┤   │ Aggregator  │
                    │    │ Filter (ch 1)  │     │ SF9          │   │   └─────────────┘
                    │    └────────────────┘     └──────────────┘   │
                    │                                              │
                    └───▶ ... more channels ...                ────┘

Key Settings:

• SDR Source: Wide bandwidth (e.g., 2 MHz)
• Freq Xlating Filters: Tune to each channel center
• Each RX can have different SF/NETWORKID

---

5. Detailed RX Chain (Custom Processing)

For advanced users who need access to intermediate data:

┌───────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌───────────┐
│ SDR Source│────▶│ CSS Demod   │────▶│ Frame Sync  │────▶│ PHY Decode  │────▶│ Msg Debug │
│           │ IQ  │             │bins │             │syms │             │ msg │           │
└───────────┘     └──────┬──────┘     └──────┬──────┘     └─────────────┘     └───────────┘
                         │                   │
                         ▼                   ▼
                  ┌─────────────┐     ┌─────────────┐
                  │ File Sink   │     │ Tag Debug   │
                  │ (raw bins)  │     │ (NETWORKID) │
                  └─────────────┘     └─────────────┘

This allows:

• Saving raw demodulated bins for analysis
• Monitoring NETWORKID without full decode
• Custom filtering between stages

---

6. Detailed TX Chain (Custom Processing)

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌───────────┐
│ Msg Source  │────▶│ PHY Encode  │────▶│ Frame Gen   │────▶│ CSS Mod     │────▶│ SDR Sink  │
│             │bytes│             │bins │             │bins │             │ IQ  │           │
└─────────────┘     └─────────────┘     └──────┬──────┘     └─────────────┘     └───────────┘
                                               │
                                               ▼
                                        ┌─────────────┐
                                        │ Vector Sink │
                                        │ (frame bins)│
                                        └─────────────┘

This allows:

• Inspecting encoded symbols before modulation
• Custom preamble/sync word injection
• Frame structure debugging

---

Parameter Reference

Common Parameters (All Blocks)

Parameter	Values	Description
Spreading Factor	7-12	Higher = longer range, lower rate
Sample Rate	Hz	Must be ≥ bandwidth × oversampling
Bandwidth	125e3, 250e3, 500e3	LoRa signal bandwidth
Coding Rate	1-4	1=4/5, 2=4/6, 3=4/7, 4=4/8

RX-Specific Parameters

Parameter	Default	Description
Expected NETWORKID	-1	Filter frames by NID (-1 = accept all)
use_grlora_gray	True	Gray mapping mode (see notes)
soft_decoding	False	Bin offset mode (see notes)

TX-Specific Parameters

Parameter	Default	Description
NETWORKID	18	Encode this NID in sync word
Preamble Length	8	Number of preamble upchirps

---

Sample Rate Guidelines

Configuration	Minimum Sample Rate	Recommended
BW=125kHz, any SF	125 kHz	250 kHz
BW=250kHz, any SF	250 kHz	500 kHz
BW=500kHz, any SF	500 kHz	1 MHz

Note: Higher sample rates improve timing accuracy but increase CPU load.

---

Tips & Troubleshooting

No Frames Detected

1. Check center frequency - Must match RYLR998 setting
2. Check NETWORKID - Set to -1 to accept any, or match RYLR998
3. Check bandwidth - RYLR998 default is 125 kHz
4. Lower sample rate - Try sample_rate = bw first
5. Check antenna - Ensure proper connection

Decoded Payload is Garbage

1. SF mismatch - Must match transmitter exactly
2. CR mismatch - Must match transmitter
3. Wrong decode mode - For real SDR captures, use defaults

High CPU Usage

1. Reduce sample rate - Use minimum needed
2. Increase SF - Lower symbol rate = less processing
3. Add decimation - Before RYLR998 RX block

Message Output Format

The RX block outputs PMT messages with:

{
    'payload': bytes,        # Decoded payload
    'networkid': int,        # Extracted NETWORKID
    'cfo_bin': float,        # Carrier frequency offset
    'crc_ok': bool,          # CRC verification result
    'rssi': float,           # Signal strength (if available)
}

---

Example GRC Files

The examples/ directory contains ready-to-use flowgraphs:

File	Description
rylr998_rx_flowgraph.grc	BladeRF → RX → File output
rylr998_tx_flowgraph.grc	File input → TX → BladeRF
rylr998_loopback_test.grc	Software loopback verification

To use:

gnuradio-companion examples/rylr998_rx_flowgraph.grc

---

Integration with Other Tools

With gr-lora_sdr

gr-rylr998 is compatible with gr-lora_sdr. You can:

• Use gr-lora_sdr CSS demod → gr-rylr998 PHY decode
• Use gr-rylr998 PHY encode → gr-lora_sdr CSS mod

With SoapySDR

Any SoapySDR-supported device works:

Device Arguments: soapy=0,driver=bladerf

With File Sources

For offline analysis:

File Source → Throttle → RYLR998 RX → Message Debug

Set throttle rate to match original sample rate.