Ryan Malloy
c839d225a8
GNU Radio Out-of-Tree module providing: - Complete TX chain: PHYEncode → FrameGen → CSSMod - Complete RX chain: CSSDemod → FrameSync → PHYDecode - NETWORKID extraction/encoding (0-255 range) - All SF (7-12) and CR (4/5-4/8) combinations - Loopback tested with 24/24 configurations passing Key features: - Fractional SFD (2.25 downchirp) handling - Gray encode/decode with proper inverse operations - gr-lora_sdr compatible decode modes - GRC block definitions and example flowgraphs - Comprehensive documentation Discovered RYLR998 sync word mapping: sync_bin_1 = (NETWORKID >> 4) * 8 sync_bin_2 = (NETWORKID & 0x0F) * 8
305 lines
12 KiB
Markdown
305 lines
12 KiB
Markdown
# 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.
|
||
|
||
```bash
|
||
# 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:
|
||
```python
|
||
{
|
||
'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:
|
||
```bash
|
||
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.
|