ble

package
v0.0.0-...-ea8db31 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 3, 2026 License: Apache-2.0 Imports: 13 Imported by: 1

Documentation

Index

Examples

Constants

View Source 
const (
	// DefaultScanTimeout is the default duration for scanning.
	DefaultScanTimeout = time.Duration(5 * time.Second)
)
View Source 
const (
	// DefaultTransportTimeout is the default timeout for transport operations.
	DefaultTransportTimeout = 5 * time.Second
)
View Source 
const (
	Version = ".."
)

Variables

View Source 
var (
	// ErrNotConnected indicates that the device is not connected.
	ErrNotConnected = errors.New("not connected")
	// ErrNotSet indicates that the value is not set.
	ErrNotSet = errors.New("not set")
	// ErrInvalid indicates that the value is invalid.
	ErrInvalid = errors.New("invalid")
	// ErrNotFound indicates that the value was not found.
	ErrNotFound = errors.New("not found")
)

Functions

func DefaultDatabase 

func DefaultDatabase() db.Database

DefaultDatabase returns the default database instance.

Types

type Address 

type Address []byte

Address represents a Bluetooth address.

func (Address) String 

func (addr Address) String() string

String returns the string representation of the Bluetooth address.

type Central 

type Central interface {
	Scanner
	// Connect connects to the specified device.
	Connect(ctx context.Context, dev Device) error
}

Central represents a Bluetooth central device.

func NewCentral 

func NewCentral() Central

NewCentral creates a new Bluetooth central device.

type Characteristic 

type Characteristic interface {
	// CharacteristicDescriptor represents a Bluetooth Characteristic Descriptor.
	CharacteristicDescriptor
	// CharacteristicOperator represents operations that can be performed on a Bluetooth Characteristic.
	CharacteristicOperator
	// MarshalObject returns an object suitable for marshaling to JSON.
	MarshalObject() any
	// String returns a string representation of the characteristic.
	String() string
}

Characteristic represents a Bluetooth Characteristic.

type CharacteristicDescriptor 

type CharacteristicDescriptor interface {
	// Service returns the service that the characteristic belongs to.
	Service() Service
	// UUID returns the Characteristic UUID.
	UUID() UUID
	// Name returns the Characteristic name.
	Name() string
	// ID returns the Characteristic ID.
	ID() string
}

CharacteristicDescriptor represents a Bluetooth Characteristic Descriptor.

type CharacteristicOperator 

type CharacteristicOperator interface {
	// Read reads the characteristic value.
	Read() ([]byte, error)
	// Write writes the characteristic value.
	Write([]byte) (int, error)
	// WriteWithoutResponse writes the characteristic value without waiting for a response.
	WriteWithoutResponse([]byte) (int, error)
	// Notify subscribes to characteristic notifications.
	Notify(OnCharacteristicNotification) error
}

CharacteristicOperator represents operations that can be performed on a Bluetooth Characteristic.

type Device 

type Device interface {
	// DeviceDescriptor returns the read-only device descriptor.
	DeviceDescriptor
	// DeviceOperator returns the device operator.
	DeviceOperator
	// String returns a string representation of the device.
	String() string
}

Device represents a Bluetooth device.

type DeviceDescriptor 

type DeviceDescriptor interface {
	// Manufacturer returns the Bluetooth manufacturer of the device.
	Manufacturer() Manufacturer
	// LocalName returns the local name of the device.
	LocalName() string
	// Address returns the Bluetooth address of the device.
	Address() Address
	// Services returns the Bluetooth services of the device.
	Services() []Service
	// RSSI returns the received signal strength indicator of the device.
	RSSI() int
	// DiscoveredAt returns the time when the device was first discovered.
	DiscoveredAt() time.Time
	// ModifiedAt returns the time when the device was last modified.
	ModifiedAt() time.Time
	// LastSeenAt returns the time when the device was last seen.
	LastSeenAt() time.Time
}

DeviceDescriptor represents a read-only Bluetooth device descriptor.

type DeviceOperator 

type DeviceOperator interface {
	// Connect connects to the device.
	Connect(ctx context.Context) error
	// Disconnect disconnects from the device.
	Disconnect() error
	// IsConnected returns whether the device is connected.
	IsConnected() bool
	// LookupService looks up a service by its UUID. The UUID can be of any type accepted such as string, uint16, uint32, []byte, or UUID.
	LookupService(uuid any) (Service, bool)
}

DeviceOperator represents a Bluetooth device operator.

type Manufacturer 

type Manufacturer interface {
	// ID returns the company ID.
	ID() int
	// Name returns the company name.
	Name() string
	// Data returns the manufacturer specific data.
	Data() []byte
	// MarshalObject returns an object suitable for marshaling to JSON.
	MarshalObject() any
	// String returns a string representation of the manufacturer.
	String() string
}

Manufacturer represents a Bluetooth manufacturer.

type OnCharacteristicNotification 

type OnCharacteristicNotification func(char Characteristic, buf []byte)

OnCharacteristicNotification represents a callback function to be called when a notification is received.

type ScanHandler 

type ScanHandler func(Device)

ScanHandler defines a handler function for scan results.

type Scanner 

type Scanner interface {
	// Devices returns the list of discovered devices.
	Devices() []Device
	// Scan starts scanning for Bluetooth devices.
	Scan(ctx context.Context, opts ...ScannerOption) error
}

Scanner defines the interface for a Bluetooth scanner.

Example 
package main

import (
	"context"
	"time"

	"github.com/cybergarage/go-ble/ble"
	"github.com/cybergarage/go-logger/log"
)

func main() {
	scanner := ble.NewScanner()

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

	err := scanner.Scan(ctx,
		ble.ScanHandler(func(dev ble.Device) {
			log.Infof("Device found: dev=%s", dev.String())
		}))
	if err != nil {
		log.Errorf("Failed to scan: %v", err)
	}

	for n, dev := range scanner.Devices() {
		log.Infof("[%d] %s", n, dev.String())
	}
}
Example (Matter) 
package main

import (
	"context"
	"fmt"
	"time"

	"github.com/cybergarage/go-ble/ble"
)

func main() {
	scanner := ble.NewScanner()
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()
	scanner.Scan(ctx)
	lookupMatterDevices := func(devs []ble.Device, targetDisc uint16) (ble.Device, bool) {
		for _, dev := range devs {
			if service, ok := dev.LookupService(0xFFF6); ok {
				if 3 <= len(service.Data()) {
					serviceDisc := uint16(service.Data()[1]) | (uint16(service.Data()[2]) << 8)
					if serviceDisc == targetDisc {
						return dev, true
					}
				}
			}
		}
		return nil, false
	}
	targetDisc := uint16(4068)
	dev, ok := lookupMatterDevices(scanner.Devices(), targetDisc)
	if ok {
		fmt.Printf("Matter device found: %s", dev.String())
	}
}

func NewScanner 

func NewScanner() Scanner

NewScanner creates a new Bluetooth scanner.

type ScannerOption 

type ScannerOption any

ScannerOption represents an option for the scanner.

type Service 

type Service interface {
	// ServiceDescriptor represents a Bluetooth service descriptor.
	ServiceDescriptor
	// ServiceOperator represents a Bluetooth service operator.
	ServiceOperator
	// MarshalObject returns an object suitable for marshaling to JSON.
	MarshalObject() any
	// String returns a string representation of the service.
	String() string
}

Service represents a Bluetooth service.

type ServiceDescriptor 

type ServiceDescriptor interface {
	// Device returns the device that the service belongs to.
	Device() Device
	// UUID returns the UUID of the service.
	UUID() UUID
	// Name returns the name of the service.
	Name() string
	// Data returns the data of the service.
	Data() []byte
	// LookupCharacteristic looks up a characteristic by UUID.
	LookupCharacteristic(uuid any) (Characteristic, bool)
	// Characteristics returns the characteristics of the service.
	Characteristics() []Characteristic
}

ServiceDescriptor represents a Bluetooth service descriptor.

type ServiceOperator 

type ServiceOperator interface {
	// Open opens a transport on the service with the specified options.
	Open(opts ...ServiceTransportOption) (Transport, error)
}

ServiceOperator represents a Bluetooth service operator.

type ServiceTransportOption 

type ServiceTransportOption func(*serviceTransportUUIDs)

ServiceTransportOption represents options for opening a transport on a service.

func WithTransportNotifyUUID 

func WithTransportNotifyUUID(uuid UUID) ServiceTransportOption

WithTransportNotifyUUID sets the notify UUID for the service transport.

func WithTransportReadUUID 

func WithTransportReadUUID(uuid UUID) ServiceTransportOption

WithTransportReadUUID sets the read UUID for the service transport.

func WithTransportWriteUUID 

func WithTransportWriteUUID(uuid UUID) ServiceTransportOption

WithTransportWriteUUID sets the write UUID for the service transport.

type Transport 

type Transport interface {
	// Open opens the transport for communication.
	Open() error
	// Close closes the transport and releases resources.
	Close() error
	// WriterCharacteristic returns the characteristic used for writing data.
	WriteCharacteristic() (Characteristic, error)
	// ReadCharacteristic returns the characteristic used for reading data.
	ReadCharacteristic() (Characteristic, error)
	// NotifyCharacteristic returns the characteristic used for notifications.
	NotifyCharacteristic() (Characteristic, error)
	// Read reads bytes from the transport.
	Read(ctx context.Context) ([]byte, error)
	// Write writes the specified bytes to the transport.
	Write(ctx context.Context, data []byte) (int, error)
	// WriteWithoutResponse writes the specified bytes to the transport without waiting for a response.
	WriteWithoutResponse(ctx context.Context, data []byte) (int, error)
}

Transport represents the BLE transport layer.

func NewTransport 

func NewTransport(opts ...TransportOption) Transport

NewTransport returns a new Transport instance.

type TransportOption 

type TransportOption func(*transport)

TransportOption represents a function type to set transport options.

func WithTransportNotifyCharacteristic 

func WithTransportNotifyCharacteristic(char Characteristic) TransportOption

WithTransportNotifyCharacteristic sets the characteristic used for notifications.

func WithTransportReadCharacteristic 

func WithTransportReadCharacteristic(char Characteristic) TransportOption

WithTransportReadCharacteristic sets the characteristic used for reading data.

func WithTransportWriteCharacteristic 

func WithTransportWriteCharacteristic(char Characteristic) TransportOption

WithTransportWriteCharacteristic sets the characteristic used for writing data.

type UUID 

type UUID = types.UUID

UUID represents a Bluetooth UUID.

func MustUUIDFrom 

func MustUUIDFrom(v any) UUID

MustUUIDFrom creates a UUID from various types and return nil UUID if it fails.

func MustUUIDFromString 

func MustUUIDFromString(s string) UUID

MustUUIDFromString creates a UUID from a string representation and return nil UUID if it fails.

func NewNilUUID 

func NewNilUUID() UUID

NewNilUUID creates a nil UUID.

func NewUUIDFrom 

func NewUUIDFrom(v any) (UUID, error)

NewUUIDFrom creates a UUID from various types.

func NewUUIDFromBytes 

func NewUUIDFromBytes(b []byte) (UUID, error)

NewUUIDFromBytes creates a UUID from a byte slice.

func NewUUIDFromString 

func NewUUIDFromString(s string) (UUID, error)

NewUUIDFromString creates a new UUID from the given UUID string.

func NewUUIDFromUUID16 

func NewUUIDFromUUID16(u uint16) UUID

NewUUIDFromUUID16 creates a new UUID from the given 16-bit UUID.

Source Files

View all Source files

Directories

Path Synopsis
db
ext

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.