ble

README

telesma-app/ble

github.com/telesma-app/ble is a small, cgo-free BLE Central/GATT client for Go. Its first backend calls the Objective-C CoreBluetooth API through purego/objc; no TinyGo, C compiler, Objective-C shim, or main run loop is required.

The API intentionally covers discovery, connections, service and characteristic discovery, acknowledged writes, reads, and notifications. It does not manage pairing or bonds. When a remote characteristic requires link security, the operating system may perform pairing and establish the encrypted link as part of the GATT operation.

Platforms

Platform	Backend
macOS amd64/arm64	CoreBluetooth and Foundation via purego
Linux and Windows	Unsupported stub returning ble.ErrUnavailable

The module requires Go 1.25 or newer. It is currently an untagged prototype used by the CTAP BLE backend in github.com/telesma-app/ctap.

Usage

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

for info, err := range ble.Scan(ctx, ble.UUID16(0xfffd)) {
	if err != nil {
		if errors.Is(err, context.DeadlineExceeded) {
			break
		}
		log.Fatal(err)
	}
	fmt.Printf("%s %s %d dBm\n", info.ID, info.Name, info.RSSI)
}

Scan deduplicates by the opaque CoreBluetooth identifier and stops the native scan when its context ends or its iterator consumer stops. An advertisement is not a connection-state event, so this package deliberately does not expose a Watch API.

Open can connect to an identifier discovered in the current process or one known to CoreBluetooth. GATT operations on one peripheral are serialized. If a context is canceled while a native operation is in flight, the Go call returns promptly, but the next operation waits for the original CoreBluetooth callback. A canceled connection remains busy until CoreBluetooth confirms its disconnection. Writes are never retried automatically.

On macOS, the host application is responsible for Bluetooth authorization and an appropriate NSBluetoothAlwaysUsageDescription. Command-line use also requires Bluetooth permission for the terminal application. See Apple's CBCentralManager documentation for the native central-role lifecycle.

Testing

gofmt -l .
go vet ./...
go test ./...
go test -race ./...
CGO_ENABLED=0 go test ./...

Documentation

Overview

Package ble provides the small Bluetooth Low Energy central/GATT client surface required by CTAP BLE transports.

Index

• Variables
• func Scan(ctx context.Context, _ UUID) iter.Seq2[*DeviceInfo, error]
• type Characteristic
• type CharacteristicProperties
• type DeviceInfo
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type Identifier
• type Peripheral
  • func Open(ctx context.Context, _ Identifier) (Peripheral, error)
• type Service
• type Subscription
• type UUID
  • func UUID16(value uint16) UUID
  • func (u UUID) String() string

Variables

var (
	ErrUnavailable  = errors.New("ble unavailable")
	ErrUnauthorized = errors.New("ble unauthorized")
	ErrPoweredOff   = errors.New("ble powered off")
	ErrNotFound     = errors.New("ble peripheral not found")
	ErrDisconnected = errors.New("ble peripheral disconnected")
	ErrClosed       = errors.New("ble peripheral closed")
)

Functions

func Scan

func Scan(ctx context.Context, _ UUID) iter.Seq2[*DeviceInfo, error]

Scan reports that the current platform backend is not implemented.

Types

type Characteristic

type Characteristic interface {
	UUID() UUID
	Properties() CharacteristicProperties
	Read(context.Context) ([]byte, error)
	Write(context.Context, []byte) error
	Subscribe(context.Context) (Subscription, error)
}

Characteristic is one discovered remote GATT characteristic. Write uses a GATT write request and waits for the peripheral's acknowledgement. Read is unavailable while the same characteristic has an active subscription.

type CharacteristicProperties

type CharacteristicProperties uint16

CharacteristicProperties is the Bluetooth Characteristic Properties field.

const (
	// Bit 0 is the Bluetooth Broadcast property, which this client API does not expose.
	CharacteristicPropertyRead CharacteristicProperties = 1 << (iota + 1)
	CharacteristicPropertyWriteWithoutResponse
	CharacteristicPropertyWrite
	CharacteristicPropertyNotify
)

type DeviceInfo

type DeviceInfo struct {
	ID   Identifier
	Name string
	RSSI int
}

DeviceInfo describes one peripheral advertisement.

type Error

type Error struct {
	Operation   string
	Domain      string
	Code        int64
	Description string
	Err         error
}

Error preserves a native Bluetooth error while exposing a portable cause through errors.Is.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type Identifier

type Identifier string

Identifier is an opaque, platform-specific peripheral identifier.

type Peripheral

type Peripheral interface {
	DiscoverServices(context.Context, ...UUID) ([]Service, error)
	io.Closer
}

Peripheral is an owned connection to a remote BLE peripheral.

func Open

func Open(ctx context.Context, _ Identifier) (Peripheral, error)

Open reports that the current platform backend is not implemented.

type Service

type Service interface {
	UUID() UUID
	Primary() bool
	DiscoverCharacteristics(context.Context, ...UUID) ([]Characteristic, error)
}

Service is one discovered remote GATT service.

type Subscription

type Subscription interface {
	Listen() <-chan []byte
	io.Closer
}

Subscription publishes copied notification values in delivery order. If Listen closes unexpectedly, Close returns the terminal error.

type UUID

type UUID [16]byte

UUID is a canonical 128-bit Bluetooth UUID in network byte order.

func UUID16

func UUID16(value uint16) UUID

UUID16 expands a 16-bit Bluetooth UUID into the Bluetooth base UUID.

func (UUID) String

func (u UUID) String() string