add readrssi

You can read the Received Signal Strength Indicator (RSSI) of a peripheral to determine its signal strength:

let rssiValue = try await peripheral.readRSSI()

Author: meech-ward

CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] - 2025-04-25
+
+### Added
+- Add RSSI value to Peripheral `readRSSI()`
+
 ## [0.3.1] - 2025-03-10
 
 ### Fixed

README.md

@@ -353,6 +353,29 @@ for await value in characteristic.value.stream { // or .current or .observable
 try await peripheral.writeValueWithResponse(data, for: characteristic) 
 ```
 
+## RSSI
+
+You can read the Received Signal Strength Indicator (RSSI) of a peripheral to determine its signal strength:
+
+```swift
+// Read RSSI once
+let rssiValue = try await peripheral.readRSSI()
+print("Signal strength: \(rssiValue) dBm") // Values typically range from -40 (near) to -100 dBm (far)
+
+// Or observe RSSI changes over time
+for await rssi in peripheral.rssi.stream {
+  print("RSSI updated: \(rssi) dBm") 
+  if rssi > -50 {
+    print("Device is very close")
+  } else if rssi > -70 {
+    print("Device is at medium range")
+  } else {
+    print("Device is far away")
+  }
+}
+
+// note that the rssi is only updated when you call readRSSI, so you would need to call this for the loop to itterate
+```
 
 ## Running Tests
 

Sources/AsyncCoreBluetooth/Peripheral.swift

@@ -138,6 +138,7 @@ public actor Peripheral {
   /// that is only available in the underlying `CBMPeripheral`.
   public private(set) var cbPeripheral: CBMPeripheral
 
+
   /// The unique identifier associated with the peripheral.
   ///
   /// This UUID uniquely identifies the peripheral and can be used to retrieve the peripheral later
@@ -153,12 +154,44 @@ public actor Peripheral {
   /// This will not affect the async streams.
   public var delegate: CBMPeripheralDelegate?
 
+  /// The received signal strength indicator (RSSI) of the peripheral.
+  ///
+  /// This property is an AsyncObservableUnwrapped that provides the signal strength
+  /// of the connection with the peripheral, measured in decibels (dBm).
+  /// The closer to 0, the stronger the signal (for example, -30 is a strong signal,
+  /// while -90 is a weak signal).
+  ///
+  /// Example Usage:
+  /// ```swift
+  /// Task {
+  ///   for await value in peripheral.rssi {
+  ///     print("RSSI updated: \(value) dBm")
+  ///     // You could use this to estimate proximity to the device
+  ///     if value > -50 {
+  ///       print("Very close proximity")
+  ///     } else if value > -70 {
+  ///       print("Medium proximity")
+  ///     } else {
+  ///       print("Far proximity")
+  ///     }
+  ///   }
+  /// }
+  /// ```
+  ///
+  /// Note: The RSSI value updates when you call `readRSSI()` or when the system
+  /// periodically updates the value for connected peripherals.
+  @MainActor
+  let _rssi: AsyncObservableUnwrapped<Int> = .init(nil)
+  @MainActor
+  public var rssi: some AsyncObservableUnwrappedStreamReadOnly<Int> { _rssi }
+
   private var peripheralDelegate: PeripheralDelegate?
 
   var discoverServicesContinuations = Deque<CheckedContinuation<[CBUUID /* service uuid */: Service], Error>>()
   var discoverCharacteristicsContinuations: [CBUUID /* service uuid */: Deque<CheckedContinuation<[CBUUID /* characteristic uuid */: Characteristic], Error>>] = [:]
 
   var readCharacteristicValueContinuations: [CBUUID: Deque<CheckedContinuation<Data, Error>>] = [:]
+  var readRSSIContinuations: Deque<CheckedContinuation<Int, Error>> = []
   var writeCharacteristicWithResponseContinuations: Deque<CheckedContinuation<Void, any Error>> = Deque<CheckedContinuation<Void, Error>>()
   var notifyCharacteristicValueContinuations: [CBUUID: Deque<CheckedContinuation<Bool, Error>>] = [:]
 
@@ -427,6 +460,41 @@ extension Peripheral {
     }
   }
 
+  /// Reads the current RSSI value for the peripheral.
+  ///
+  /// This method requests the current received signal strength indicator (RSSI) from the peripheral.
+  /// RSSI is measured in decibels (dBm) and provides an indication of connection signal strength.
+  /// The value is typically negative, with values closer to 0 indicating stronger signals.
+  ///
+  /// Example Usage:
+  /// ```swift
+  /// do {
+  ///   let rssiValue = try await peripheral.readRSSI()
+  ///   print("Current RSSI: \(rssiValue) dBm")
+  ///   
+  ///   // Use RSSI for approximate distance estimation
+  ///   if rssiValue > -50 {
+  ///     print("Device is nearby")
+  ///   } else if rssiValue > -70 {
+  ///     print("Device is at medium range")
+  ///   } else {
+  ///     print("Device is far away")
+  ///   }
+  /// } catch {
+  ///   print("Failed to read RSSI: \(error)")
+  /// }
+  /// ```
+  ///
+  /// - Returns: The current RSSI value in dBm (decibels relative to 1 milliwatt).
+  /// - Throws: An error if the RSSI read operation fails or if the peripheral disconnects during the read.
+  @discardableResult
+  public func readRSSI() async throws -> Int {
+    return try await withCheckedThrowingContinuation { continuation in
+      readRSSIContinuations.append(continuation)
+      cbPeripheral.readRSSI()
+    }
+  }
+
   /// Writes a value to a characteristic and waits for a response.
   ///
   /// This method writes data to the specified characteristic and waits for a confirmation

Sources/AsyncCoreBluetooth/PeripheralDelegate.swift

@@ -25,6 +25,11 @@ extension Peripheral {
   func peripheral(_ cbPeripheral: CBMPeripheral, didReadRSSI RSSI: NSNumber, error: Error?) {
     print("peripheral \(cbPeripheral) didReadRSSI \(RSSI) error \(String(describing: error))")
     delegate?.peripheral(cbPeripheral, didReadRSSI: RSSI, error: error)
+    self._rssi.update(RSSI.intValue)
+    guard let continuation = readRSSIContinuations.popFirst() else {
+      return
+    }
+    continuation.resume(with: Result.success(RSSI.intValue))
   }
 
   func peripheral(

Tests/AsyncCoreBluetoothTests/MockPeripheral.swift

@@ -33,6 +33,8 @@ class MockPeripheral: @unchecked Sendable {
       return peripheralDidReceiveConnectionRequestResult
     }
 
+  
+ 
     // Read requests
     func peripheral(
       _ peripheral: CBMPeripheralSpec,
@@ -93,12 +95,12 @@ class MockPeripheral: @unchecked Sendable {
     }
   }
 
-  static func makeDevice(identifier: UUID = UUID(), delegate: CBMPeripheralSpecDelegate, isKnown: Bool = false)
+  static func makeDevice(identifier: UUID = UUID(), delegate: CBMPeripheralSpecDelegate, isKnown: Bool = false, proximity: CBMProximity = .near)
     -> CBMPeripheralSpec
   {
     var spec =
       CBMPeripheralSpec
-      .simulatePeripheral(identifier: identifier, proximity: .near)
+      .simulatePeripheral(identifier: identifier, proximity: proximity)
       .advertising(
         advertisementData: [
           CBMAdvertisementDataLocalNameKey: "my device",

Tests/AsyncCoreBluetoothTests/Peripheral/ReadRSSITests.swift

@@ -0,0 +1,206 @@
+@preconcurrency import CoreBluetoothMock
+import Foundation
+import Testing
+
+@testable import AsyncCoreBluetooth
+
+@Suite(.serialized) struct ReadRSSITests {
+  let mockPeripheralDelegate = MockPeripheral.Delegate()
+  let rssiDeviation = 15
+  
+  func setup(proximity: CBMProximity, connect: Bool = true) async throws -> (Peripheral, CBMPeripheralSpec, CentralManager) {
+    CBMCentralManagerMock.simulateInitialState(.poweredOff)
+
+    // Create a mutable mockPeripheral
+    let mockPeripheral = MockPeripheral.makeDevice(
+      delegate: mockPeripheralDelegate,
+      isKnown: true,
+      proximity: proximity
+    )
+
+    CBMCentralManagerMock.simulatePeripherals([mockPeripheral])
+    CBMCentralManagerMock.simulateInitialState(.poweredOn)
+
+    let centralManager = CentralManager(forceMock: true)
+    _ = await centralManager.start().first(where: { $0 == .poweredOn })
+
+    let peripheral = await centralManager.retrievePeripherals(withIdentifiers: [
+      mockPeripheral.identifier
+    ])[0]
+    if connect {
+      _ = await centralManager.connect(peripheral).first(where: { $0 == .connected })
+    }
+ 
+    return (peripheral, mockPeripheral, centralManager)
+  }
+
+  @Test("Read RSSI returns near proximity value")
+  func test_readRSSI_near() async throws {
+    let (peripheral, _, _) = try await setup(proximity: .near)
+
+    try await peripheral.readRSSI()
+    guard let rssiValue = await peripheral.rssi.stream.first(where: { _ in true }) else {
+      Issue.record("No RSSI value received")
+      return
+    }
+    // Near proximity base RSSI is -40, but can vary by ±15 (rssiDeviation)
+    #expect(rssiValue >= -40 - rssiDeviation && rssiValue <= -40 + rssiDeviation)
+  }
+
+  @Test("Read RSSI returns immediate proximity value")
+  func test_readRSSI_immediate() async throws {
+    let (peripheral, _, _) = try await setup(proximity: .immediate)
+
+    try await peripheral.readRSSI()
+    guard let rssiValue = await peripheral.rssi.stream.first(where: { _ in true }) else {
+      Issue.record("No RSSI value received")
+      return
+    }
+    // Immediate proximity base RSSI is -70, but can vary by ±15 (rssiDeviation)
+    #expect(rssiValue >= -70 - rssiDeviation && rssiValue <= -70 + rssiDeviation)
+  }
+
+  @Test("Read RSSI returns far proximity value")
+  func test_readRSSI_far() async throws {
+    let (peripheral, _, _) = try await setup(proximity: .far)
+
+    try await peripheral.readRSSI()
+    guard let rssiValue = await peripheral.rssi.stream.first(where: { _ in true }) else {
+      Issue.record("No RSSI value received")
+      return
+    }
+    // Far proximity base RSSI is -100, but can vary by ±15 (rssiDeviation)
+    #expect(rssiValue >= -100 - rssiDeviation && rssiValue <= -100 + rssiDeviation)
+  }
+
+  @Test("RSSI Observable is initially nil")
+  func test_rssi_initially_nil() async throws {
+    let (peripheral, _, _) = try await setup(proximity: .near)
+    
+    // Before reading RSSI, the observable should be nil
+    let initialValue = await peripheral._rssi.current
+    #expect(initialValue == nil)
+  }
+
+  @Test("Multiple sequential RSSI reads return consistent values for the same proximity")
+  func test_sequential_rssi_reads_consistent() async throws {
+    let (peripheral, _, _) = try await setup(proximity: .near)
+    
+    // Read RSSI multiple times with the same proximity
+    let rssi1 = try await peripheral.readRSSI()
+    let rssi2 = try await peripheral.readRSSI()
+    let rssi3 = try await peripheral.readRSSI()
+    
+    // All values should be near proximity (-40 ± deviation)
+    #expect(rssi1 >= -40 - rssiDeviation && rssi1 <= -40 + rssiDeviation)
+    #expect(rssi2 >= -40 - rssiDeviation && rssi2 <= -40 + rssiDeviation)
+    #expect(rssi3 >= -40 - rssiDeviation && rssi3 <= -40 + rssiDeviation)
+    
+    // The observable should have the latest value
+    let currentValue = await peripheral._rssi.current
+    #expect(currentValue == rssi3)
+  }
+  
+  @Test("RSSI observable updates when proximity changes")
+  func test_rssi_updates_with_proximity_changes() async throws {
+    // Start with near proximity
+    let (peripheral, mockPeripheral, _) = try await setup(proximity: .near)
+    
+    // Read initial RSSI
+    _ = try await peripheral.readRSSI()
+    let initialRssi = await peripheral._rssi.current
+    #expect(initialRssi != nil)
+    #expect(initialRssi! >= -40 - rssiDeviation && initialRssi! <= -40 + rssiDeviation)
+    
+    // Change proximity to far and read again
+    mockPeripheral.simulateProximityChange(.far)
+    _ = try await peripheral.readRSSI()
+    
+    // RSSI should update to far proximity value
+    let farRssi = await peripheral._rssi.current
+    #expect(farRssi != nil)
+    #expect(farRssi! >= -100 - rssiDeviation && farRssi! <= -100 + rssiDeviation)
+  }
+  
+  @Test("RSSI stream receives updates")
+  func test_rssi_stream_receives_updates() async throws {
+    let (peripheral, mockPeripheral, _) = try await setup(proximity: .near)
+    
+    // Get initial RSSI value
+    _ = try await peripheral.readRSSI()
+    let firstValue = await peripheral._rssi.current
+    #expect(firstValue != nil)
+    #expect(firstValue! >= -40 - rssiDeviation && firstValue! <= -40 + rssiDeviation)
+    
+    // Change to immediate proximity and read
+    mockPeripheral.simulateProximityChange(.immediate)
+    _ = try await peripheral.readRSSI()
+    let secondValue = await peripheral._rssi.current
+    #expect(secondValue != nil)
+    #expect(secondValue! >= -70 - rssiDeviation && secondValue! <= -70 + rssiDeviation)
+    
+    // Change to far proximity and read
+    mockPeripheral.simulateProximityChange(.far)
+    _ = try await peripheral.readRSSI()
+    let thirdValue = await peripheral._rssi.current
+    #expect(thirdValue != nil)
+    #expect(thirdValue! >= -100 - rssiDeviation && thirdValue! <= -100 + rssiDeviation)
+  }
+  
+  @Test("RSSI values can be collected with AsyncStream")
+  func test_rssi_values_collected_with_stream() async throws {
+    let (peripheral, mockPeripheral, _) = try await setup(proximity: .near)
+    
+    // Create a task to collect RSSI values from the stream
+    let streamTask = Task {
+      var values = [Int]()
+      var count = 0
+      for await value in await peripheral.rssi.stream {
+        values.append(value)
+        count += 1
+        if count >= 3 {
+          // We'll collect 3 values
+          break
+        }
+      }
+      return values
+    }
+    
+    // Now perform real RSSI reads with different proximities to generate values
+    _ = try await peripheral.readRSSI() // Read with near proximity
+    
+    // Change to immediate proximity and read again
+    mockPeripheral.simulateProximityChange(.immediate)
+    _ = try await peripheral.readRSSI()
+    
+    // Change to far proximity and read again
+    mockPeripheral.simulateProximityChange(.far)
+    _ = try await peripheral.readRSSI()
+    
+    // Get the collected values from our stream task
+    let collectedValues = await streamTask.value
+    
+    // Verify the stream collected all three values
+    #expect(collectedValues.count == 3)
+    
+    // Verify values match the expected proximity ranges
+    #expect(collectedValues[0] >= -40 - rssiDeviation && collectedValues[0] <= -40 + rssiDeviation) // Near
+    #expect(collectedValues[1] >= -70 - rssiDeviation && collectedValues[1] <= -70 + rssiDeviation) // Immediate
+    #expect(collectedValues[2] >= -100 - rssiDeviation && collectedValues[2] <= -100 + rssiDeviation) // Far
+  }
+  
+  // @Test("Disconnected peripheral throws error on RSSI read")
+  // func test_disconnected_peripheral_throws_error() async throws {
+  //   let (peripheral, _, centralManager) = try await setup(proximity: .near)
+  //   await centralManager.cancelPeripheralConnection(peripheral)
+    
+  //   // Attempt to read RSSI, should throw an error
+  //   do {
+  //     _ = try await peripheral.readRSSI()
+  //     Issue.record("Expected an error when reading RSSI from disconnected peripheral")
+  //   } catch {
+  //     // Expected to throw an error
+  //     #expect(error is PeripheralConnectionError)
+  //   }
+  // }
+}