📦 WitMotion React Native BLE SDK

React Native SDK for connecting to WitMotion BLE IMU sensors (e.g. WT901, WT901BLECL) using 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

# 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

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

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

---

2. Connect to a device

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

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
• WT901BLECL Datasheet (PDF)
• react-native-ble-plx

---

📜 License

MIT License © 2025 — Massimiliano Wosz