> For the complete documentation index, see [llms.txt](https://geotag.gitbook.io/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://geotag.gitbook.io/api/geotag-bluetooth-hardware-interface-documentation.md).

# GeoTag Bluetooth Hardware Interface Documentation

### 1. Overview

* **Protocol**: Bluetooth Low Energy (BLE)
* **Transport**: Uses `TRANSPORT_LE` (Low Energy)

***

### 2. GATT Services and Characteristics

#### 2.1 Custom Service

| Item             | Value                                  |
| ---------------- | -------------------------------------- |
| **Service UUID** | `0000FFE0-0000-1000-8000-00805F9B34FB` |
| **Short UUID**   | 0xFFE0                                 |

#### 2.2 Characteristic List

| Characteristic | Short UUID | Full UUID                              | Properties  | Description               |
| -------------- | ---------- | -------------------------------------- | ----------- | ------------------------- |
| Buzzer Control | 0xFFE1     | `0000FFE1-0000-1000-8000-00805F9B34FB` | Read, Write | Buzzer on/off control     |
| Battery Data   | 0xFFE2     | `0000FFE2-0000-1000-8000-00805F9B34FB` | Read        | Battery level and voltage |

***

### 3. Buzzer Control Characteristic (0xFFE1)

#### 3.1 Properties

* **Readable**: Yes
* **Writable**: Yes
* **Write Without Response Supported**: Yes

#### 3.2 Command Format

Single-byte write:

| Value (Hex) | Value (Dec) | Meaning         |
| ----------- | ----------- | --------------- |
| 0x01        | 1           | Turn on buzzer  |
| 0x00        | 0           | Turn off buzzer |

#### 3.3 Examples

```
Turn on buzzer: Write [0x01]  
Turn off buzzer: Write [0x00]
```

***

### 4. Battery Data Characteristic (0xFFE2)

#### 4.1 Properties

* **Readable**: Yes
* **Writable**: No (Read-only)

#### 4.2 Data Format

Fixed **5 bytes**, big-endian:

| Byte Index | Content                   | Type  | Description                 |
| ---------- | ------------------------- | ----- | --------------------------- |
| \[0]       | Raw ADC High Byte         | uint8 | High 8 bits of rawAdcValue  |
| \[1]       | Raw ADC Low Byte          | uint8 | Low 8 bits of rawAdcValue   |
| \[2]       | Battery Voltage High Byte | uint8 | High 8 bits of voltage (mV) |
| \[3]       | Battery Voltage Low Byte  | uint8 | Low 8 bits of voltage (mV)  |
| \[4]       | Battery Percentage        | uint8 | 0–100                       |

#### 4.3 Parsing Example

```
// Raw ADC (16-bit, big-endian)
rawAdc = (data[0] << 8) | data[1];

// Battery voltage (mV, 16-bit, big-endian)
batteryVoltage_mV = (data[2] << 8) | data[3];

// Battery percentage
batteryPercent = data[4];  // 0–100
```

***

### 5. Connection and Usage Flow

```
1. BLE scan → Discover device
2. connectGatt(TRANSPORT_LE) → Establish connection
3. discoverServices() → Discover services
4. After onServicesDiscovered succeeds:
   - Read 0xFFE2 to obtain battery status
   - Write to 0xFFE1 to control buzzer
5. Disconnect: gatt.close()
```

***

### 6. Reference: UUID Constant Definitions

```
// Service
CUSTOM_SERVICE_UUID = "0000ffe0-0000-1000-8000-00805f9b34fb"

// Buzzer
BUZZER_CHARACTERISTIC_UUID = "0000ffe1-0000-1000-8000-00805f9b34fb"

// Battery
BATTERY_CHARACTERISTIC_UUID = "0000ffe2-0000-1000-8000-00805f9b34fb"
```