Spezi Bluetooth

https://github.com/stanfordspezi/spezibluetooth
Admin
A Swift module for connecting and communicating with Bluetooth devices using modern programming...
Tokens:4,008
Snippets:64
Trust Score:9.8
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install TestPeripheral launchd Service

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/Sources/TestPeripheral/TestPeripheral.docc/Service-Setup.md

Installs the launchd service for the TestPeripheral application. Ensure the TestPeripheral binary is in the `/Applications` folder before running.

```shell
./bin/service-launchd.sh install
```

--------------------------------

### Start TestPeripheral launchd Service

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/Sources/TestPeripheral/TestPeripheral.docc/Service-Setup.md

Loads and starts the TestPeripheral service into `launchd`. If the peripheral does not appear, try toggling Bluetooth off and on.

```shell
./bin/service-launchd.sh start
```

--------------------------------

### Configure Bluetooth Module

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/Sources/SpeziBluetooth/SpeziBluetooth.docc/SpeziBluetooth.md

Configure the Bluetooth module within your Spezi app's delegate. This example shows how to discover devices advertising a specific service UUID.

```swift
import Spezi

class ExampleDelegate: SpeziAppDelegate {
    override var configuration: Configuration {
        Configuration {
            Bluetooth {
                // Define which devices type to discover by what criteria .
                // In this case we search for some custom FFF0 characteristic that is advertised.
                Discover(MyDevice.self, by: .advertisedService("FFF0"))
            }
        }
    }
}
```

--------------------------------

### Using Bluetooth Module in SwiftUI

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/Sources/SpeziBluetooth/SpeziBluetooth.docc/SpeziBluetooth.md

Access the Bluetooth module and connected devices from your SwiftUI views using the @Environment property wrapper. This example demonstrates listing nearby devices, auto-connecting, and displaying connected device status.

```swift
import SpeziBluetooth
import SwiftUI

struct MyView: View {
    @Environment(Bluetooth.self)
    var bluetooth
    @Environment(MyDevice.self)
    var myDevice: MyDevice?

    var body: some View {
        List {
            if let myDevice {
                Section {
                    Text("Device")
                    Spacer()
                    Text("\(myDevice.state.description)")
                }
            }

            Section {
                ForEach(bluetooth.nearbyDevices(for: MyDevice.self), id: \.id) {
                    device in
                    Text("\(device.name ?? \"unknown\")")
                }
            } header: {
                HStack {
                    Text("Devices")
                        .padding(.trailing, 10)
                    if bluetooth.isScanning {
                        ProgressView()
                    }
                }
            }
        }
            .scanNearbyDevices(with: bluetooth, autoConnect: true)
    }
}
```

--------------------------------

### Integrate BluetoothDevice as a Spezi Module

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/Sources/SpeziBluetooth/SpeziBluetooth.docc/SpeziBluetooth.md

Demonstrates how a BluetoothDevice can be treated as a Spezi Module, allowing it to leverage dependency injection and interact with other Spezi Modules.

```swift
class Measurements: Module, EnvironmentAccessible, DefaultInitializable {
    required init() {}

    func recordNewMeasurement(_ measurement: WeightMeasurement) {
        // ... process measurement
    }
}

class MyDevice: BluetoothDevice {
    @Service var weightScale = WeightScaleService()
    
    // declare dependency to a configured Spezi Module
    @Dependency var measurements: Measurements
    
    required init() {}

    func configure() {
        weightScale.$weightMeasurement.onChange { [weak self] value in
            self?.handleNewMeasurement(value)
        }
    }
    
    private func handleNewMeasurement(_ measurement: WeightMeasurement) {
        measurements.recordNewMeasurement(measurement)
    }
}
```

--------------------------------

### Implement a Bluetooth Device

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/README.md

Create a `BluetoothDevice` implementation using property wrappers like `@DeviceState` for device properties and `@Service` for custom services. `@DeviceAction` can be used to access device actions.

```swift
class MyDevice: BluetoothDevice {
    @DeviceState(\.id)
    var id: UUID
    @DeviceState(\.name)
    var name: String?
    @DeviceState(\.state)
    var state: PeripheralState

    @Service var deviceInformation = DeviceInformationService()

    @DeviceAction(\.connect)
    var connect
    @DeviceAction(\.disconnect)
    var disconnect

    required init() {}
}
```

--------------------------------

### Configure Bluetooth Module in SpeziAppDelegate

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/README.md

Configure the `Bluetooth` module within your `SpeziAppDelegate` by specifying which device types to discover and by what criteria, such as advertised services.

```swift
import Spezi

class ExampleDelegate: SpeziAppDelegate {
    override var configuration: Configuration {
        Configuration {
            Bluetooth {
                // Define which devices type to discover by what criteria .
                // In this case we search for some custom FFF0 service that is advertised.
                Discover(MyDevice.self, by: .advertisedService("FFF0"))
            }
        }
    }
}
```

--------------------------------

### Check TestPeripheral launchd Service Status

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/Sources/TestPeripheral/TestPeripheral.docc/Service-Setup.md

Retrieves the current status of the TestPeripheral launch agent. Displays the PID and exit code if the service is running.

```shell
./bin/service-launchd.sh status
```

--------------------------------

### Access Spezi Module from BluetoothDevice

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/README.md

Demonstrates how a `BluetoothDevice` can access a configured Spezi Module using the `@Dependency` property. Ensure the `Measurements` module is configured within your Spezi application.

```swift
class Measurements: Module, EnvironmentAccessible, DefaultInitializable {
    required init() {}

    func recordNewMeasurement(_ measurement: WeightMeasurement) {
        // ... process measurement
    }
}

class MyDevice: BluetoothDevice {
    @Service var weightScale = WeightScaleService()
    
    // declare dependency to a configured Spezi Module
    @Dependency var measurements: Measurements
    
    required init() {}
    
    func configure() {
        weightScale.$weightMeasurement.onChange { [weak self] value in
            self?.handleNewMeasurement(value)
        }
    }
    
    private func handleNewMeasurement(_ measurement: WeightMeasurement) {
        measurements.recordNewMeasurement(measurement)
    }
}
```

--------------------------------

### Scan and Display Nearby Devices

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/README.md

Access the Bluetooth module from the SwiftUI environment to scan for nearby devices, auto-connect to the first available one, and display device information. Requires importing SpeziBluetooth and SwiftUI.

```swift
import SpeziBluetooth
import SwiftUI

struct MyView: View {
    @Environment(Bluetooth.self)
    var bluetooth
    @Environment(MyDevice.self)
    var myDevice: MyDevice?

    var body: some View {
        List {
            if let myDevice {
                Section {
                    Text("Device")
                    Spacer()
                    Text("\(myDevice.state.description)")
                }
            }

            Section {
                ForEach(bluetooth.nearbyDevices(for: MyDevice.self), id: \.id) { device in
                    Text("\(device.name ?? \"unknown\")")
                }
            } header: {
                HStack {
                    Text("Devices")
                        .padding(.trailing, 10)
                    if bluetooth.isScanning {
                        ProgressView()
                    }
                }
            }
        }
            .scanNearbyDevices(with: bluetooth, autoConnect: true)
    }
}
```

--------------------------------

### Register Bluetooth Module in SpeziAppDelegate

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/README.md

Register the Bluetooth module within your Spezi application's configuration. This is necessary for the module to be initialized and available for use.

```swift
class ExampleAppDelegate: SpeziAppDelegate {
    override var configuration: Configuration {
        Configuration {
            Bluetooth {
                // discover devices ...
            }
        }
    }
}
```

--------------------------------

### Uninstall TestPeripheral launchd Service

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/Sources/TestPeripheral/TestPeripheral.docc/Service-Setup.md

Completely removes the TestPeripheral launchd launch agent from the system.

```shell
./bin/service-launchd.sh uninstall
```

--------------------------------

### Enable Automation Mode for UI Tests

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/Sources/TestPeripheral/TestPeripheral.docc/Service-Setup.md

Enables UI automation mode without requiring authentication, which is necessary for running UI tests on macOS.

```shell
automationmodetool enable-automationmode-without-authentication
```

--------------------------------

### Define Bluetooth Service with Characteristics

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/README.md

Implement a Bluetooth service by conforming to `BluetoothService` and declare characteristics using the `@Characteristic` property wrapper. Ensure value types are optional and conform to `ByteEncodable`, `ByteDecodable`, or `ByteCodable`.

```swift
struct DeviceInformationService: BluetoothService {
    static let id: BTUUID = "180A"

    @Characteristic(id: "2A29")
    var manufacturer: String?
    @Characteristic(id: "2A26")
    var firmwareRevision: String?
}
```

--------------------------------

### Stop TestPeripheral launchd Service

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/Sources/TestPeripheral/TestPeripheral.docc/Service-Setup.md

Unloads and stops the TestPeripheral service from `launchd`.

```shell
./bin/service-launchd.sh stop
```

--------------------------------

### Retrieve and Connect to a Specific Device

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/README.md

Retrieve a previously paired or known Bluetooth device using its identifier and attempt to connect to it. This method is efficient for connecting to specific devices rather than scanning broadly. Assumes the Bluetooth module is accessible and device actions are declared.

```swift
let id: UUID = ... // a Bluetooth peripheral identifier (e.g., previously retrieved when pairing the device)

let device = bluetooth.retrieveDevice(for: id, as: MyDevice.self)

await device.connect() // assume declaration of @DeviceAction(\.connect)

// Connect doesn't time out. Connection with the device will be established as soon as the device is in reach.
```

--------------------------------

### Retrieve a Specific Bluetooth Device

Source: https://github.com/stanfordspezi/spezibluetooth/blob/main/Sources/SpeziBluetooth/SpeziBluetooth.docc/SpeziBluetooth.md

Retrieve a previously paired Bluetooth device using its UUID. This is useful for establishing a connection to a known device without needing to scan for it first. The connection is established asynchronously when the device becomes available.

```swift
let id: UUID = ... // a Bluetooth peripheral identifier (e.g., previously retrieved when pairing the device)

let device = bluetooth.retrieveDevice(for: id, as: MyDevice.self)

await device.connect() // assume declaration of @DeviceAction(\ .connect)

// Connect doesn't time out. Connection with the device will be established as soon as the device is in reach.
```
Tokens:
Raw