ble

package
v0.0.0-...-b1abd1f Latest Latest
Warning

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

 Go to latest Published: Nov 12, 2021 License: Apache-2.0, MIT Imports: 7 Imported by: 2

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 = "00000000-0000-1000-8000-00805F9B34FB"
	//DBUS Interfaces
	ObjectManager           = "org.freedesktop.DBus.ObjectManager"
	AdapterInterface        = "org.bluez.Adapter1"
	DeviceInterface         = "org.bluez.Device1"
	ServiceInterface        = "org.bluez.GattService1"
	CharacteristicInterface = "org.bluez.GattCharacteristic1"
	DescriptorInterface     = "org.bluez.GattDescriptor1"
	DbusProperties          = "org.freedesktop.DBus.Properties"
	DbusIntrospectable      = "org.freedesktop.DBus.Introspectable"

	//DBUS signals
	InterfacesAdded   = "org.freedesktop.DBus.ObjectManager.InterfacesAdded"
	InterfacesRemoved = "org.freedesktop.DBus.ObjectManager.InterfacesRemoved"
	PropertiesChanged = "org.freedesktop.DBus.Properties.PropertiesChanged"

	//DBus signal rules
	AddRule        = "type='signal',interface='org.freedesktop.DBus.ObjectManager',member='InterfacesAdded'"
	RemoveRule     = "type='signal',interface='org.freedesktop.DBus.ObjectManager',member='InterfacesRemoved'"
	PropertiesRule = "type='signal',interface='org.freedesktop.DBus.Properties',member='PropertiesChanged'"

	//BlueZ DBUS Properties
	BluezAdapter             = "Adapter"
	BluezAddress             = "Address"
	BluezAdvertisingFlags    = "AdvertisingFlags"
	BluezAlias               = "Alias"
	BluezAppearance          = "Appearance"
	BluezBlocked             = "Blocked"
	BluezCharacteristic      = "Characteristic"
	BluezClass               = "Class"
	BluezConnected           = "Connected"
	BluezDevice              = "Device"
	BluezDiscoverable        = "Discoverable"
	BluezDiscoverableTimeout = "DiscoverableTimeout"
	BluezDiscovering         = "Discovering"
	BluezFlags               = "Flags"
	BluezIcon                = "Icon"
	BluezIncludes            = "Includes"
	BluezLegacyPairing       = "LegacyPairing"
	BluezManufacturerData    = "ManufacturerData"
	BluezModalias            = "Modalias"
	BluezName                = "Name"
	BluezNotifyAcquired      = "NotifyAcquired"
	BluezNotifying           = "Notifying"
	BluezPairable            = "Pairable"
	BluezPairableTimeout     = "PairableTimeout"
	BluezPaired              = "Paired"
	BluezPowered             = "Powered"
	BluezPrimary             = "Primary"
	BluezRSSI                = "RSSI"
	BluezService             = "Service"
	BluezServiceData         = "ServiceData"
	BluezServicesResolved    = "ServicesResolved"
	BluezTrusted             = "Trusted"
	BluezTxPower             = "TxPower"
	BluezUUID                = "UUID"
	BluezUUIDs               = "UUIDs"
	BluezValue               = "Value"
	BluezWriteAcquired       = "WriteAcquired"

	BleCommandRead  = "read"
	BleCommandWrite = "write"
)

Constants used to reference DBUS specific items

Variables

This section is empty.

Functions

func ConvertUUID 

func ConvertUUID(uuid string) string

ConvertUUID creates the 128 bit representation of a uuid from a 16, 32, or 128 bit uuid

func CreateNewBlob 

func CreateNewBlob() *blob

CreateNewBlob - Creates a new blob instance

func ParseAddressFromPath 

func ParseAddressFromPath(path string) string

ParseAddressFromPath - Extracts the device address from a device path

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(sigChannel chan<- *dbus.Signal, stopDiscoveryChannel <-chan bool, uuids ...string)

	Address() string //The Bluetooth device address - readonly
	Alias() string   //The Bluetooth friendly name - readwrite
	SetAlias(string)
	Class() uint32 //The Bluetooth class of device - readonly
	Powered() bool //Switch an adapter on or off - readwrite
	SetPowered(bool)
	Discoverable() bool //Switch an adapter to discoverable or non-discoverable - readwrite
	SetDiscoverable(bool)
	Pairable() bool //Switch an adapter to pairable or non-pairable - readwrite
	SetPairable(bool)
	PairableTimeout() uint32 //The pairable timeout in seconds - readwrite
	SetPairableTimeout(uint32)
	DiscoverableTimeout() uint32 //The discoverable timeout in seconds - readwrite
	SetDiscoverableTimeout(uint32)
	Discovering() bool //Indicates that a device discovery procedure is active - readonly
	UUIDs() []string   //List of 128-bit UUIDs that represents the available local services - readonly
	Modalias() string  //Local Device ID information in modalias format used by the kernel and udev - readonly, optional
}

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 BaseObject 

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

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

type Characteristic 

type Characteristic interface {
	ReadWriteHandle

	StartNotify() error
	StopNotify() error
	HandleNotify(NotifyHandler) error

	Service() dbus.ObjectPath //Object path of the GATT service the characteristic belongs to - readonly
	Value() []byte            //The cached value of the characteristic - readonly, optional
	WriteAcquired() bool      //True, if this characteristic has been acquired by any client using AcquireWrite - readonly, optional
	NotifyAcquired() bool     //True, if this characteristic has been acquired by any client using AcquireNotify - readonly, optional
	Notifying() bool          //True, if notifications or indications on this characteristic are currently enabled - readonly, optional
	Flags() []string          //Defines how the characteristic value can be used - readonly
}

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) AddMatch 

func (conn *Connection) AddMatch(rule string) error

AddMatch - Adds a signal matching rule to DBUS. Allows a specific type of DBUS signal to be handled within a program.

func (*Connection) Close 

func (conn *Connection) Close()

Close closes the D-Bus connection.

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) GetDevice 

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

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

func (*Connection) GetDeviceByAddress 

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

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

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) GetDevices 

func (conn *Connection) GetDevices(uuids ...string) ([]Device, error)

GetDevices finds all Devices 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) ReadCharacteristic 

func (conn *Connection) ReadCharacteristic(uuid string) ([]byte, error)

ReadCharacteristic reads a Characteristic with the given UUID.

func (*Connection) RemoveMatch 

func (conn *Connection) RemoveMatch(rule string) error

RemoveMatch - Removes a signal matching rule from DBUS.

func (*Connection) StartDiscovery 

func (conn *Connection) StartDiscovery(stopDiscoveryChannel <-chan bool, uuids ...string) chan *dbus.Signal

StartDiscovery - Initiates discovery of LE peripherals with the given UUIDs.

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

func (*Connection) WriteCharacteristic 

func (conn *Connection) WriteCharacteristic(uuid string, value []byte) error

WriteCharacteristic writes a Characteristic with the given UUID.

type Descriptor 

type Descriptor interface {
	ReadWriteHandle

	Characteristic() dbus.ObjectPath //Object path of the GATT characteristic the descriptor belongs to - readonly
	Value() []byte                   //The cached value of the descriptor - readonly, optional
	Flags() []string                 //Defines how the descriptor value can be used - readonly
}

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

type Device 

type Device interface {
	BaseObject

	Connect() error
	Disconnect() error
	ConnectProfile(string) error
	DisconnectProfile(string) error
	Pair() error
	CancelPairing() error

	Address() string                          //The Bluetooth device address of the remote device - readonly
	Name() string                             //The Bluetooth remote name - readonly, optional
	Icon() string                             //Proposed icon name according to the freedesktop.org icon naming specification - readonly, optional
	Class() uint32                            //The Bluetooth class of device - readonly, optional
	Appearance() uint16                       //External appearance of device, as found on GAP service - readonly, optional
	UUIDs() []string                          //List of 128-bit UUIDs that represents the available remote services - readonly, optional
	Paired() bool                             //Indicates if the remote device is paired - readonly
	Connected() bool                          //Indicates if the remote device is currently connec - readonly
	Trusted() bool                            //Indicates if the remote is seen as trusted - readwrite
	SetTrusted(bool)                          //Sets the trusted value
	Blocked() bool                            //If set to true any incoming connections from the device will be immediately rejected - readwrite
	SetBlocked(bool)                          //Sets the blocked value
	Alias() string                            //The name alias for the remote device - readwrite
	SetAlias(string)                          //Sets the device alias
	Adapter() dbus.ObjectPath                 //The object path of the adapter the device belongs to - readonly
	LegacyPairing() bool                      //Set to true if the device only supports the pre-2.1 pairing mechanism
	Modalias() string                         //Remote Device ID information in modalias format used by the kernel and udev - readonly, optional
	RSSI() int16                              //Received Signal Strength Indicator of the remote device - readonly, optional
	TxPower() int16                           //Advertised transmitted power level - readonly, optional
	ManufacturerData() map[string]interface{} //Manufacturer specific advertisement data - readonly, optional
	ServiceData() map[string]interface{}      //Service advertisement data - readonly, optional
	ServicesResolved() bool                   //Indicate whether or not service discovery has been resolved - readonly
	AdvertisingFlags() []byte                 //The Advertising Data Flags of the remote device - readonly, experimental
}

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

type GattHandle 

type GattHandle interface {
	BaseObject

	UUID() string
}

GattHandle is the interface satisfied by GATT handles.

type JSONableSlice 

type JSONableSlice []uint8

func (JSONableSlice) MarshalJSON 

func (u JSONableSlice) MarshalJSON() ([]byte, error)

MarshalJSON - Allows a []byte to be marshalled as an array rather than a string

type NotifyHandler 

type NotifyHandler func([]byte)

NotifyHandler represents a function that handles notifications.

type Properties 

type Properties map[string]dbus.Variant

func GetInterfaceProperties 

func GetInterfaceProperties(s *dbus.Signal) Properties

GetInterfaceProperties If the signal contains deviceInterface, return the corresponding properties, otherwise nil. See http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager

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

	Primary() bool               //Indicates whether or not this GATT service is a primary service - readonly
	Device() dbus.ObjectPath     //Object path of the Bluetooth device the service belongs to - readonly, optional
	Includes() []dbus.ObjectPath //Array of object paths representing the included services of this service - readonly, Currently not implemented in BlueZ
}

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

Source Files

View all Source files

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.