beshell-bt-app

# BeShell-BT Example App

这是一个演示 BeShell-BT (蓝牙 BLE) 用法的示例工程。

## 功能特性

本示例工程演示了以下功能：

### BLE 功能

| 示例文件 | 说明 |
|---------|------|
| `ble-scan.js` | 扫描周围的 BLE 设备，解析广播数据 |
| `ble-central.js` | 作为 BLE 主机连接设备，发现服务和特征 |
| `ble-peripheral.js` | 作为 BLE 从机，提供 GATT 服务 |
| `ble-uart.js` | BLE UART (Nordic UART Service) 实现 |
| `ble-heart-rate.js` | 心率服务 (Heart Rate Service) 实现 |
| `ibeacon.js` | iBeacon 广播器 |
| `eddystone.js` | Eddystone 广播器 (UID/URL/TLM) |

## 项目结构

```
beshell-bt-app/
├── CMakeLists.txt          # 项目 CMake 配置
├── sdkconfig.defaults      # 默认 SDK 配置
├── README.md               # 本文件
├── main/
│   ├── main.cpp            # C++ 入口文件
│   ├── CMakeLists.txt      # main 组件 CMake 配置
│   └── idf_component.yml   # 组件依赖配置
├── img/
│   ├── partitions-4MB.csv  # 4MB Flash 分区表
│   ├── partitions-8MB.csv  # 8MB Flash 分区表
│   └── partitions-16MB.csv # 16MB Flash 分区表
└── js/
    ├── main.js             # JS 入口文件
    └── example/            # 示例脚本目录
        ├── ble-scan.js
        ├── ble-central.js
        ├── ble-peripheral.js
        ├── ble-uart.js
        ├── ble-heart-rate.js
        ├── ibeacon.js
        └── eddystone.js
```

## 硬件要求

- ESP32 / ESP32-S3 / ESP32-C3 等支持蓝牙的芯片
- 至少 4MB Flash
- USB 转串口用于烧录和调试

## 快速开始

### 1. 构建项目

```bash
idf.py build
```

### 2. 烧录固件

```bash
idf.py flash
```

### 3. 查看串口输出

```bash
idf.py monitor
```

### 4. 运行示例

在串口终端中，输入以下命令运行示例：

```
run /example/ble-scan.js
```

## 示例详解

### BLE 扫描

扫描周围的 BLE 设备并解析广播数据：

```javascript
import * as bt from "bt"

bt.setScanParam({
    scan_type: 0,           // 0: 被动扫描, 1: 主动扫描
    scan_interval: 0x50,
    scan_window: 0x40
})

bt.on('scan-res', (device) => {
    let adv = bt.parseAdv(device.adv_raw)
    console.log(`Device: ${device.addr}, RSSI: ${device.rssi}`)
})

bt.startScan()
```

### BLE Central (主机)

连接到 BLE 设备并操作 GATT 服务：

```javascript
import * as bt from "bt"

bt.central.init()

// 连接设备
let peer = await bt.central.connect("AA:BB:CC:DD:EE:FF", 10000)

// 发现服务
await peer.search()

// 读取特征值
let data = await peer['2a37'].read()

// 订阅通知
await peer['2a37'].subscribe()
peer['2a37'].on('notify', (data) => {
    console.log("Received:", data)
})
```

### BLE Peripheral (从机)

创建 GATT 服务并广播：

```javascript
import * as bt from "bt"

bt.peripheral.init()
bt.setAdvName("MyDevice")

// 添加服务
let service = bt.peripheral.addService({
    uuid: "180d",
    primary: true,
    chars: [
        {
            uuid: "2a37",
            props: ["read", "notify"]
        }
    ]
})

// 设置特征值
service.chars['2a37'].setValue(new Uint8Array([72]))

// 发送通知
service.chars['2a37'].notify(new Uint8Array([75]))

bt.startAdv()
```

### iBeacon

创建 iBeacon 广播器：

```javascript
import * as bt from "bt"

bt.peripheral.init()
bt.setAdvName("iBeacon")

// 设置 iBeacon 数据
let beaconData = createIBeaconData({
    uuid: "E2C56DB5-DFFB-48D2-B060-D0F5A71096E0",
    major: 1,
    minor: 1,
    txPower: -59
})

bt.setAdvData(beaconData.buffer)
bt.startAdv()
```

### BLE UART

实现 Nordic UART Service 进行串口通信：

```javascript
import * as bt from "bt"

bt.peripheral.init()

let nusService = bt.peripheral.addService({
    uuid: "6E400001-B5A3-F393-E0A9-E50E24DCCA9E",
    chars: [
        { uuid: "6E400002-B5A3-F393-E0A9-E50E24DCCA9E", props: ["write"] },
        { uuid: "6E400003-B5A3-F393-E0A9-E50E24DCCA9E", props: ["notify"] }
    ]
})

// 接收数据
nusService.chars['6E400002'].on('write', (data) => {
    console.log("Received:", new TextDecoder().decode(data))
})
```

## 依赖组件

- [beshell](https://github.com/become-cool/beshell) - BeShell 核心框架
- [beshell-bt](https://github.com/become-cool/beshell-bt) - 蓝牙 BLE 组件

## 许可证

LGPL

## 相关链接

- [BeShell 文档](https://beshell.become.cool)
- [ESP-IDF 文档](https://docs.espressif.com/projects/esp-idf/)
- [Bluetooth GATT 规范](https://www.bluetooth.com/specifications/gatt/)