# rpi_ble_network

**Repository Path**: mkirin/rpi_ble_network

## Basic Information

- **Project Name**: rpi_ble_network
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RPi-BLE-Network

树莓派BLE一键配网程序 - 类似ESP32 SmartConfig功能

## 项目简介

RPi-BLE-Network是一个为树莓派5开发的基于BLE（低功耗蓝牙）的一键配网程序。用户可以通过手机APP连接树莓派的蓝牙，发送WiFi配置信息，实现WiFi配网功能。

## 功能特性

- 开机自动启动BLE服务
- 无需配对码即可连接
- JSON格式消息传递
- 设备状态查询（WiFi连接状态、IP地址等）
- WiFi配置和连接
- 可配置参数
- 完善的日志记录

## 系统要求

### 硬件
- 树莓派5（推荐）
- 其他支持BLE的Linux设备（需测试）

### 操作系统
- Debian 11/12/13 (Bookworm)
- Raspberry Pi OS
- Ubuntu 20.04+
- 其他支持 BlueZ 5.50+ 的 Linux 发行版

### 桌面环境
**本项目不依赖任何桌面环境**，可在以下所有环境运行：
- ✅ GNOME
- ✅ KDE Plasma (Wayland/X11)
- ✅ XFCE
- ✅ LXDE
- ✅ 无桌面环境（headless/服务器模式）

## 快速开始

### 一键安装依赖并编译

```bash
# 克隆项目
git clone https://github.com/your-repo/rpi-ble-network.git
cd rpi-ble-network

# 安装依赖（需要sudo）
sudo make deps

# 编译
make

# 安装（需要sudo）
sudo make install

# 启动服务
sudo systemctl enable --now rpi-ble-network
```

## 依赖说明

### 编译时依赖

| 依赖包 | 用途 | 安装命令 |
|--------|------|---------|
| build-essential | 编译工具链 | `sudo apt install build-essential` |
| pkg-config | 编译标志管理 | `sudo apt install pkg-config` |
| libglib2.0-dev | GLib 开发库 | `sudo apt install libglib2.0-dev` |
| libdbus-1-dev | DBus 开发库 | `sudo apt install libdbus-1-dev` |
| libcjson-dev | JSON 解析库 | `sudo apt install libcjson-dev` |

### 运行时依赖

| 依赖包 | 用途 |
|--------|------|
| bluez | 蓝牙协议栈 |
| wpa_supplicant | WiFi 管理 |

### 一键安装所有依赖

```bash
# Debian/Ubuntu/Raspberry Pi OS
sudo apt update
sudo apt install -y build-essential pkg-config \
    libglib2.0-dev libdbus-1-dev libcjson-dev \
    bluetooth bluez wpasupplicant
```

### 关于 GLib 的说明

**GLib 是纯 C 工具库，不依赖任何桌面环境**（GTK/GNOME/KDE）。本项目使用 GLib 的原因：
- GMainLoop：事件驱动的主循环
- GDBus：D-Bus 高级 API，简化 BlueZ 通信
- 跨平台兼容性

详细依赖说明请参考 [docs/DEPENDENCIES.md](docs/DEPENDENCIES.md)

## 编译安装

### 1. 检查依赖

```bash
make check-deps
```

### 2. 编译

```bash
make clean
make
```

### 3. 安装

```bash
sudo make install
```

### 4. 启用服务

```bash
sudo systemctl enable rpi-ble-network
sudo systemctl start rpi-ble-network
```

## 配置

配置文件位于 `/etc/rpi-ble-network/config.json`：

```json
{
    "bluetooth": {
        "name_prefix": "rpi",
        "auto_start": true,
        "advertising_interval": 100
    },
    "network": {
        "connect_timeout": 30,
        "max_retry": 3,
        "scan_timeout": 10
    },
    "service": {
        "log_level": "INFO",
        "log_file": "/var/log/rpi-ble-network.log"
    }
}
```

## BLE GATT服务

### 服务UUID
`0000FFE0-0000-1000-8000-00805F9B34FB`

### 特征值

| 特征值 | UUID | 属性 | 功能 |
|--------|------|------|------|
| 设备状态 | FFE1 | Read, Notify | 查询设备状态 |
| WiFi配置 | FFE2 | Write | 配置WiFi |
| 状态通知 | FFE3 | Notify | 状态变化通知 |

## 消息协议

### 设备状态查询请求
```json
{
    "type": "query_status",
    "timestamp": 1234567890
}
```

### 设备状态响应
```json
{
    "type": "status_response",
    "data": {
        "wifi_connected": true,
        "wifi_ssid": "MyWiFi",
        "ip_address": "192.168.1.100",
        "mac_address": "AA:BB:CC:DD:EE:FF",
        "signal_strength": -45,
        "bluetooth_name": "rpi-5b-24C8"
    },
    "timestamp": 1234567890
}
```

### WiFi配置请求
```json
{
    "type": "wifi_config",
    "data": {
        "ssid": "MyWiFi",
        "password": "password123",
        "security": "WPA2"
    },
    "timestamp": 1234567890
}
```

### WiFi配置响应
```json
{
    "type": "wifi_config_response",
    "data": {
        "success": true,
        "message": "WiFi连接成功",
        "ip_address": "192.168.1.100"
    },
    "timestamp": 1234567890
}
```

## 日志

日志文件位于 `/var/log/rpi-ble-network.log`

查看日志：
```bash
tail -f /var/log/rpi-ble-network.log
```

## 开发

### 目录结构
```
rpi-ble-network/
├── docs/                    # 文档
│   ├── REQUIREMENTS.md     # 需求文档
│   ├── DESIGN.md           # 设计文档
│   └── DEPENDENCIES.md     # 依赖说明
├── src/                    # 源代码
├── include/                # 头文件
├── scripts/                # 脚本
├── config/                 # 配置文件
├── systemd/                # systemd服务文件
├── bug/                    # Bug报告
├── Makefile               # 构建文件
└── README.md              # 说明文档
```

### Makefile 目标

```bash
make            # 编译项目（默认检查依赖）
make check-deps # 仅检查依赖
make deps       # 安装依赖（需要sudo）
make clean      # 清理编译产物
make install    # 安装程序（需要sudo）
make uninstall  # 卸载程序（需要sudo）
make test       # 运行测试
make help       # 显示帮助信息
```

### 代码规范
- 遵循Linux内核编码风格
- 使用4空格缩进
- 函数命名：模块名_动作_对象
- 变量命名：小写+下划线

## 故障排除

### 编译错误: glib.h 找不到

```bash
# 安装 GLib 开发库
sudo apt install libglib2.0-dev
```

### 蓝牙服务未启动

```bash
# 启动蓝牙服务
sudo systemctl start bluetooth

# 检查蓝牙状态
sudo systemctl status bluetooth
```

### 更多问题

请参考 [bug/report.md](bug/report.md) 查看已知问题和解决方案。

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request。

## 作者

RPi-BLE-Network Team