microReticulumTbeam/exercises/01_lora_ascii_pingpong/README.md

# Exercise: LoRa Transmission Validation (SX1262)

## Overview

This exercise validates raw LoRa packet transmission from the **LILYGO T-Beam SUPREME V3.0** using the onboard **SX1262** radio.

The objective is to:

1. Transmit deterministic LoRa packets at known parameters.
2. Confirm successful reception using:

   * A second T-Beam
   * A Waveshare SX1303 concentrator sniffer
   * Or any SDR/LoRa receiver configured with identical PHY settings
3. Verify correct alignment of frequency, spreading factor, bandwidth, and coding rate.

This is a **PHY-layer validation exercise**, not LoRaWAN.

---

## Hardware

### Transmitter

* Board: **LILYGO T-Beam SUPREME V3.0**
* MCU: ESP32-S3
* Radio: SX1262
* Antenna: 915 MHz tuned antenna
* Power: USB-C or 18650 battery

### Receiver / Sniffer

Any device capable of raw LoRa reception with manual PHY configuration:

* Second T-Beam (SX1262)
* Waveshare SX1303 + `lora_pkt_fwd`
* SDR with LoRa demodulator

---

## LoRa Radio Specifications

The sniffer **must** match these parameters exactly.

| Parameter        | Value              |
| ---------------- | ------------------ |
| Radio Chip       | SX1262             |
| Frequency        | **915.000 MHz**    |
| Modulation       | LoRa               |
| Bandwidth        | **125 kHz**        |
| Spreading Factor | **SF8**            |
| Coding Rate      | **4/5**            |
| Preamble Length  | 8 symbols          |
| Sync Word        | 0x12 (Public LoRa) |
| CRC              | Enabled            |
| IQ Inversion     | Disabled           |
| Output Power     | 14 dBm (default)   |

---

## Important Notes for Sniffer Operators

### 1. Frequency

Ensure your sniffer JSON or configuration file contains:

```
"freq": 915000000
```

If using SX130x HAL:

```
915000000
```

No offset. No channel hopping.

---

### 2. Spreading Factor

Must be:

```
SF8
```

If the sniffer is set to multi-SF mode, confirm that SF8 is enabled.

---

### 3. Bandwidth

```
125000 Hz
```

Not 250 kHz. Not 500 kHz.

---

### 4. Coding Rate

```
4/5
```

Some interfaces represent this as:

```
CR = 1
```

---

### 5. Sync Word

If your sniffer filters on sync word:

```
0x12
```

This is the public LoRa sync word (not LoRaWAN private).

---

## Expected Packet Behavior

The transmitter:

* Sends a short ASCII payload
* Repeats at a fixed interval
* Does not use LoRaWAN
* Does not use encryption
* Does not use MAC layer framing

Sniffer output should display:

* RSSI
* SNR
* SF8
* BW125
* Payload length matching transmitter

---

## Confirming Correct Alignment

A properly aligned sniffer will show:

* Stable RSSI
* Correct SF detection (SF8)
* Clean CRC pass
* No excessive packet loss at short range

If you see:

* No packets → Check frequency mismatch first.
* Packets but CRC fail → Check bandwidth mismatch.
* Packets only intermittently → Check spreading factor.

---

## SX1262 SPI Mapping (T-Beam SUPREME)

For reference, the radio is connected as follows:

| Signal | ESP32-S3 Pin |
| ------ | ------------ |
| SCK    | 12           |
| MISO   | 13           |
| MOSI   | 11           |
| CS     | 10           |
| RESET  | 5            |
| BUSY   | 4            |
| DIO1   | 1            |

These match the board’s hardware routing.

---

## Build & Flash

### PlatformIO

1. Open project folder
2. Select correct environment
3. Compile
4. Upload via USB-C
5. Monitor serial output

### Arduino IDE

* Board: ESP32S3 Dev Module
* Flash: 8MB
* PSRAM: QSPI
* Upload speed: 921600
* USB Mode: CDC and JTAG

---

## Purpose of This Exercise

This exercise verifies:

* SPI communication with SX1262
* Radio configuration correctness
* Antenna functionality
* Sniffer alignment
* Baseline RF performance

It is intended as the foundational RF validation step before:

* Reticulum interface integration
* microReticulum radio abstraction
* LoRa time-synchronized experiments
* Multi-node field testing

---

## If You Cannot See Packets

Work through this checklist:

1. Confirm antenna attached.
2. Confirm sniffer at 915 MHz.
3. Confirm SF8.
4. Confirm BW125.
5. Reduce distance to < 2 meters.
6. Increase TX power to 17–20 dBm for testing.
7. Confirm no regional regulatory lock mismatch.

---

## Relationship to `main.cpp`

This README corresponds to the current exercise implementation in:

```
main.cpp
```

See source for definitive parameter values 

If you modify radio parameters in code, update this README accordingly.