@robotical/raftjs 1.3.3

package/src/RaftChannelBLE.web.ts

@@ -0,0 +1,362 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+//
+// RaftChannelBLE
+// Part of RaftJS
+//
+// Rob Dobson & Chris Greening 2020-2024
+// (C) 2020-2024 All rights reserved
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+import RaftChannel from "./RaftChannel";
+import { RaftConnEvent, RaftConnEventFn } from "./RaftConnEvents";
+import RaftLog from "./RaftLog";
+import RaftMsgHandler from "./RaftMsgHandler";
+import { ConnectorOptions } from "./RaftSystemType";
+import RaftUtils from "./RaftUtils";
+
+export default class RaftChannelBLE implements RaftChannel {
+  // BLE UUIDS
+  public static RICServiceUUID = "aa76677e-9cfd-4626-a510-0d305be57c8d";
+  public static CogServiceUUID = "da903f65-d5c2-4f4d-a065-d1aade7af874";
+  public static CmdUUID = "aa76677e-9cfd-4626-a510-0d305be57c8e";
+  public static RespUUID = "aa76677e-9cfd-4626-a510-0d305be57c8f";
+
+  // Device and characteristics
+  private _bleDevice: BluetoothDevice | null = null;
+  private _characteristicTx: BluetoothRemoteGATTCharacteristic | null = null;
+  private _characteristicRx: BluetoothRemoteGATTCharacteristic | null = null;
+
+  // Message handler
+  private _raftMsgHandler: RaftMsgHandler | null = null;
+
+  // Conn event fn
+  private _onConnEvent: RaftConnEventFn | null = null;
+
+  // Last message tx time
+  private _msgTxTimeLast = Date.now();
+  private _msgTxMinTimeBetweenMs = 1;
+  private readonly maxRetries = 1;
+
+  // Connected flag and retries
+  private _isConnected = false;
+  private readonly _maxConnRetries = 3;
+
+  // Event listener fn
+  private _eventListenerFn: ((event: Event) => void) | null = null;
+
+  // File Handler parameters
+  private _requestedBatchAckSize = 10;
+  private _requestedFileBlockSize = 500;
+
+  fhBatchAckSize(): number {
+    return this._requestedBatchAckSize;
+  }
+  fhFileBlockSize(): number {
+    return this._requestedFileBlockSize;
+  }
+
+  // Set message handler
+  setMsgHandler(raftMsgHandler: RaftMsgHandler): void {
+    this._raftMsgHandler = raftMsgHandler;
+  }
+
+  requiresSubscription(): boolean {
+    return true;
+  }
+
+  // RICREST command before disconnect
+  ricRestCmdBeforeDisconnect(): string | null {
+    // NT: Sending blerestart *before* disconnecting results in timeout issues as the device is no longer connected when we try to actually disconnect
+    // suggested fix: allow callaback command to be sent after disconnect on the fw side 
+    // return "blerestart";
+    return null;
+  }
+
+  // isEnabled
+  isEnabled() {
+    if (navigator.bluetooth) {
+      RaftLog.error("Web Bluetooth is supported in your browser.");
+      return true;
+    } else {
+      window.alert(
+        "Web Bluetooth API is not available.\n" +
+        'Please make sure the "Experimental Web Platform features" flag is enabled.'
+      );
+      return false;
+    }
+  }
+
+  // isConnected
+  isConnected(): boolean {
+    return this._bleDevice !== null && this._isConnected;
+  }
+
+  // Set onConnEvent handler
+  setOnConnEvent(connEventFn: RaftConnEventFn): void {
+    this._onConnEvent = connEventFn;
+  }
+
+  // Disconnection event
+  onDisconnected(event: Event): void {
+    const device = event.target as BluetoothDevice;
+    RaftLog.debug(`RaftChannelBLE.onDisconnected ${device.name}`);
+    if (this._bleDevice) {
+      this._bleDevice.removeEventListener(
+        "gattserverdisconnected",
+        this._eventListenerFn
+      );
+    }
+    this._isConnected = false;
+    if (this._onConnEvent) {
+      this._onConnEvent(RaftConnEvent.CONN_DISCONNECTED);
+    }
+  }
+
+  // Get connected locator
+  getConnectedLocator(): string | object {
+    return this._bleDevice || "";
+  }
+
+  // Connect to a device
+  async connect(locator: string | object, _connectorOptions: ConnectorOptions): Promise<boolean> {
+    // RaftLog.debug(`Selected device: ${deviceID}`);
+    this._bleDevice = locator as BluetoothDevice;
+    if (this._bleDevice && this._bleDevice.gatt) {
+      try {
+        // Connect
+        for (let connRetry = 0; connRetry < this._maxConnRetries; connRetry++) {
+          // Connect
+          const connTimeoutMs = _connectorOptions.connTimeoutMs || 5000;
+          await RaftUtils.withTimeout(connTimeoutMs, this._bleDevice.gatt.connect());
+          RaftLog.debug(
+            `RaftChannelBLE.connect - ${this._bleDevice.gatt.connected ? "OK" : "FAILED"
+            } attempt ${connRetry + 1} connection to device ${this._bleDevice.name}`
+          );
+
+          if (this._bleDevice.gatt.connected) {
+
+            // Delay a bit
+            await new Promise(resolve => setTimeout(resolve, 100));
+
+            // Get service
+            try {
+              let service: BluetoothRemoteGATTService | null = null;
+              // iterate over known services
+              for (const serviceUUID of [RaftChannelBLE.CogServiceUUID, RaftChannelBLE.RICServiceUUID]) {
+                try {
+                  service = await this._bleDevice.gatt.getPrimaryService(serviceUUID);
+                  if (service) {
+                    break;
+                  }
+                } catch (error) {
+                  RaftLog.warn(
+                    `RaftChannelBLE.connect - cannot get primary service ${error}`
+                  );
+                }
+              }
+
+              if (!service) {
+                RaftLog.error(
+                  `RaftChannelBLE.connect - cannot get primary service - giving up`
+                );
+                return false;
+              }
+              RaftLog.debug(
+                `RaftChannelBLE.connect - found service: ${service.uuid}`
+              );
+
+              try {
+                // Get Tx and Rx characteristics
+                this._characteristicTx = await service.getCharacteristic(
+                  RaftChannelBLE.CmdUUID
+                );
+                RaftLog.debug(
+                  `RaftChannelBLE.connect - found char ${this._characteristicTx.uuid}`
+                );
+                this._characteristicRx = await service.getCharacteristic(
+                  RaftChannelBLE.RespUUID
+                );
+                RaftLog.debug(
+                  `RaftChannelBLE.connect - found char ${this._characteristicRx.uuid}`
+                );
+
+                // Notifications of received messages
+                try {
+                  await this._characteristicRx.startNotifications();
+                  RaftLog.debug(
+                    "RaftChannelBLE.connect - notifications started"
+                  );
+                  this._characteristicRx.addEventListener(
+                    "characteristicvaluechanged",
+                    this._onMsgRx.bind(this)
+                  );
+                } catch (error) {
+                  RaftLog.debug(
+                    "RaftChannelBLE.connnect - addEventListener failed " + error
+                  );
+                }
+
+                // Connected ok
+                RaftLog.debug(`RaftChannelBLE.connect ${this._bleDevice.name}`);
+
+                // Add disconnect listener
+                this._eventListenerFn = this.onDisconnected.bind(this);
+                this._bleDevice.addEventListener(
+                  "gattserverdisconnected",
+                  this._eventListenerFn
+                );
+
+                // Connected
+                this._isConnected = true;
+                return true;
+              } catch (error) {
+                RaftLog.error(
+                  `RaftChannelBLE.connect - cannot find characteristic: ${error}`
+                );
+              }
+            } catch (error) {
+              if (connRetry === this._maxConnRetries - 1) {
+                RaftLog.error(
+                  `RaftChannelBLE.connect - cannot get primary service ${error} - attempt #${connRetry + 1} - giving up`
+                );
+              } else {
+                RaftLog.debug(
+                  `RaftChannelBLE.connect - cannot get primary service - attempt #${connRetry + 1} ${error}`
+                );
+              }
+            }
+          }
+        }
+      } catch (error: unknown) {
+        RaftLog.warn(`RaftChannelBLE.connect - cannot connect ${error}`);
+      }
+
+      // Disconnect
+      if (
+        this._bleDevice &&
+        this._bleDevice.gatt &&
+        this._bleDevice.gatt.connected
+      ) {
+        try {
+          await this._bleDevice.gatt.disconnect();
+        } catch (error) {
+          RaftLog.warn(`RaftChannelBLE.connect - cannot disconnect ${error}`);
+        }
+      }
+    }
+
+    return false;
+  }
+
+  // Disconnect
+  async disconnect(): Promise<void> {
+    if (this._bleDevice && this._bleDevice.gatt) {
+      try {
+        RaftLog.debug(`RaftChannelBLE.disconnect GATT`);
+        await this._bleDevice.gatt.disconnect();
+      } catch (error) {
+        RaftLog.debug(`RaftChannelBLE.disconnect ${error}`);
+      }
+    }
+  }
+
+  pauseConnection(pause: boolean): void {
+    RaftLog.verbose(
+      `pauseConnection ${pause} - no effect for this channel type`
+    );
+    return;
+  }
+
+  // Handle notifications
+  _onMsgRx(event: Event): void {
+    // Get characteristic
+    const characteristic = event.target as BluetoothRemoteGATTCharacteristic;
+
+    // Get value
+    const value = characteristic.value;
+    if (value !== undefined) {
+      const msg = new Uint8Array(value.buffer);
+
+      // Handle message
+      if (this._raftMsgHandler) {
+        try {
+          this._raftMsgHandler.handleNewRxMsg(msg);
+        } catch (error) {
+          RaftLog.debug(`RaftChannelBLE.onMsgRx ${error}`);
+        }
+      }
+    }
+  }
+
+  // Send a message
+  async sendTxMsg(
+    msg: Uint8Array
+    //    _sendWithResponse: boolean
+  ): Promise<boolean> {
+    // Check valid
+    if (this._bleDevice === null) {
+      return false;
+    }
+
+    // Retry upto maxRetries
+    for (let retryIdx = 0; retryIdx < this.maxRetries; retryIdx++) {
+      // Check for min time between messages
+      while (Date.now() - this._msgTxTimeLast < this._msgTxMinTimeBetweenMs) {
+        await new Promise((resolve) => setTimeout(resolve, 5));
+      }
+      this._msgTxTimeLast = Date.now();
+
+      // Write to the characteristic
+      try {
+        if (this._characteristicTx) {
+          if (this._characteristicTx.writeValueWithoutResponse) {
+            await this._characteristicTx.writeValueWithoutResponse(msg);
+          } else if (this._characteristicTx.writeValue) {
+            await this._characteristicTx.writeValue(msg);
+          } else if (this._characteristicTx.writeValueWithResponse) {
+            await this._characteristicTx.writeValueWithResponse(msg);
+          }
+        }
+        break;
+      } catch (error) {
+        if (retryIdx === this.maxRetries - 1) {
+          RaftLog.info(
+            `RaftChannelBLE.sendTxMsg ${error} retried ${retryIdx} times`
+          );
+        }
+      }
+    }
+    return true;
+  }
+
+  // Send message without awaiting response
+  async sendTxMsgNoAwait(
+    msg: Uint8Array
+    //    _sendWithResponse: boolean
+  ): Promise<boolean> {
+    // Check valid
+    if (this._bleDevice === null) {
+      return false;
+    }
+
+    // Check for min time between messages
+    while (Date.now() - this._msgTxTimeLast < this._msgTxMinTimeBetweenMs) {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+    this._msgTxTimeLast = Date.now();
+
+    // Write to the characteristic
+    if (this._characteristicTx) {
+      if (this._characteristicTx.writeValueWithoutResponse) {
+        this._characteristicTx.writeValueWithoutResponse(msg);
+      } else if (this._characteristicTx.writeValue) {
+        this._characteristicTx.writeValue(msg);
+      } else if (this._characteristicTx.writeValueWithResponse) {
+        this._characteristicTx.writeValueWithResponse(msg);
+      }
+      return true;
+    }
+    return false;
+  }
+}

package/src/RaftChannelBLEFactory.ts

@@ -0,0 +1,13 @@
+/**
+ * @description
+ * This file is used to create a new instance of the RaftChannelBLE class.
+ * RaftChannelBLE exists in 2 files: RaftChannelBLE.native.ts and RaftChannelBLE.web.ts
+ * each of these files contains the same class but with different implementations (native and web).
+ * The import statement at the top of the file will import the correct implementation based on the platform 
+ * (depending on the build configuration).
+ */
+import RaftChannelBLE from './RaftChannelBLE';
+
+export function createBLEChannel() {
+  return RaftChannelBLE;
+}

package/src/RaftChannelBLEScanner.native.ts

@@ -0,0 +1,190 @@
+/////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+//
+// RICBLEScanner
+// Communications Connector for RIC V2
+//
+// RIC V2
+// Rob Dobson 2022
+// (C) Robotical 2022
+//
+/////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+import {
+  BleManager,
+  Device,
+  BleError,
+} from 'react-native-ble-plx';
+import { DiscoveredRIC } from './RaftTypes';
+import RaftLog from './RaftLog';
+import { RaftConnEvent, RaftConnEventFn } from './RaftConnEvents';
+
+export default class RICBLEScanner {
+
+  // BleManager
+  _bleManager: BleManager;
+
+  // Services to scan for
+  _uuidsOfServicesToScanFor: Array<string> = [];
+
+  // Scanned devices found on BLE
+  _discoveredRICs: DiscoveredRIC[] = [];
+  static _scanInProgress = false;
+
+  // Time to scan for
+  _discoveryTimeMs = 10000;
+
+  // Event callback
+  _eventCallback: RaftConnEventFn;
+
+  constructor(bleManager: BleManager, uuidsOfServicesToScanFor: Array<string>, eventCallback: RaftConnEventFn) {
+    this._bleManager = bleManager;
+    this._uuidsOfServicesToScanFor = uuidsOfServicesToScanFor;
+    this._eventCallback = eventCallback;
+  }
+
+  // Get discovered RICs
+  getDiscoveredRICs(): DiscoveredRIC[] {
+    return this._discoveredRICs;
+  }
+
+  // Check is a scan is in progress
+  isScanInProgress(): boolean {
+    return RICBLEScanner._scanInProgress;
+  }
+
+  async scanningStart(uuid?: string): Promise<boolean> {
+    let uuidsOfServicesToScanFor: string[] = [];
+    if (uuid) {
+      uuidsOfServicesToScanFor.push(uuid);
+    } else {
+      uuidsOfServicesToScanFor = this._uuidsOfServicesToScanFor;
+    }
+    // Handle discovery
+    RaftLog.debug('Starting Scanning...');
+
+    // Clear list
+    this._discoveredRICs = [];
+
+    // Disconnect any connections
+    RICBLEScanner._scanInProgress = true;
+
+    // Start scan
+    try {
+      this._bleManager.startDeviceScan(
+        uuidsOfServicesToScanFor,
+        { allowDuplicates: true },
+        (error: BleError | null, device: Device | null) => {
+          // RaftLog.debug(`discoveryFoundCB error ${error}`);
+          this._discoveryFoundCB(error, device);
+        },
+      );
+    } catch (e) {
+      RaftLog.warn(`Error starting scan ${e}`);
+      return false;
+    }
+
+    // Set a time limit
+    this._discoverySetTimeLimit(this._discoveryTimeMs);
+    return true;
+  }
+
+  scanningStop(): void {
+
+    RaftLog.debug('scanningStop');
+
+    // Emit finished if we were scanning
+    RaftLog.debug(`IS SCANNING IN PROGRESS: ${RICBLEScanner._scanInProgress}`);
+    if (RICBLEScanner._scanInProgress) {
+      RaftLog.debug(`sending BLE_SCANNING_FINISHED event`);
+      this._eventCallback(RaftConnEvent.BLE_SCANNING_FINISHED, { discoveredRICs: this._discoveredRICs });
+    }
+
+    // Cancel scanning
+    this._bleManager.stopDeviceScan();
+    RICBLEScanner._scanInProgress = false;
+  }
+
+  // Callback from BLE-PLX library on device discovered
+  _discoveryFoundCB(
+    error: BleError | null,
+    scannedDevice: Device | null,
+  ): void {
+    if (error) {
+      //RaftLog.warn(`⚠️ Scan Error >> ${error.toString()}`);
+      RaftLog.warn(`⚠️ Scan Error >> ${JSON.stringify(error)}`);
+      // Event if we were scanning
+      if (RICBLEScanner._scanInProgress) {
+        this._eventCallback(RaftConnEvent.BLE_SCANNING_FINISHED, {
+          discoveredRICs: this._discoveredRICs,
+        });
+        RICBLEScanner._scanInProgress = false;
+      }
+      return;
+    }
+
+    // See if already in the list
+    const ricAlreadyFound = this._discoveredRICs.find(
+      item => item.id === scannedDevice!.id,
+    );
+
+    RaftLog.debug(`✅ Scanning... >> ${scannedDevice}`);
+
+    if (ricAlreadyFound) {
+      // update the rssi value if it's not 127
+      if (scannedDevice!.rssi !== null && scannedDevice!.rssi !== 127) {
+        ricAlreadyFound._rssi = scannedDevice!.rssi;
+        this._eventCallback(RaftConnEvent.BLE_DEVICE_FOUND, {
+          discoveredRIC: ricAlreadyFound
+        });
+      }
+      return;
+    }
+
+    if (scannedDevice !== null) {
+      if (!scannedDevice.localName) {
+        // if the name of the device is null, don't add this device
+        // the first time round. Second time this device comes up
+        // will have all the needed info
+        return;
+      }
+      const newDiscoveredRic = new DiscoveredRIC(
+        scannedDevice.localName !== null ? scannedDevice.localName : '',
+        scannedDevice.name !== null ? scannedDevice.name : '',
+        scannedDevice.id,
+        scannedDevice.rssi !== null ? scannedDevice.rssi : -150,
+      );
+      this._discoveredRICs.push(newDiscoveredRic);
+      // send the newly found ric to the state so it can pop-up on the front-end
+      this._eventCallback(RaftConnEvent.BLE_DEVICE_FOUND, {
+        discoveredRIC: newDiscoveredRic
+      });
+    }
+    RaftLog.debug(`🤖 Scanned RICs >> ${this._discoveredRICs}`);
+  }
+
+  // Time-limit on device scanning
+  _discoverySetTimeLimit(timeLimitMs: number) {
+    setTimeout(() => {
+      // Stop scanning
+      this._bleManager.stopDeviceScan();
+
+      // Check we were scanning
+      if (RICBLEScanner._scanInProgress) {
+        // Sort by signal strength
+        // this._discoveredRICs.sort((a, b) => {
+        //   return b!.rssi! - a!.rssi!;
+        // });
+
+        // Debug
+        const msg = `🤖 ${this._discoveredRICs.length} RICs found! Choose one to connect`;
+        RaftLog.debug(msg);
+
+        // Finished event
+        this._eventCallback(RaftConnEvent.BLE_SCANNING_FINISHED, {
+          discoveredRICs: this._discoveredRICs,
+        });
+      }
+      RICBLEScanner._scanInProgress = false;
+    }, timeLimitMs);
+  }
+}