MR16/README.md

# MR16 模块说明文档

## 概述
MR16 是基于 SX1281 2.4GHz 无线收发芯片的遥控数据传输系统，支持多种无线协议（BLE/LoRa/GFSK/FLRC），提供 FreeRTOS CLI 命令行接口和 LCD 状态显示。

## ⚠️ 通信要求 (Critical Requirements)

**发送端和接收端必须配置一致，否则无法通信！**

### 必须匹配的参数：
1. **无线协议模式** - `radio mode <BLE|LORA|GFSK|FLRC>`
   - 双方必须使用相同的协议（如都用 FLRC）
   
2. **波特率** - `radio baudrate <index>`
   - 同一协议下，双方必须使用相同的波特率索引
   - 例如：FLRC 模式下，双方都用 `radio baudrate 2` (520kbps)
   
3. **频率** - `radio channel <MHz>`
   - 双方必须工作在相同频率
   - 例如：都设置为 `radio channel 2450`
   
4. **TX/RX ID** - `mr16 txid <id>` / `mr16 rxid <id>`
   - 发送端的 TX_ID 必须等于接收端的 RX_ID
   - 例如：发送端 `txid 0x1234`，接收端 `rxid 0x1234`

### 配置示例
```bash
# 发送端配置
radio mode FLRC          # 选择 FLRC 协议
radio baudrate 2         # 波特率索引 2 (520kbps)
radio channel 2450       # 频率 2450MHz
mr16 txid 0x1234         # 发送ID

# 接收端配置（必须完全一致）
radio mode FLRC          # 相同协议
radio baudrate 2         # 相同波特率
radio channel 2450       # 相同频率
mr16 rxid 0x1234         # 接收ID = 发送端的TX_ID
```

### 验证方法
```bash
# 使用 show 命令查看当前配置
mr16 show               # 查看 TX_ID/RX_ID
radio mode              # 查看当前协议
radio baudrate          # 查看当前波特率
radio modulation        # 查看详细调制参数
```

### 常见错误
- ❌ 双方协议不同（一个BLE，一个FLRC）→ 完全无法通信
- ❌ 波特率索引不同（一个用2，一个用3）→ 解调失败
- ❌ 频率偏差过大 → 接收不到信号
- ❌ ID不匹配 → 接收到数据但被过滤丢弃

---

## 硬件平台
- **MCU**: STM32F103C8T6 (20KB RAM, 64KB Flash)
- **无线芯片**: SX1281 2.4GHz 收发器
- **显示**: LCD 彩屏 (240x135)
- **接口**: UART2 (CLI + 数据输入), DBUS (数据输出)

## 代码结构

### 文件组织
```
mr16.c - 主实现文件 (1788行)
├─ [PART 1] 核心功能 (MR16 CORE FUNCTIONS)
│  ├─ 无线事件回调
│  ├─ 系统初始化
│  ├─ 主循环
│  └─ 数据包处理
├─ [PART 2] UI显示 (UI DISPLAY FUNCTIONS)
│  ├─ 开机动画
│  ├─ 主界面显示
│  └─ 状态更新
└─ [PART 3] CLI命令 (CLI COMMAND FUNCTIONS)
   ├─ 帮助文本
   ├─ MR16命令处理器
   ├─ Radio命令处理器
   └─ CLI初始化
```

---

## PART 1: 核心功能模块

### 1.1 数据格式 (Data Format)

#### 可变长度模式 (VARIABLE)
- 触发方式: UART 空闲中断
- 长度: 动态，根据实际接收数据
- 适用场景: 不定长数据传输

#### 固定长度模式 (FIXED)
- 长度: 预定义 (默认122字节)
- 可调范围: 1-123 字节 (纯用户数据)
- 适用场景: 固定格式数据，如遥控器

### 1.2 数据包格式

```
完整数据包结构 (最大127字节):
┌─────────┬──────────────────┬─────────┐
│ Header  │   User Data      │   CRC   │
│ 2 bytes │  1-123 bytes     │ 2 bytes │
└─────────┴──────────────────┴─────────┘
```

#### Header (2字节)
- Byte 0: TX_ID 高字节
- Byte 1: TX_ID 低字节
- 用途: 识别发送端，支持多机接收

#### User Data (1-123字节)
- 用户纯数据，不包含 Header 和 CRC
- VARIABLE 模式: 实际接收长度
- FIXED 模式: 配置的 `fixedLength` 值

#### CRC (2字节)
- 算法: CRC16
- 校验范围: Header + User Data
- Byte N+2: CRC 高字节
- Byte N+3: CRC 低字节

### 1.3 数据流向

#### TX 端 (发送端)
```
用户数据 (UART2) 
    ↓
MR16_PackTxBuffer() ← 添加 Header + CRC
    ↓
完整数据包 → SX1281 无线发送
```

#### RX 端 (接收端)
```
SX1281 无线接收
    ↓
验证 Header (RX_ID 匹配)
    ↓
验证 CRC (数据完整性)
    ↓
输出完整包 (含Header) → DBUS/UART
```

### 1.4 失控保护 (Failsafe)

**仅在 RX 端启用**

#### 触发条件
- 100ms 未接收到有效数据

#### 安全帧格式
```
安全帧结构:
┌─────────┬────────────────────────┬─────────┐
│ Header  │  0xFF 0x00 0xFF 0x00   │ 0x00... │
│ 2 bytes │  4 bytes (安全标识)     │ 填充0   │
└─────────┴────────────────────────┴─────────┘
```

#### 实现位置
- `MR16_Main()` 函数中
- 自动构造安全帧到 `txbuffer`
- DBUS 输出自动发送安全帧

### 1.5 核心函数

#### `MR16_Init()`
**功能**: 系统初始化
- 从 Flash 加载配置（失败则用默认值）
- 初始化 CLI 命令系统
- 初始化 SX1281 无线模块
- 初始化 LCD 显示

#### `MR16_Main()`
**功能**: 主循环
- 处理 UART2 数据（区分 CLI 命令 / 用户数据）
- 执行无线收发
- RX 端失控保护
- 定时更新 UI 显示

#### `MR16_PackTxBuffer()`
**功能**: 封装数据包
- 输入: 用户纯数据
- 输出: Header + 数据 + CRC
- 自动添加 TX_ID 和 CRC16 校验

#### `SX1281_Callback()`
**功能**: 无线事件回调
- `RX_DONE`: 接收成功，验证ID，更新计数
- `TX_DONE`: 发送成功，继续发送
- `RX_TIMEOUT` / `TX_TIMEOUT`: 超时处理

---

## PART 2: UI 显示模块

### 2.1 显示界面

#### 开机动画 (`MR16_UI_PowerON`)
- MR16 Logo
- "Initializing..." 提示

#### 主界面 (`MR16_UI_Home`)

**TX 模式显示:**
```
┌──────────────────────────────┐
│ MR16 Status            [TX]  │
├──────────────────────────────┤
│ Mode: FIXED     Power: 10dBm │
│ Radio: FLRC     DataLen: 122B│
│ Freq: 2450MHz                │
│ TXID: 0x1234                 │
└──────────────────────────────┘
```

**RX 模式显示:**
```
┌──────────────────────────────┐
│ MR16 Status            [RX]  │
├──────────────────────────────┤
│ Mode: FIXED     rxcount:     │
│ Radio: FLRC     ch1: 1234    │
│ Freq: 2450MHz   ch2: 567     │
│ rxid: 0x1234 0x5678 0x9ABC   │
└──────────────────────────────┘
```

### 2.2 UI 函数

| 函数 | 功能 | 调用时机 |
|------|------|----------|
| `MR16_UI_PowerON()` | 开机动画 | 系统初始化时 |
| `MR16_UI_Home()` | 主界面 | 初始化完成 / 模式切换 |
| `MR16_UI_UpdateStatus()` | 状态更新 | RX模式 1秒刷新一次 |

---

## PART 3: CLI 命令模块

### 3.1 MR16 系统命令

#### 配置管理
```bash
mr16 save             # 保存配置到 Flash
mr16 get              # 从 Flash 加载配置
mr16 reset            # 恢复默认配置
```

#### 数据格式
```bash
mr16 mode             # 查看当前格式
mr16 mode VARIABLE    # 设置可变长度模式
mr16 mode FIXED       # 设置固定长度模式
```

#### 固定长度设置
```bash
mr16 fixedlen         # 查看当前长度
mr16 fixedlen 100     # 设置用户数据长度为100字节
                      # 范围: 1-123 字节（不含Header和CRC）
                      # 总包长 = fixedlen + 4
```

#### 发射功率
```bash
mr16 power            # 查看当前功率
mr16 power 10         # 设置功率为 10dBm
                      # 范围: -18 到 +13 dBm
```

#### RX ID 配置
```bash
mr16 rxid             # 显示所有 RX ID
mr16 rxid1 0x1234     # 设置 RX ID 1 为 0x1234
mr16 rxid2 0x5678     # 设置 RX ID 2
mr16 rxid3 0x9ABC     # 设置 RX ID 3
                      # 有效范围: 0x0001-0xFFFE
```

#### 操作命令
```bash
mr16 tx               # 启动发送模式
mr16 rx               # 启动接收模式
```

#### 信息查看
```bash
mr16 show             # 显示所有配置
mr16 help             # 显示帮助信息
```

### 3.2 Radio 无线命令

#### 协议模式
```bash
radio mode            # 查看当前协议
radio mode BLE        # 切换到 BLE 模式
radio mode LORA       # 切换到 LoRa 模式
radio mode GFSK       # 切换到 GFSK 模式
radio mode FLRC       # 切换到 FLRC 模式
```

#### 频率设置
```bash
radio rffreq          # 查看当前频率
radio rffreq 2450000000   # 设置为 2450MHz
```

#### 调制参数
```bash
radio modulation help     # 查看调制参数帮助
radio modulation          # 显示当前调制参数

# BLE/GFSK 示例:
radio modulation br_bw 0x4C      # 设置比特率/带宽
radio modulation modindex 1      # 设置调制指数
radio modulation shaping 0x10    # 设置波形整形

# LoRa 示例:
radio modulation sf 0x70         # 设置扩频因子 SF7
radio modulation bw 0x18         # 设置带宽 800kHz
radio modulation cr 0x01         # 设置编码率 4/5

# FLRC 示例:
radio modulation br_bw 0x45      # 比特率/带宽
radio modulation cr 0x00         # 编码率
radio modulation shaping 0x10    # 波形整形
```

#### 数据包参数
```bash
radio packet help         # 查看数据包参数帮助
radio packet              # 显示当前包参数

# GFSK/FLRC 示例:
radio packet Preamble 0x30        # 前导码长度
radio packet SyncWordLength 0x04  # 同步字长度
radio packet Header 0x00          # 包头类型 (VARIABLE)
radio packet Payload 127          # 载荷长度
radio packet Crc 0x20             # CRC 类型
radio packet Whitening 0x00       # 白化开启

# 同步字设置:
radio packet SyncWord             # 显示所有同步字
radio packet SyncWord1 0x12345678 # 设置同步字1
radio packet SyncWord2 0xABCDEF00 # 设置同步字2
radio packet SyncWord3 0x11223344 # 设置同步字3

# LoRa 示例:
radio packet Preamble 8           # 前导码符号数
radio packet Header 0x00          # 显式包头
radio packet Payload 64           # 载荷长度
radio packet Crc 0x20             # CRC 开启
radio packet InvertIQ 0x40        # IQ 正常
```

#### 波特率
```bash
radio baudrate            # 显示所有协议波特率
radio baudrate BLE 1      # 设置 BLE 波特率
radio baudrate LORA 3     # 设置 LoRa 波特率
radio baudrate GFSK 2     # 设置 GFSK 波特率
radio baudrate FLRC 3     # 设置 FLRC 波特率
```

#### 其他参数
```bash
radio power 10            # 设置发射功率 (dBm)
radio ramptime 10         # 设置上升时间 (us)
                          # 可选: 2/4/6/8/10/12/16/20
```

### 3.3 命令特性

- **不区分大小写**: `MODE` = `mode` = `Mode`
- **参数自动解析**: 支持十进制、十六进制 (0x前缀)
- **帮助系统**: 所有命令支持 `help` 子命令
- **分页输出**: 长帮助文本自动分页显示
- **实时生效**: 参数修改后立即更新硬件
- **自动刷新**: 参数变更后自动更新 LCD 显示

---

## 典型应用场景

### 场景1: 遥控器发射端
```bash
# 初始配置
mr16 mode FIXED           # 固定长度模式
mr16 fixedlen 18          # 18字节遥控数据
radio mode FLRC           # 使用 FLRC 协议（低延迟）
mr16 power 10             # 10dBm 发射功率
mr16 save                 # 保存配置

# 启动发送
mr16 tx
```

### 场景2: 接收机
```bash
# 配置多机接收
mr16 rxid1 0x1234         # 遥控器1
mr16 rxid2 0x5678         # 遥控器2
mr16 rxid3 0x9ABC         # 遥控器3
radio mode FLRC
mr16 save

# 启动接收（带失控保护）
mr16 rx
```

### 场景3: 透传模式
```bash
# 可变长度透传
mr16 mode VARIABLE        # 不定长数据
radio mode GFSK           # GFSK 协议
mr16 save
```

---

## 配置参数说明

### Flash 存储结构
```c
Config_t {
  MR16_Param_t mr16;      // MR16 参数
  uint32_t earsed_count;  // 擦写次数
}

MR16_Param_t {
  SX1281_Params_t radioParams;  // 无线参数
  MR16_DataFormat_t format;     // 数据格式
  uint16_t fixedLength;         // 固定长度
  uint16_t TX_ID;               // 发送ID
  uint16_t RX_ID[3];            // 接收ID (3个)
}
```

### 默认配置
```c
format       = MR16_FORMAT_FIXED
fixedLength  = 122
TX_ID        = 0x1234
RX_ID[0]     = 0x5678
RX_ID[1]     = 0x0000 (禁用)
RX_ID[2]     = 0x0000 (禁用)
radioMode    = FLRC
rfFrequency  = 2450000000 (2450MHz)
txOutputPower = 10 (dBm)
```

---

## 性能指标

| 参数 | 值 |
|------|---|
| 最大数据包长度 | 127 字节 |
| 最大用户数据 | 123 字节 |
| DBUS 输出频率 | 71Hz (14ms间隔) |
| 失控检测延迟 | 100ms |
| UI 刷新频率 | 1Hz (RX模式) |
| 命令响应 | <10ms |

---

## 注意事项

### 数据长度限制
⚠️ **已知问题**: 117-118 字节总包长（113-114字节用户数据）会触发 SX1281 TX 超时
- 建议用户数据不超过 112 字节
- 固定长度模式建议设置 ≤ 110 字节

### ID 配置
- TX_ID / RX_ID 有效范围: `0x0001` - `0xFFFE`
- `0x0000` 和 `0xFFFF` 为无效值，用于禁用通道

### 失控保护
- **仅 RX 端检测**: TX 端正常发送，不关心接收状态
- **安全帧识别**: 下游设备需检测 `0xFF 0x00 0xFF 0x00` 模式
- **避免冲突**: 正常数据避免出现连续的安全帧模式

### Flash 寿命
- STM32 Flash 擦写次数: 约 10,000 次
- 避免频繁 `mr16 save` 操作
- 建议只在配置完成后保存一次

---

## 开发者信息

- **版本**: 2.0
- **最后更新**: 2024-12-09
- **开发团队**: MR16 Development Team

## 相关文件
- `mr16.c` - 主实现文件
- `mr16.h` - 头文件定义
- `config.c` - 配置管理
- `sx1281_driver.c` - SX1281 驱动
- `lcd.c` - LCD 驱动

---

**文档结束**