@bota-dev/react-native-sdk 0.0.2

package/src/ble/constants.ts

@@ -0,0 +1,158 @@
+/**
+ * BLE Service and Characteristic UUIDs for Bota devices
+ * Based on Device-App Protocol specification
+ */
+
+// Standard Bluetooth SIG Services
+export const SERVICE_DEVICE_INFO = '180A';
+export const SERVICE_BATTERY = '180F';
+export const SERVICE_NORDIC_DFU = 'FE59';
+
+// Bota Custom Services
+export const SERVICE_BOTA_AUDIO = 'B07A0001-0000-1000-8000-00805F9B34FB';
+export const SERVICE_BOTA_CONTROL = 'B07A0002-0000-1000-8000-00805F9B34FB';
+export const SERVICE_BOTA_PROVISIONING = 'B07A0003-0000-1000-8000-00805F9B34FB';
+export const SERVICE_BOTA_STORAGE = 'B07A0004-0000-1000-8000-00805F9B34FB';
+
+// Device Information Service Characteristics (0x180A)
+export const CHAR_MANUFACTURER_NAME = '2A29';
+export const CHAR_MODEL_NUMBER = '2A24';
+export const CHAR_SERIAL_NUMBER = '2A25';
+export const CHAR_HARDWARE_REVISION = '2A27';
+export const CHAR_FIRMWARE_REVISION = '2A26';
+
+// Battery Service Characteristics (0x180F)
+export const CHAR_BATTERY_LEVEL = '2A19';
+
+// Bota Audio Service Characteristics (B07A0001)
+export const CHAR_AUDIO_DATA = 'B07A0001-0001-1000-8000-00805F9B34FB';
+export const CHAR_AUDIO_CODEC = 'B07A0001-0002-1000-8000-00805F9B34FB';
+export const CHAR_AUDIO_CONTROL = 'B07A0001-0003-1000-8000-00805F9B34FB';
+
+// Bota Control Service Characteristics (B07A0002)
+export const CHAR_DEVICE_STATUS = 'B07A0002-0001-1000-8000-00805F9B34FB';
+export const CHAR_RECORDING_CONTROL = 'B07A0002-0002-1000-8000-00805F9B34FB';
+export const CHAR_RECORDING_STATUS = 'B07A0002-0003-1000-8000-00805F9B34FB';
+export const CHAR_TIME_SYNC = 'B07A0002-0004-1000-8000-00805F9B34FB';
+export const CHAR_DEVICE_COMMAND = 'B07A0002-0005-1000-8000-00805F9B34FB';
+
+// Bota Provisioning Service Characteristics (B07A0003)
+export const CHAR_PAIRING_STATE = 'B07A0003-0001-1000-8000-00805F9B34FB';
+export const CHAR_DEVICE_TOKEN = 'B07A0003-0002-1000-8000-00805F9B34FB';
+export const CHAR_API_ENDPOINT = 'B07A0003-0003-1000-8000-00805F9B34FB';
+export const CHAR_WIFI_CONFIG = 'B07A0003-0004-1000-8000-00805F9B34FB';
+export const CHAR_PROVISIONING_RESULT = 'B07A0003-0005-1000-8000-00805F9B34FB';
+
+// Bota Storage Service Characteristics (B07A0004)
+export const CHAR_STORAGE_INFO = 'B07A0004-0001-1000-8000-00805F9B34FB';
+export const CHAR_RECORDING_LIST = 'B07A0004-0002-1000-8000-00805F9B34FB';
+export const CHAR_RECORDING_TRANSFER = 'B07A0004-0003-1000-8000-00805F9B34FB';
+export const CHAR_TRANSFER_CONTROL = 'B07A0004-0004-1000-8000-00805F9B34FB';
+export const CHAR_TRANSFER_STATUS = 'B07A0004-0005-1000-8000-00805F9B34FB';
+
+// Device name prefixes for scanning
+export const DEVICE_NAME_PREFIX = 'Bota-';
+export const DEVICE_NAME_PREFIX_PIN = 'Bota-Pin-';
+export const DEVICE_NAME_PREFIX_PIN_4G = 'Bota-Pin4G-';
+export const DEVICE_NAME_PREFIX_NOTE = 'Bota-Note-';
+
+// Manufacturer data byte positions
+export const MFG_DATA_DEVICE_TYPE = 0;
+export const MFG_DATA_FW_MAJOR = 1;
+export const MFG_DATA_FW_MINOR = 2;
+export const MFG_DATA_PAIRING_STATE = 3;
+export const MFG_DATA_BATTERY = 4;
+
+// Device type values in manufacturer data
+export const DEVICE_TYPE_PIN = 0x01;
+export const DEVICE_TYPE_PIN_4G = 0x02;
+export const DEVICE_TYPE_NOTE = 0x03;
+
+// Pairing state values
+export const PAIRING_STATE_UNPAIRED = 0x00;
+export const PAIRING_STATE_PAIRING = 0x01;
+export const PAIRING_STATE_PAIRED = 0x02;
+export const PAIRING_STATE_ERROR = 0x03;
+
+// Provisioning result codes
+export const PROVISIONING_SUCCESS = 0x00;
+export const PROVISIONING_INVALID_TOKEN = 0x01;
+export const PROVISIONING_STORAGE_ERROR = 0x02;
+export const PROVISIONING_CHUNK_ERROR = 0x03;
+
+// API endpoint values
+export const API_ENDPOINT_PRODUCTION = 0x00;
+export const API_ENDPOINT_SANDBOX = 0x01;
+
+// Transfer control commands
+export const TRANSFER_CMD_LIST = 0x01;
+export const TRANSFER_CMD_START = 0x02;
+export const TRANSFER_CMD_CONFIRM_SYNC = 0x07;
+
+// Transfer packet types (Device → App)
+export const PACKET_TYPE_DATA = 0x01;
+export const PACKET_TYPE_EOF = 0x02;
+export const PACKET_TYPE_ERROR = 0xff;
+
+// ACK types (App → Device)
+export const ACK_TYPE_ACK = 0x10;
+export const ACK_TYPE_NACK = 0x11;
+export const ACK_TYPE_ABORT = 0x12;
+
+// Device command values
+export const DEVICE_CMD_ENTER_DFU = 0x03;
+
+// Device state values (from status)
+export const DEVICE_STATE_IDLE = 0x00;
+export const DEVICE_STATE_RECORDING = 0x01;
+export const DEVICE_STATE_SYNCING = 0x02;
+export const DEVICE_STATE_UPLOADING = 0x03;
+export const DEVICE_STATE_CHARGING = 0x04;
+export const DEVICE_STATE_LOW_BATTERY = 0x05;
+export const DEVICE_STATE_STORAGE_FULL = 0x06;
+export const DEVICE_STATE_ERROR = 0xff;
+
+// Device status flags (bitmask)
+export const FLAG_CHARGING = 1 << 0;
+export const FLAG_USB_CONNECTED = 1 << 1;
+export const FLAG_LOW_BATTERY = 1 << 2;
+export const FLAG_CRITICAL_BATTERY = 1 << 3;
+export const FLAG_STORAGE_WARNING = 1 << 4;
+export const FLAG_STORAGE_FULL = 1 << 5;
+export const FLAG_CELLULAR_AVAILABLE = 1 << 6;
+export const FLAG_CELLULAR_ROAMING = 1 << 7;
+export const FLAG_WIFI_CONNECTED = 1 << 8;
+export const FLAG_RECORDING_ACTIVE = 1 << 9;
+export const FLAG_SYNC_REQUIRED = 1 << 10;
+export const FLAG_UPDATE_AVAILABLE = 1 << 11;
+
+// Audio codec values
+export const CODEC_PCM_16K = 0x00;
+export const CODEC_PCM_8K = 0x01;
+export const CODEC_OPUS_16K = 0x10;
+export const CODEC_OPUS_8K = 0x11;
+
+// BLE error codes
+export const BLE_ERROR_SUCCESS = 0x00;
+export const BLE_ERROR_INVALID_COMMAND = 0x01;
+export const BLE_ERROR_INVALID_STATE = 0x02;
+export const BLE_ERROR_INVALID_PARAMETER = 0x03;
+export const BLE_ERROR_STORAGE_FULL = 0x10;
+export const BLE_ERROR_RECORDING_NOT_FOUND = 0x11;
+export const BLE_ERROR_TRANSFER_FAILED = 0x12;
+export const BLE_ERROR_TOKEN_INVALID = 0x20;
+export const BLE_ERROR_TOKEN_EXPIRED = 0x21;
+export const BLE_ERROR_NETWORK_ERROR = 0x30;
+export const BLE_ERROR_UPLOAD_FAILED = 0x31;
+export const BLE_ERROR_UNKNOWN = 0xff;
+
+// Timeouts (ms)
+export const SCAN_TIMEOUT = 30000;
+export const CONNECTION_TIMEOUT = 30000;
+export const OPERATION_TIMEOUT = 10000;
+export const TRANSFER_PACKET_TIMEOUT = 2000;
+
+// Transfer settings
+export const TRANSFER_WINDOW_SIZE = 4;
+export const DEFAULT_MTU = 23;
+export const MAX_MTU = 512;

package/src/ble/index.ts

@@ -0,0 +1,7 @@
+/**
+ * BLE module exports
+ */
+
+export * from './constants';
+export * from './parsers';
+export { BleManager, getBleManager, resetBleManager } from './BleManager';

package/src/ble/parsers.ts

@@ -0,0 +1,395 @@
+/**
+ * BLE data parsers for Bota device protocol
+ */
+
+import { Buffer } from 'buffer';
+
+import type {
+  DeviceType,
+  PairingState,
+  DeviceState,
+  DeviceStatus,
+  DeviceFlags,
+  StorageInfo,
+} from '../models/Device';
+import type { DeviceRecording, AudioCodec, TransferPacket } from '../models/Recording';
+import {
+  DEVICE_TYPE_PIN,
+  DEVICE_TYPE_PIN_4G,
+  DEVICE_TYPE_NOTE,
+  PAIRING_STATE_UNPAIRED,
+  PAIRING_STATE_PAIRING,
+  PAIRING_STATE_PAIRED,
+  PAIRING_STATE_ERROR,
+  DEVICE_STATE_IDLE,
+  DEVICE_STATE_RECORDING,
+  DEVICE_STATE_SYNCING,
+  DEVICE_STATE_UPLOADING,
+  DEVICE_STATE_CHARGING,
+  DEVICE_STATE_LOW_BATTERY,
+  DEVICE_STATE_STORAGE_FULL,
+  DEVICE_STATE_ERROR,
+  FLAG_CHARGING,
+  FLAG_USB_CONNECTED,
+  FLAG_LOW_BATTERY,
+  FLAG_CRITICAL_BATTERY,
+  FLAG_STORAGE_WARNING,
+  FLAG_STORAGE_FULL,
+  FLAG_CELLULAR_AVAILABLE,
+  FLAG_CELLULAR_ROAMING,
+  FLAG_WIFI_CONNECTED,
+  FLAG_RECORDING_ACTIVE,
+  FLAG_SYNC_REQUIRED,
+  FLAG_UPDATE_AVAILABLE,
+  CODEC_PCM_16K,
+  CODEC_PCM_8K,
+  CODEC_OPUS_16K,
+  CODEC_OPUS_8K,
+  PACKET_TYPE_DATA,
+  PACKET_TYPE_EOF,
+  PACKET_TYPE_ERROR,
+} from './constants';
+
+/**
+ * Parse device type from manufacturer data byte
+ */
+export function parseDeviceType(byte: number): DeviceType {
+  switch (byte) {
+    case DEVICE_TYPE_PIN:
+      return 'bota_pin';
+    case DEVICE_TYPE_PIN_4G:
+      return 'bota_pin_4g';
+    case DEVICE_TYPE_NOTE:
+      return 'bota_note';
+    default:
+      return 'bota_pin';
+  }
+}
+
+/**
+ * Parse pairing state from manufacturer data byte
+ */
+export function parsePairingState(byte: number): PairingState {
+  switch (byte) {
+    case PAIRING_STATE_UNPAIRED:
+      return 'unpaired';
+    case PAIRING_STATE_PAIRING:
+      return 'pairing';
+    case PAIRING_STATE_PAIRED:
+      return 'paired';
+    case PAIRING_STATE_ERROR:
+      return 'error';
+    default:
+      return 'unpaired';
+  }
+}
+
+/**
+ * Parse firmware version from major/minor bytes
+ */
+export function parseFirmwareVersion(major: number, minor: number): string {
+  return `${major}.${minor}.0`;
+}
+
+/**
+ * Parse device state from status byte
+ */
+export function parseDeviceState(byte: number): DeviceState {
+  switch (byte) {
+    case DEVICE_STATE_IDLE:
+      return 'idle';
+    case DEVICE_STATE_RECORDING:
+      return 'recording';
+    case DEVICE_STATE_SYNCING:
+      return 'syncing';
+    case DEVICE_STATE_UPLOADING:
+      return 'uploading';
+    case DEVICE_STATE_CHARGING:
+      return 'charging';
+    case DEVICE_STATE_LOW_BATTERY:
+      return 'lowBattery';
+    case DEVICE_STATE_STORAGE_FULL:
+      return 'storageFull';
+    case DEVICE_STATE_ERROR:
+      return 'error';
+    default:
+      return 'idle';
+  }
+}
+
+/**
+ * Parse device flags from 16-bit value
+ */
+export function parseDeviceFlags(value: number): DeviceFlags {
+  return {
+    charging: (value & FLAG_CHARGING) !== 0,
+    usbConnected: (value & FLAG_USB_CONNECTED) !== 0,
+    lowBattery: (value & FLAG_LOW_BATTERY) !== 0,
+    criticalBattery: (value & FLAG_CRITICAL_BATTERY) !== 0,
+    storageWarning: (value & FLAG_STORAGE_WARNING) !== 0,
+    storageFull: (value & FLAG_STORAGE_FULL) !== 0,
+    cellularAvailable: (value & FLAG_CELLULAR_AVAILABLE) !== 0,
+    cellularRoaming: (value & FLAG_CELLULAR_ROAMING) !== 0,
+    wifiConnected: (value & FLAG_WIFI_CONNECTED) !== 0,
+    recordingActive: (value & FLAG_RECORDING_ACTIVE) !== 0,
+    syncRequired: (value & FLAG_SYNC_REQUIRED) !== 0,
+    updateAvailable: (value & FLAG_UPDATE_AVAILABLE) !== 0,
+  };
+}
+
+/**
+ * Parse device status from 16-byte characteristic value
+ *
+ * Format:
+ * Bytes 0-3:   Timestamp (Unix seconds)
+ * Byte 4:     Battery % (0-100)
+ * Byte 5:     State
+ * Byte 6:     Storage % (0-100)
+ * Byte 7:     Signal (0-5)
+ * Bytes 8-9:  Pending recordings count
+ * Bytes 10-13: Last sync time (Unix seconds)
+ * Bytes 14-15: Flags
+ */
+export function parseDeviceStatus(data: Buffer): DeviceStatus {
+  if (data.length < 16) {
+    throw new Error(`Invalid status data length: ${data.length}`);
+  }
+
+  const timestamp = data.readUInt32LE(0);
+  const batteryLevel = data.readUInt8(4);
+  const state = parseDeviceState(data.readUInt8(5));
+  const storageUsedPercent = data.readUInt8(6);
+  const signalStrength = data.readUInt8(7);
+  const pendingRecordings = data.readUInt16LE(8);
+  const lastSyncTimestamp = data.readUInt32LE(10);
+  const flagsValue = data.readUInt16LE(14);
+  const flags = parseDeviceFlags(flagsValue);
+
+  return {
+    batteryLevel,
+    storageUsedPercent,
+    state,
+    pendingRecordings,
+    lastSyncAt: lastSyncTimestamp > 0 ? new Date(lastSyncTimestamp * 1000) : null,
+    signalStrength,
+    flags,
+    timestamp,
+  };
+}
+
+/**
+ * Parse storage info from 16-byte characteristic value
+ *
+ * Format:
+ * Bytes 0-3:   Total storage (KB)
+ * Bytes 4-7:   Used storage (KB)
+ * Bytes 8-9:   Total recording count
+ * Bytes 10-11: Pending sync count
+ * Bytes 12-15: Reserved
+ */
+export function parseStorageInfo(data: Buffer): StorageInfo {
+  if (data.length < 12) {
+    throw new Error(`Invalid storage info length: ${data.length}`);
+  }
+
+  return {
+    totalKb: data.readUInt32LE(0),
+    usedKb: data.readUInt32LE(4),
+    totalRecordings: data.readUInt16LE(8),
+    pendingSyncCount: data.readUInt16LE(10),
+  };
+}
+
+/**
+ * Parse audio codec from byte value
+ */
+export function parseAudioCodec(byte: number): AudioCodec {
+  switch (byte) {
+    case CODEC_PCM_16K:
+      return 'pcm_16k';
+    case CODEC_PCM_8K:
+      return 'pcm_8k';
+    case CODEC_OPUS_16K:
+      return 'opus_16k';
+    case CODEC_OPUS_8K:
+      return 'opus_8k';
+    default:
+      return 'opus_16k';
+  }
+}
+
+/**
+ * Parse recording list from notification data
+ * Each recording entry is typically 24 bytes:
+ * - UUID: 16 bytes
+ * - Timestamp: 4 bytes (Unix seconds)
+ * - Duration: 2 bytes (seconds)
+ * - Size: 2 bytes (KB, or needs scaling)
+ */
+export function parseRecordingList(data: Buffer): DeviceRecording[] {
+  const recordings: DeviceRecording[] = [];
+  const entrySize = 24;
+
+  // First byte might be count
+  let offset = 0;
+  if (data.length > 0 && data.length % entrySize !== 0) {
+    // Skip count byte
+    offset = 1;
+  }
+
+  while (offset + entrySize <= data.length) {
+    const uuid = formatUuid(data.slice(offset, offset + 16));
+    const timestamp = data.readUInt32LE(offset + 16);
+    const durationSeconds = data.readUInt16LE(offset + 20);
+    const sizeKb = data.readUInt16LE(offset + 22);
+
+    recordings.push({
+      uuid,
+      startedAt: new Date(timestamp * 1000),
+      durationMs: durationSeconds * 1000,
+      fileSizeBytes: sizeKb * 1024,
+      codec: 'opus_16k', // Default, actual codec read separately
+    });
+
+    offset += entrySize;
+  }
+
+  return recordings;
+}
+
+/**
+ * Format 16-byte UUID buffer to string
+ */
+function formatUuid(data: Buffer): string {
+  const hex = data.toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+/**
+ * Parse transfer packet from device
+ *
+ * Format:
+ * Byte 0:     Packet type (0x01=data, 0x02=EOF, 0xFF=error)
+ * Bytes 1-2:  Sequence number
+ * Bytes 3-4:  Chunk size (data) or CRC32 start (EOF)
+ * Bytes 5+:   Audio data (data) or CRC32 remainder (EOF)
+ */
+export function parseTransferPacket(data: Buffer): TransferPacket {
+  if (data.length < 3) {
+    throw new Error(`Invalid transfer packet length: ${data.length}`);
+  }
+
+  const type = data.readUInt8(0);
+  const sequenceNumber = data.readUInt16LE(1);
+
+  switch (type) {
+    case PACKET_TYPE_DATA:
+      return {
+        type: 'data',
+        sequenceNumber,
+        data: data.slice(5), // Skip header
+      };
+
+    case PACKET_TYPE_EOF:
+      return {
+        type: 'eof',
+        sequenceNumber,
+        checksum: data.readUInt32LE(3),
+      };
+
+    case PACKET_TYPE_ERROR:
+      return {
+        type: 'error',
+        sequenceNumber,
+        errorCode: data.length > 3 ? data.readUInt8(3) : 0xff,
+      };
+
+    default:
+      throw new Error(`Unknown packet type: ${type}`);
+  }
+}
+
+/**
+ * Create time sync data buffer
+ *
+ * Format:
+ * Bytes 0-3:  Unix timestamp (seconds)
+ * Bytes 4-5:  Milliseconds (0-999)
+ * Bytes 6-7:  Timezone offset (signed, minutes from UTC)
+ */
+export function createTimeSyncData(date: Date = new Date()): Buffer {
+  const buffer = Buffer.alloc(8);
+  const unixSeconds = Math.floor(date.getTime() / 1000);
+  const milliseconds = date.getMilliseconds();
+  const timezoneOffset = -date.getTimezoneOffset(); // getTimezoneOffset returns opposite sign
+
+  buffer.writeUInt32LE(unixSeconds, 0);
+  buffer.writeUInt16LE(milliseconds, 4);
+  buffer.writeInt16LE(timezoneOffset, 6);
+
+  return buffer;
+}
+
+/**
+ * Create ACK packet for transfer
+ *
+ * Format:
+ * Byte 0:    ACK type (0x10=ACK, 0x11=NACK, 0x12=Abort)
+ * Bytes 1-2: Sequence number
+ */
+export function createAckPacket(
+  ackType: 'ack' | 'nack' | 'abort',
+  sequenceNumber: number
+): Buffer {
+  const buffer = Buffer.alloc(3);
+
+  switch (ackType) {
+    case 'ack':
+      buffer.writeUInt8(0x10, 0);
+      break;
+    case 'nack':
+      buffer.writeUInt8(0x11, 0);
+      break;
+    case 'abort':
+      buffer.writeUInt8(0x12, 0);
+      break;
+  }
+
+  buffer.writeUInt16LE(sequenceNumber, 1);
+  return buffer;
+}
+
+/**
+ * Create transfer control command
+ *
+ * Format:
+ * Byte 0: Command (0x01=list, 0x02=start, 0x07=confirm)
+ * Bytes 1+: Recording UUID (for start/confirm)
+ */
+export function createTransferCommand(
+  command: 'list' | 'start' | 'confirm',
+  recordingUuid?: string
+): Buffer {
+  let cmdByte: number;
+  switch (command) {
+    case 'list':
+      cmdByte = 0x01;
+      break;
+    case 'start':
+      cmdByte = 0x02;
+      break;
+    case 'confirm':
+      cmdByte = 0x07;
+      break;
+  }
+
+  if (recordingUuid) {
+    const uuidBuffer = Buffer.from(recordingUuid.replace(/-/g, ''), 'hex');
+    const buffer = Buffer.alloc(1 + uuidBuffer.length);
+    buffer.writeUInt8(cmdByte, 0);
+    uuidBuffer.copy(buffer, 1);
+    return buffer;
+  }
+
+  return Buffer.from([cmdByte]);
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+/**
+ * Bota React Native SDK
+ *
+ * SDK for communicating with Bota wearable devices via BLE.
+ *
+ * @packageDocumentation
+ */
+
+// Main client
+export { BotaClient } from './BotaClient';
+export type { BotaConfig, SdkState, BluetoothState } from './BotaClient';
+
+// Managers
+export { DeviceManager, RecordingManager, OTAManager } from './managers';
+export type { UploadInfoProvider, FirmwareInfo, OtaStage, OtaProgress } from './managers';
+
+// Models - Device
+export type {
+  DeviceType,
+  PairingState,
+  ConnectionState,
+  DeviceState,
+  DeviceFlags,
+  DiscoveredDevice,
+  ConnectedDevice,
+  DeviceStatus,
+  StorageInfo,
+  ScanOptions,
+  Environment,
+  ProvisioningResult,
+} from './models/Device';
+
+// Models - Recording
+export type {
+  AudioCodec,
+  DeviceRecording,
+  UploadInfo,
+  SyncStage,
+  SyncProgress,
+  UploadTaskStatus,
+  UploadTask,
+  TransferPacket,
+} from './models/Recording';
+
+// Models - Status & Events
+export type {
+  LogLevel,
+  SdkStatus,
+  DeviceManagerEvents,
+  RecordingManagerEvents,
+  BotaClientEvents,
+} from './models/Status';
+
+// Errors
+export {
+  BotaError,
+  BluetoothError,
+  DeviceError,
+  ProvisioningError,
+  TransferError,
+  UploadError,
+  SdkError,
+  isBotaError,
+} from './utils/errors';