GATT

Bluetooth Generic Attribute Profile (GATT) for Swift

Installation

GATT is available as a Swift Package Manager package. To use it, add the following dependency in your Package.swift:

.package(url: "https://github.com/PureSwift/GATT.git", branch: "master"),

and to your target, add GATT to your dependencies. You can then import GATT to get access to GATT functionality.

Package Traits

GATT requires Swift 6.2 and uses package traits to gate the pure Swift GATT stack:

Trait	Default	Description
BluetoothGATT	Disabled	Imports the BluetoothGATT module, enabling the pure Swift GATT server (GATTPeripheral, PeripheralManager) and making the central use the BluetoothGATT types (GATTCharacteristicProperties, ATTAttributePermissions, ATTMaximumTransmissionUnit) instead of the lightweight shims.

By default the BluetoothGATT trait is disabled, so GATT builds against the lightweight shim types. This suits central-only clients built on a platform Bluetooth stack (for example CoreBluetooth on iOS or the Android Bluetooth API), where the platform provides the GATT server and the shims keep the dependency footprint small.

Enable the trait when you need a GATT server (peripheral). This applies to both the pure Swift GATTPeripheral and the CoreBluetooth-backed DarwinPeripheral; the shim build provides the central role only. On platforms without threading (Embedded Swift targets like Pi Pico W, ESP32 or nRF52840 running BTStack, NimBLE or Zephyr), GATTPeripheral is driven by calling its non-blocking run() method from the platform's run loop instead of background threads.

.package(
    url: "https://github.com/PureSwift/GATT.git",
    branch: "master",
    traits: ["BluetoothGATT"]
),

Platforms

Platform	Roles	Backend	Library
macOS, iOS, watchOS, tvOS, visionOS	Central, Peripheral	CoreBluetooth	DarwinGATT
Linux	Central, Peripheral	BlueZ	BluetoothLinux, GATT
Android	Central	Java Native Interface	AndroidBluetooth
WebAssembly	Central	Bluetooth Web API	BluetoothWeb
Pi Pico W	Peripheral	BlueKitchen BTStack	BTStack
ESP32	Peripheral	Apache NimBLE	NimBLE
nRF52840	Peripheral	Zephyr SDK	Zephyr

Usage

Peripheral

import Bluetooth
#if canImport(Darwin)
import DarwinGATT
#elseif os(Linux)
import BluetoothLinux
#endif

#if os(Linux)
typealias LinuxPeripheral = GATTPeripheral<BluetoothLinux.HostController, BluetoothLinux.L2CAPSocket>
guard let hostController = await HostController.default else {
    fatalError("No Bluetooth hardware connected")
}
let serverOptions = GATTPeripheralOptions(
    maximumTransmissionUnit: .max,
    maximumPreparedWrites: 1000
)
let peripheral = LinuxPeripheral(
    hostController: hostController,
    options: serverOptions,
    socket: BluetoothLinux.L2CAPSocket.self
)
#elseif canImport(Darwin)
let peripheral = DarwinPeripheral()
#else
#error("Unsupported platform")
#endif

// start advertising
try await peripheral.start()

Central

import Bluetooth
#if canImport(Darwin)
import DarwinGATT
#elseif os(Linux)
import BluetoothLinux
#endif

#if os(Linux)
typealias LinuxCentral = GATTCentral<BluetoothLinux.HostController, BluetoothLinux.L2CAPSocket>
let hostController = await HostController.default
let central = LinuxCentral(
    hostController: hostController,
    socket: BluetoothLinux.L2CAPSocket.self
)
#elseif canImport(Darwin)
let central = DarwinCentral()
#else
#error("Unsupported platform")
#endif

// start scanning
let stream = try await central.scan(filterDuplicates: true)
for try await scanData in stream {
    print(scanData)
    stream.stop()
}

Documentation

Read the documentation here. Documentation can be generated with DocC.

License

GATT is released under the MIT license. See LICENSE for details.