# LoRa_RFFI

**Repository Path**: hylan-j/LoRa_RFFI

## Basic Information

- **Project Name**: LoRa_RFFI
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 47
- **Forks**: 29
- **Created**: 2024-12-15
- **Last Updated**: 2025-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 自述

本课题构建了基于深度学习技术的LoRa射频指纹识别（RFFI）系统。还提供了包含从60个LoRa设备收集的信号的数据集。不同子数据集的详细收集设置可以在章节[数据集描述](#jump1)中找到。[代码示例](#jump2)部分介绍了一些重要函数的用法，详细用法请仔细阅读代码注释。

## 引用

如果数据集/代码的一部分对您的项目有贡献，请引用：

```
[1] G. Shen, J. Zhang, A. Marshall, and J. Cavallaro.   “Towards Scalable and Channel-Robust Radio Frequency 
Fingerprint Identification for LoRa,” IEEE Trans. Inf. Forensics Security, 2022.
```

```
@article{shen2021towards,
  title={Towards Scalable and Channel-Robust Radio Frequency Fingerprint Identification for LoRa},
  author={Shen, Guanxiong and Zhang, Junqing and Marshall, Alan and Cavallaro, Joseph},
  journal={IEEE Trans. Inf. Forensics Security},
  year={2021}
}
```

## 数据集描述

<span id="jump1"></span>

### 实验设备

实验中包括60种商用LoRa器件（LoPy4，mbed SX1261 shields，FiPy，Dragino SX1276 shields）。下表提供了它们的更多细节。

| 设备索引      | 型号                  | 芯片组   |
| ------------ | --------------------- | ------- |
| 1 - 45       | Pycom LoPy4           | SX1276  |
| 46 - 50      | mbed SX1261 shield    | SX1261  |
| 51 - 55      | Pycom FiPy            | SX1272  |
| 56 - 60      | Dragino SX1276 shield | SX1276  |

所有的LoRa报文都由USRP N210软件定义无线电（SDR）捕获。

### 数据集结构

数据集由26个子数据集组成，每个子数据集是一个HDF5文件。每个HDF5文件包含多个LoRa信号（前导部分IQ样本）和相应的设备标签。由于HDF5不支持复数，我们将信号i支路（实部）和q支路（虚部）连接起来，然后保存。下图显示了原始HDF5数据集的结构。

<img src="./readme_images/HDF5.jpg" width="700" height="450" />

### 训练数据集

下表总结了每个训练数据集的基本信息。所有训练数据集都是在发射器和接收器之间有视线（LOS）的住宅房间中收集的。


| 训练数据集路径                             | 设备     | 每个设备采集的包数            | 增强                                |
| ----------------------------------------- | ------- | ---------------------------- | ---------------------------------- |
| Dataset/Train/dataset_training_aug.h5     | 1 - 30  | 1,000                        | Yes, both multipath & Doppler      |
| Dataset/Train/dataset_training_aug_0hz.h5 | 1 - 30  | 1,000                        | Yes, only multipath ($f_d$ = 0 Hz) |
| Dataset/Train/dataset_training_no_aug.h5  | 1 - 30  | 500                          | No                                 |


### 测试/注册数据集

测试/注册数据集在一个住宅房间、一个办公楼和一个会议室收集。平面图如下图所示：

<img src="./readme_images/floor_plan.jpg" width="700" height="330" />

下表总结了每个测试/注册数据集的基本信息。

| 测试数据集路径                                       | 设备     | 每个设备采集的包数            | 采集环境                                        |
| --------------------------------------------------- | ------- | ---------------------------- | ---------------------------------------------- |
| Dataset/Test/dataset_seen_devices.h5                | 1 - 30  | 400                          | Residential room, LOS, stationary              |
| Dataset/Test/dataset_rogue.h5                       | 41 - 45 | 200                          | Residential room, LOS, stationary              |
| Dataset/Test/dataset_residential.h5                 | 31 - 40 | 400                          | Residential room, LOS, stationary              |
| Dataset/Test/dataset_other_device_type.h5           | 46 - 60 | 400                          | Residential room, LOS, stationary              |
| Dataset/Test/channel_problem/A.h5                   | 31 - 40 | 200                          | Location A, LOS, stationary                    |
| Dataset/Test/channel_problem/B.h5                   | 31 - 40 | 200                          | Location B, LOS, stationary                    |
| Dataset/Test/channel_problem/C.h5                   | 31 - 40 | 200                          | Location C, LOS, stationary                    |
| Dataset/Test/channel_problem/D.h5                   | 31 - 40 | 200                          | Location D, NLOS, stationary                   |
| Dataset/Test/channel_problem/E.h5                   | 31 - 40 | 200                          | Location E, NLOS, stationary                   |
| Dataset/Test/channel_problem/F.h5                   | 31 - 40 | 200                          | Location F, NLOS, stationary                   |
| Dataset/Test/channel_problem/B_walk.h5              | 31 - 40 | 200                          | Location B, LOS, object moving                 |
| Dataset/Test/channel_problem/F_walk.h5              | 31 - 40 | 200                          | Location F, NLOS, object moving                |
| Dataset/Test/channel_problem/moving_office.h5       | 31 - 40 | 200                          | LOS, mobile in the office                      |
| Dataset/Test/channel_problem/moving_meeting_room.h5 | 31 - 40 | 200                          | NLOS, mobile in the meeting room               |
| Dataset/Test/channel_problem/B_antenna.h5           | 31 - 40 | 200                          | Location B, LOS, stationary, parallel antenna  |
| Dataset/Test/channel_problem/F_antenna.h5           | 31 - 40 | 200                          | Location F, NLOS, stationary, parallel antenna |

## 代码示例
<span id="jump2"></span>

### 1. 开始之前

#### a) 安装所需软件包

请找到“requirement.txt”文件来安装所需的软件包。

#### b) 下载数据集

请下载数据集并将其放在项目文件夹中，下载链接为 'https://ieee-dataport.org/open-access/lorarffidataset'.

#### c) 操作系统

这个项目完全建立在Windows操作系统上。在其他操作系统上可能会出现意想不到的问题。


### 2. 快速启动
在安装正确版本的软件包并下载数据集后，您可以直接运行‘main.py’文件进行RFF提取器训练/流氓设备检测/分类任务。您可以更改第364行中的变量‘run_for’来指定要执行的任务。例如，如果您将‘run_for’设置为‘ train ’，该程序将训练RFF提取器并保存它。

### 3. 加载数据集

建议使用我们提供的“LoadDataset”类函数来加载原始HDF5文件。您需要在运行它之前指定数据集路径、设备范围和数据包范围。下面是一个加载HDF5文件的例子：

```python
import numpy as np
from dataset_preparation import LoadDataset

LoadDatasetObj = LoadDataset()
data, label = LoadDatasetObj.load_iq_samples(file_path = './dataset/Train/dataset_training_aug.h5', 
                                             dev_range = np.arange(0,30, dtype = int), 
                                             pkt_range= np.arange(0,100, dtype = int))
```

这个例子将总共提取（$10\times100=1000$）个LoRa信号。更具体地说，它将从范围内的每个设备中提取100个数据包。函数‘load_iq_samples’返回两个数组，data和label。data是一个大小为（1000,8192）的complex128数组，label是一个大小为（1000,1）的int32数组。下图展示了这两个数组的结构。

<img src="./readme_images/loaded_dataset.png" width="600" height="500" />

<font color="#dd0000">请注意，加载的标签从0开始，而不是1，以适应深度学习。换句话说，设备1被标记为0，设备2被标记为1，以此类推。</font> 


### 4. 生成信道独立频谱图
信道无关谱图有助于减轻接收信号中的信道效应，使LoRa-RFFI系统对信道变化具有更强的鲁棒性。我们提供了将IQ样本阵列转换为信道独立谱图的功能。下面的代码块给出了一个例子：

```python
from dataset_preparation import ChannelIndSpectrogram

ChannelIndSpectrogramObj = ChannelIndSpectrogram()
# The input 'data' is the loaded IQ samples in the last example.
ch_ind_spec = ChannelIndSpectrogramObj.channel_ind_spectrogram(data)
```

返回的‘ch_ind_spec’是一个大小为（1000,102,62,1）的数组。请注意，数组的大小受到STFT参数的影响，这些参数可以在代码中更改。请参阅我们的论文或代码注释，以找到信道无关谱图的详细推导。

### 5. 训练一个RFF提取器
函数‘train_feature_extractor()’可以使用三元组损失训练RFF提取器。

```python
import numpy as np
from deep_learning_models import TripletNet, identity_loss
from sklearn.model_selection import train_test_split
from keras.callbacks import EarlyStopping, ReduceLROnPlateau
from keras.optimizers import RMSprop

feature_extractor = train_feature_extractor()
```

您还可以指定训练数据集路径、训练设备范围、训练数据包范围和增强期间的信噪比范围。否则，将使用默认值。示例如下：

```python
feature_extractor = train_feature_extractor(file_path = './dataset/Train/dataset_training_aug.h5', 
                                            dev_range = np.arange(0,10, dtype = int), 
                                            pkt_range = np.arange(0,1000, dtype = int), 
                                            snr_range = np.arange(20,80)):
```

### 6. 非法设备检测
函数test_rogue_device_detection（）执行非法设备检测任务。在运行该函数之前，必须指定RFF提取器路径。请看下面的例子：

```python
import numpy as np
from sklearn.neighbors import KNeighborsClassifier
from sklearn.metrics import roc_curve, auc

fpr, tpr, roc_auc, eer = test_rogue_device_detection('./models/Extractor_1.h5')
```

该函数返回假阳性率（FPR）、真阳性率（TPR）、曲线下面积（AUC）和等错误率（EER）。这些都是流氓设备检测任务中重要的评估指标。它们的定义请参考我们的论文。

以下代码行使用返回的结果绘制ROC曲线：

```python
import matplotlib.pyplot as plt

# Plot the ROC curves.
plt.figure(figsize=(4.8, 2.8))
plt.xlim(-0.01, 1.02)
plt.ylim(-0.01, 1.02)
plt.plot([0, 1], [0, 1], 'k--')
plt.plot(fpr, tpr, label='Extractor 1, AUC = ' 
         + str(round(roc_auc,3)) + ', EER = ' + str(round(eer,3)), C='r')
plt.xlabel('False positive rate')
plt.ylabel('True positive rate')
plt.title('ROC curve')
plt.legend(loc=4)
# plt.savefig('roc_curve.pdf',bbox_inches='tight')
plt.show()    
```

### 7. 分类
函数‘test_classification()’执行分类任务。在运行该函数之前，必须指定注册数据集、测试数据集和RFF提取器的路径。这里有一个简单的例子：

```python
from sklearn.metrics import accuracy_score
from sklearn.neighbors import KNeighborsClassifier
import numpy as np

pred_label, true_label, acc = test_classification(file_path_enrol = 
                                                  './dataset/Test/dataset_residential.h5',
                                                  file_path_clf = 
                                                  './dataset/Test/channel_problem/A.h5',
                                                  feature_extractor_name = 
                                                  './models/Extractor_1.h5')
```
这个示例返回预测标签、真实标签和总体分类精度。我们可以进一步绘制混淆矩阵来查看细粒度的分类结果：

```python
import matplotlib.pyplot as plt
import seaborn as sns

# Plot the confusion matrix.
conf_mat = confusion_matrix(true_label, pred_label)
classes = test_dev_range + 1 # xticklabels

plt.figure()
sns.heatmap(conf_mat, annot=True, 
            fmt = 'd', cmap='Blues',
            cbar = False,
            xticklabels=classes, 
            yticklabels=classes)
plt.xlabel('Predicted label', fontsize = 20)
plt.ylabel('True label', fontsize = 20)
```


## 许可证
数据集和代码遵循知识共享署名-非商业-相同方式共享4.0国际许可协议。

## 联系
如果您有任何问题，请联系以下电子邮件地址：

gxshen AT seu.edu.cn <br>

Junqing.Zhang AT liverpool.ac.uk