📦 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