ble

package module
v0.0.0-...-836931e Latest Latest
Warning

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

 Go to latest Published: Jun 11, 2020 License: MIT Imports: 7 Imported by: 8

README

Package ble provides functions to discover, connect, pair, and communicate with Bluetooth Low Energy peripheral devices.

Documentation: https://godoc.org/github.com/ecc1/ble

This implementation uses the BlueZ D-Bus interface, rather than sockets. It is similar to https://github.com/adafruit/Adafruit_Python_BluefruitLE

The apps directory contains some simple example programs.

Some older Linux kernels, like the one on the Intel Edison, may not properly support the SetDiscoveryFilter method. The ble package can be built with the "nofilter" tag to work around this.

Documentation

Overview

Package ble provides functions to discover, connect, pair, and communicate with Bluetooth Low Energy peripheral devices.

This implementation uses the BlueZ D-Bus interface, rather than sockets. It is similar to github.com/adafruit/Adafruit_Python_BluefruitLE

Index

Constants

View Source 
const (
	// BluetoothBaseUUID for service discovery.
	// See www.bluetooth.com/specifications/assigned-numbers/service-discovery
	BluetoothBaseUUID = "0000xxxx-0000-1000-8000-00805f9b34fb"
)
View Source 
const (
	// GATTMTU is the maximum size of a write to a GATT characteristic.
	GATTMTU = 20
)

Variables

This section is empty.

Functions

func LongUUID 

func LongUUID(u string) string

LongUUID returns the 128-bit UUID corresponding to a possibly-shorter UUID, which must be valid.

func ShortUUID 

func ShortUUID(u string) string

ShortUUID returns the shortest UUID corresponding to the given UUID, which must be valid.

func UUIDsInclude 

func UUIDsInclude(advertised []string, uuids []string) bool

UUIDsInclude tests whether the advertised UUIDs contain all of the ones in uuids.

func ValidAddress 

func ValidAddress(addr string) bool

ValidAddress checks whether addr is a valid MAC address.

func ValidUUID 

func ValidUUID(u string) bool

ValidUUID checks whether a string is a valid UUID.

Types

type Adapter 

type Adapter interface {
	BaseObject

	StartDiscovery() error
	StopDiscovery() error
	RemoveDevice(Device) error
	SetDiscoveryFilter(uuids ...string) error

	Discover(timeout time.Duration, uuids ...string) error
}

The Adapter type corresponds to the org.bluez.Adapter1 interface. See bluez/doc/adapter-api.txt

StartDiscovery starts discovery on the adapter.

StopDiscovery stops discovery on the adapter.

RemoveDevice removes the specified device and its pairing information.

SetDiscoveryFilter sets the discovery filter to require LE transport and the given UUIDs.

Discover performs discovery for a device with the given UUIDs, for at most the specified timeout, or indefinitely if timeout is 0. See also the Discover method of the ObjectCache type.

type Address 

type Address string

Address represents a MAC address.

type BaseObject 

type BaseObject interface {
	Conn() *Connection
	Path() dbus.ObjectPath
	Interface() string
	Name() string
	Print(io.Writer)
}

BaseObject is the interface satisfied by bluez D-Bus objects.

type Characteristic 

type Characteristic interface {
	ReadWriteHandle

	Notifying() bool

	StartNotify() error
	StopNotify() error

	HandleNotify(NotifyHandler) error
}

Characteristic corresponds to the org.bluez.GattCharacteristic1 interface. See bluez/doc/gatt-api.txt

type Connection 

type Connection struct {
	// contains filtered or unexported fields
}

Connection represents a D-Bus connection.

func Open 

func Open() (*Connection, error)

Open opens a connection to the system D-Bus

func (*Connection) Close 

func (conn *Connection) Close()

Close closes the D-Bus connection.

func (*Connection) Discover 

func (conn *Connection) Discover(timeout time.Duration, address Address, uuids ...string) (Device, error)

Discover initiates discovery for a LE peripheral with the given address (if nonempty), advertising the given UUIDs. It waits for at most the specified timeout, or indefinitely if timeout = 0.

func (*Connection) GetAdapter 

func (conn *Connection) GetAdapter() (Adapter, error)

GetAdapter finds an Adapter in the object cache and returns it.

func (*Connection) GetCharacteristic 

func (conn *Connection) GetCharacteristic(uuid string) (Characteristic, error)

GetCharacteristic finds a Characteristic with the given UUID.

func (*Connection) GetDescriptor 

func (conn *Connection) GetDescriptor(uuid string) (Descriptor, error)

GetDescriptor finds a Descriptor with the given UUID.

func (*Connection) GetDeviceByAddress 

func (conn *Connection) GetDeviceByAddress(address Address) (Device, error)

GetDeviceByAddress finds a Device in the object cache with the given address.

func (*Connection) GetDeviceByName 

func (conn *Connection) GetDeviceByName(name string) (Device, error)

GetDeviceByName finds a Device in the object cache with the given name.

func (*Connection) GetDeviceByUUID 

func (conn *Connection) GetDeviceByUUID(uuids ...string) (Device, error)

GetDeviceByUUID finds a Device in the object cache matching the given UUIDs.

func (*Connection) GetService 

func (conn *Connection) GetService(uuid string) (Service, error)

GetService finds a Service with the given UUID.

func (*Connection) HandleNotify 

func (conn *Connection) HandleNotify(uuid string, handler NotifyHandler) error

HandleNotify enables notifications from the GATT characterisitc with the specified UUID and applies the given handler to them when they arrive.

func (*Connection) Print 

func (conn *Connection) Print(w io.Writer)

Print prints the objects in the cache.

func (*Connection) Update 

func (conn *Connection) Update() error

Update gets all objects and properties. See http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager

type Descriptor 

type Descriptor interface {
	ReadWriteHandle
}

Descriptor corresponds to the org.bluez.GattDescriptor1 interface. See bluez/doc/gatt-api.txt

type Device 

type Device interface {
	BaseObject

	Address() Address
	AddressType() string
	UUIDs() []string
	Connected() bool
	Paired() bool

	Connect() error
	Disconnect() error
	Pair() error
}

The Device type corresponds to the org.bluez.Device1 interface. See bluez/doc/devicet-api.txt

type DiscoveryTimeoutError 

type DiscoveryTimeoutError []string

DiscoveryTimeoutError indicates that discovery has timed out.

func (DiscoveryTimeoutError) Error 

func (e DiscoveryTimeoutError) Error() string

type GattHandle 

type GattHandle interface {
	BaseObject

	UUID() string
}

GattHandle is the interface satisfied by GATT handles.

type NotifyHandler 

type NotifyHandler func([]byte)

NotifyHandler represents a function that handles notifications.

type Object 

type Object = map[string]Properties

Object represents a managed D-Bus object as a map from interface names to properties.

type Properties 

type Properties = map[string]dbus.Variant

Properties represents a dbus interface as a map from property names to values (D-Bus variants).

type ReadWriteHandle 

type ReadWriteHandle interface {
	GattHandle

	ReadValue() ([]byte, error)
	WriteValue([]byte) error
}

ReadWriteHandle is the interface satisfied by GATT objects that provide ReadValue and WriteValue operations.

type Service 

type Service interface {
	GattHandle
}

Service corresponds to the org.bluez.GattService1 interface. See bluez/doc/gatt-api.txt

type UUIDs 

type UUIDs []string

UUIDs represents a list of UUIDs.

func (UUIDs) String 

func (uuids UUIDs) String() string

The String method allows a list of UUIDs to be printed in short form.

Source Files

View all Source files

Directories

Path Synopsis
cmd
adapter
connect
device
disconnect
discover
objects
pair

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.