beshell-bt-app

# BeShell-BT Example App

This is an example project demonstrating the usage of BeShell-BT (Bluetooth BLE).

## Features

This example project demonstrates the following features:

### BLE Features

| Example File | Description |
|---------|------|
| `ble-scan.js` | Scan for nearby BLE devices, parse advertising data |
| `ble-central.js` | Act as BLE Central, connect to devices and discover services |
| `ble-peripheral.js` | Act as BLE Peripheral, provide GATT services |
| `ble-uart.js` | BLE UART (Nordic UART Service) implementation |
| `ble-heart-rate.js` | Heart Rate Service implementation |
| `ibeacon.js` | iBeacon broadcaster |
| `eddystone.js` | Eddystone broadcaster (UID/URL/TLM) |

## Project Structure

```
beshell-bt-app/
├── CMakeLists.txt          # Project CMake configuration
├── sdkconfig.defaults      # Default SDK configuration
├── README.md               # This file
├── main/
│   ├── main.cpp            # C++ entry file
│   ├── CMakeLists.txt      # main component CMake config
│   └── idf_component.yml   # Component dependencies
├── img/
│   ├── partitions-4MB.csv  # 4MB Flash partition table
│   ├── partitions-8MB.csv  # 8MB Flash partition table
│   └── partitions-16MB.csv # 16MB Flash partition table
└── js/
    ├── main.js             # JS entry file
    └── example/            # Example scripts directory
        ├── ble-scan.js
        ├── ble-central.js
        ├── ble-peripheral.js
        ├── ble-uart.js
        ├── ble-heart-rate.js
        ├── ibeacon.js
        └── eddystone.js
```

## Hardware Requirements

- ESP32 / ESP32-S3 / ESP32-C3 or other Bluetooth-capable chips
- At least 4MB Flash
- USB-to-Serial for flashing and debugging

## Quick Start

### 1. Build the Project

```bash
idf.py build
```

### 2. Flash the Firmware

```bash
idf.py flash
```

### 3. View Serial Output

```bash
idf.py monitor
```

### 4. Run Examples

In the serial terminal, enter the following command to run an example:

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

## Example Details

### BLE Scan

Scan for nearby BLE devices and parse advertising data:

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

bt.setScanParam({
    scan_type: 0,           // 0: passive scan, 1: active scan
    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

Connect to BLE devices and operate GATT services:

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

bt.central.init()

// Connect to device
let peer = await bt.central.connect("AA:BB:CC:DD:EE:FF", 10000)

// Discover services
await peer.search()

// Read characteristic
let data = await peer['2a37'].read()

// Subscribe to notifications
await peer['2a37'].subscribe()
peer['2a37'].on('notify', (data) => {
    console.log("Received:", data)
})
```

### BLE Peripheral

Create GATT services and advertise:

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

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

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

// Set characteristic value
service.chars['2a37'].setValue(new Uint8Array([72]))

// Send notification
service.chars['2a37'].notify(new Uint8Array([75]))

bt.startAdv()
```

### iBeacon

Create an iBeacon broadcaster:

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

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

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

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

### BLE UART

Implement Nordic UART Service for serial communication:

```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"] }
    ]
})

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

## Dependencies

- [beshell](https://github.com/become-cool/beshell) - BeShell core framework
- [beshell-bt](https://github.com/become-cool/beshell-bt) - Bluetooth BLE component

## License

LGPL

## Links

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