witmotion-react-native/README.md

React Native SDK for WitMotion BLE IMU sensors (WT901, WT901BLECL, etc.)

# 📦 WitMotion React Native BLE SDK

[![npm version](https://img.shields.io/npm/v/witmotion-react-native.svg)](https://www.npmjs.com/package/witmotion-react-native)
[![npm downloads](https://img.shields.io/npm/dm/witmotion-react-native.svg)](https://www.npmjs.com/package/witmotion-react-native)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

React Native SDK for connecting to **WitMotion BLE IMU sensors** (e.g. WT901, WT901BLECL) using [`react-native-ble-plx`](https://github.com/dotintent/react-native-ble-plx).  
Implements the **official WIT Standard Protocol** in TypeScript/JavaScript.
---

## ✨ Features

- 🔎 Scan for nearby WitMotion BLE devices  
- 🔗 Connect and subscribe to sensor notifications  
- 📡 Parse WIT Standard packets (`0x5x`, `0x61`, `0x71`)  
- 📊 Provides accelerometer, gyroscope, angle, magnetometer, quaternion, temperature  
- 📝 Exposes WitMotion commands (reset yaw, calibration, save, set output rate)  

---

## 📥 Installation

```bash
# Install SDK and dependencies
npm install witmotion-react-native
npm install react-native-ble-plx base64-js
```

---

## 📂 Project structure

```
src/
 ├── witBle.ts      # BLE connection, scanning, command sending
 ├── witParser.ts   # WIT protocol packet parser
 └── index.ts       # entry point exports
```

---

## 🚀 Quick Start

### 1. Scan for devices

```ts
import { scanForDevices } from "witmotion-react-native";

await scanForDevices((device) => {
  console.log("Found:", device.id, device.name, device.rssi);
}, 5000);
```

---

### 2. Connect to a device

```ts
import { connectById } from "witmotion-react-native";

const { device, subs, send } = await connectById("DEVICE_ID", (data) => {
  if (data.acc)   console.log("Acceleration:", data.acc);
  if (data.gyro)  console.log("Gyroscope:", data.gyro);
  if (data.angle) console.log("Angles:", data.angle);
  if (data.mag)   console.log("Magnetometer:", data.mag);
  if (data.quat)  console.log("Quaternion:", data.quat);
  if (data.temp !== undefined) console.log("Temperature:", data.temp);
});
```

---

### 3. Send commands

```ts
import { WitCmd } from "witmotion-react-native";

// Reset yaw angle
await send?.(WitCmd.resetYaw);

// Start magnetometer calibration
await send?.(WitCmd.startMagCalib);

// Save settings
await send?.(WitCmd.save);

// Set output rate to 50 Hz
await send?.(WitCmd.setRateHz(50));
```

---

## 📡 Protocol Support

| Packet | Bytes | Description |
|--------|-------|-------------|
| `0x51` | 11    | Accelerometer (X,Y,Z) |
| `0x52` | 11    | Gyroscope (X,Y,Z) |
| `0x53` | 11    | Angles (Roll, Pitch, Yaw) |
| `0x54` | 11    | Magnetometer (X,Y,Z) |
| `0x59` | 11    | Quaternion (W,X,Y,Z) |
| `0x61` | 20    | Combined BLE packet (ACC+GYRO+ANGLE) |
| `0x71` | 20/22 | Register response (Quaternion, Magnetometer, Temperature, etc.) |

---

## 🛠 Commands (WitCmd)

| Command         | Bytes                           | Description |
|-----------------|---------------------------------|-------------|
| `startMagCalib` | `[0xFF, 0xAA, 0x01, 0x07, 0x00]` | Start magnetometer calibration |
| `save`          | `[0xFF, 0xAA, 0x00, 0x00, 0x00]` | Save settings |
| `resetYaw`      | `[0xFF, 0xAA, 0x01, 0x04, 0x00]` | Reset yaw angle |
| `setRateHz(hz)` | `[0xFF, 0xAA, 0x03, L, H]`       | Set output rate (Hz) |

---

## ⚡ Requirements

- React Native ≥ 0.70  
- Android 6.0+ / iOS 12+  
- Permissions:
  - Android 12+: `BLUETOOTH_SCAN`, `BLUETOOTH_CONNECT`
  - Android <12: `ACCESS_FINE_LOCATION`

---

## 📖 References

- [WitMotion Official SDK](https://www.wit-motion.com/SDK.html)  
- [WT901BLECL Datasheet (PDF)](https://cdn.robotshop.com/rbm/f83835f4-5e29-4ee0-9cc2-e49300031503/b/bf5c1f59-3b36-40a4-a5f0-e5a0eea52565/a8cd29da_wt901blecl-datasheet.pdf)  
- [react-native-ble-plx](https://github.com/dotintent/react-native-ble-plx)  

---

## 📜 License

MIT License © 2025 — Massimiliano Wosz