ble

package
v2.0.0+incompatible Latest Latest
Warning

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

 Go to latest Published: May 28, 2023 License: Apache-2.0, Apache-2.0 Imports: 10 Imported by: 284

README

Bluetooth LE

The Gobot BLE adaptor makes it easy to interact with Bluetooth LE aka Bluetooth 4.0 using Go.

It is written using the TinyGo Bluetooh package.

Learn more about Bluetooth LE at http://en.wikipedia.org/wiki/Bluetooth_low_energy

This package also includes drivers for several well-known BLE Services:

  • Battery Service
  • Device Information Service
  • Generic Access Service

How to Install

go get -d -u gobot.io/x/gobot/v2/...
macOS

You need to have XCode installed to be able to compile code that uses the Gobot BLE adaptor on macOS. This is because the bluetooth package uses a CGo based implementation.

Ubuntu

Everything should already just compile on most Linux systems.

Windows

You will need to have a GCC compiler such as mingw-w64 installed in order to use BLE on Windows.

How To Connect

When using BLE a "peripheral" aka "server" is something you connect to such a a pulse meter. A "central" aka "client" is what does the connecting, such as your computer or mobile phone.

You need to know the BLE ID of the peripheral you want to connect to. The Gobot BLE client adaptor also lets you connect to a peripheral by friendly name.

Ubuntu

On Linux the BLE code will need to run as a root user account. The easiest way to accomplish this is probably to use go build to build your program, and then to run the requesting executable using sudo.

For example:

go build examples/minidrone.go
sudo ./minidrone AA:BB:CC:DD:EE
Windows

Hopefully coming soon...

How to Use

Here is an example that uses the BLE "Battery" service to retrieve the current change level of the peripheral device:

package main

import (
	"fmt"
	"os"
	"time"

	"gobot.io/x/gobot/v2"
	"gobot.io/x/gobot/v2/platforms/ble"
)

func main() {
	bleAdaptor := ble.NewClientAdaptor(os.Args[1])
	battery := ble.NewBatteryDriver(bleAdaptor)

	work := func() {
		gobot.Every(5*time.Second, func() {
			fmt.Println("Battery level:", battery.GetBatteryLevel())
		})
	}

	robot := gobot.NewRobot("bleBot",
		[]gobot.Connection{bleAdaptor},
		[]gobot.Device{battery},
		work,
	)

	robot.Start()
}

Documentation

Overview

Package ble provides the Gobot adaptor for Bluetooth LE.

It also includes drivers for several well-known BLE Services:

- Battery Service - Device Information Service - Generic Access Service

For more information refer to the README: https://github.com/hybridgroup/gobot/blob/master/platforms/ble/README.md

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BLEConnector added in v1.4.0 

type BLEConnector interface {
	Connect() error
	Reconnect() error
	Disconnect() error
	Finalize() error
	Name() string
	SetName(string)
	Address() string
	ReadCharacteristic(string) ([]byte, error)
	WriteCharacteristic(string, []byte) error
	Subscribe(string, func([]byte, error)) error
	WithoutResponses(bool)
}

BLEConnector is the interface that a BLE ClientAdaptor must implement

type BatteryDriver added in v1.0.0 

type BatteryDriver struct {
	gobot.Eventer
	// contains filtered or unexported fields
}

BatteryDriver represents the Battery Service for a BLE Peripheral

func NewBatteryDriver added in v1.0.0 

func NewBatteryDriver(a BLEConnector) *BatteryDriver

NewBatteryDriver creates a BatteryDriver

func (*BatteryDriver) Connection added in v1.0.0 

func (b *BatteryDriver) Connection() gobot.Connection

Connection returns the Driver's Connection to the associated Adaptor

func (*BatteryDriver) GetBatteryLevel added in v1.0.0 

func (b *BatteryDriver) GetBatteryLevel() (level uint8)

GetBatteryLevel reads and returns the current battery level

func (*BatteryDriver) Halt added in v1.0.0 

func (b *BatteryDriver) Halt() (err error)

Halt stops battery driver (void)

func (*BatteryDriver) Name added in v1.0.0 

func (b *BatteryDriver) Name() string

Name returns the Driver name

func (*BatteryDriver) SetName added in v1.0.0 

func (b *BatteryDriver) SetName(n string)

SetName sets the Driver name

func (*BatteryDriver) Start added in v1.0.0 

func (b *BatteryDriver) Start() (err error)

Start tells driver to get ready to do work

type ClientAdaptor added in v1.0.0 

type ClientAdaptor struct {
	AdapterName string
	// contains filtered or unexported fields
}

ClientAdaptor represents a Client Connection to a BLE Peripheral

func NewClientAdaptor added in v1.0.0 

func NewClientAdaptor(address string) *ClientAdaptor

NewClientAdaptor returns a new ClientAdaptor given an address

func (*ClientAdaptor) Address added in v1.2.0 

func (b *ClientAdaptor) Address() string

Address returns the Bluetooth LE address for the adaptor

func (*ClientAdaptor) Connect added in v1.0.0 

func (b *ClientAdaptor) Connect() (err error)

Connect initiates a connection to the BLE peripheral. Returns true on successful connection.

func (*ClientAdaptor) Disconnect added in v1.0.0 

func (b *ClientAdaptor) Disconnect() (err error)

Disconnect terminates the connection to the BLE peripheral. Returns true on successful disconnect.

func (*ClientAdaptor) Finalize added in v1.0.0 

func (b *ClientAdaptor) Finalize() (err error)

Finalize finalizes the BLEAdaptor

func (*ClientAdaptor) Name added in v1.0.0 

func (b *ClientAdaptor) Name() string

Name returns the name for the adaptor

func (*ClientAdaptor) ReadCharacteristic added in v1.0.0 

func (b *ClientAdaptor) ReadCharacteristic(cUUID string) (data []byte, err error)

ReadCharacteristic returns bytes from the BLE device for the requested characteristic uuid

func (*ClientAdaptor) Reconnect added in v1.0.0 

func (b *ClientAdaptor) Reconnect() (err error)

Reconnect attempts to reconnect to the BLE peripheral. If it has an active connection it will first close that connection and then establish a new connection. Returns true on Successful reconnection

func (*ClientAdaptor) SetName added in v1.0.0 

func (b *ClientAdaptor) SetName(n string)

SetName sets the name for the adaptor

func (*ClientAdaptor) Subscribe added in v1.0.0 

func (b *ClientAdaptor) Subscribe(cUUID string, f func([]byte, error)) (err error)

Subscribe subscribes to notifications from the BLE device for the requested service and characteristic

func (*ClientAdaptor) WithoutResponses added in v1.12.0 

func (b *ClientAdaptor) WithoutResponses(use bool)

WithoutResponses sets if the adaptor should expect responses after writing characteristics for this device

func (*ClientAdaptor) WriteCharacteristic added in v1.0.0 

func (b *ClientAdaptor) WriteCharacteristic(cUUID string, data []byte) (err error)

WriteCharacteristic writes bytes to the BLE device for the requested service and characteristic

type DeviceInformationDriver added in v1.0.0 

type DeviceInformationDriver struct {
	gobot.Eventer
	// contains filtered or unexported fields
}

DeviceInformationDriver represents the Device Information Service for a BLE Peripheral

func NewDeviceInformationDriver added in v1.0.0 

func NewDeviceInformationDriver(a BLEConnector) *DeviceInformationDriver

NewDeviceInformationDriver creates a DeviceInformationDriver

func (*DeviceInformationDriver) Connection added in v1.0.0 

func (b *DeviceInformationDriver) Connection() gobot.Connection

Connection returns the Driver's Connection to the associated Adaptor

func (*DeviceInformationDriver) GetFirmwareRevision added in v1.0.0 

func (b *DeviceInformationDriver) GetFirmwareRevision() (revision string)

GetFirmwareRevision returns the firmware revision for the BLE Peripheral

func (*DeviceInformationDriver) GetHardwareRevision added in v1.0.0 

func (b *DeviceInformationDriver) GetHardwareRevision() (revision string)

GetHardwareRevision returns the hardware revision for the BLE Peripheral

func (*DeviceInformationDriver) GetManufacturerName added in v1.0.0 

func (b *DeviceInformationDriver) GetManufacturerName() (manufacturer string)

GetManufacturerName returns the manufacturer name for the BLE Peripheral

func (*DeviceInformationDriver) GetModelNumber added in v1.0.0 

func (b *DeviceInformationDriver) GetModelNumber() (model string)

GetModelNumber returns the model number for the BLE Peripheral

func (*DeviceInformationDriver) GetPnPId added in v1.0.0 

func (b *DeviceInformationDriver) GetPnPId() (model string)

GetPnPId returns the PnP ID for the BLE Peripheral

func (*DeviceInformationDriver) Halt added in v1.0.0 

func (b *DeviceInformationDriver) Halt() (err error)

Halt stops driver (void)

func (*DeviceInformationDriver) Name added in v1.0.0 

func (b *DeviceInformationDriver) Name() string

Name returns the Driver name

func (*DeviceInformationDriver) SetName added in v1.0.0 

func (b *DeviceInformationDriver) SetName(n string)

SetName sets the Driver name

func (*DeviceInformationDriver) Start added in v1.0.0 

func (b *DeviceInformationDriver) Start() (err error)

Start tells driver to get ready to do work

type GenericAccessDriver added in v1.1.0 

type GenericAccessDriver struct {
	gobot.Eventer
	// contains filtered or unexported fields
}

GenericAccessDriver represents the Generic Access Service for a BLE Peripheral

func NewGenericAccessDriver added in v1.1.0 

func NewGenericAccessDriver(a BLEConnector) *GenericAccessDriver

NewGenericAccessDriver creates a GenericAccessDriver

func (*GenericAccessDriver) Connection added in v1.1.0 

func (b *GenericAccessDriver) Connection() gobot.Connection

Connection returns the Driver's Connection to the associated Adaptor

func (*GenericAccessDriver) GetAppearance added in v1.1.0 

func (b *GenericAccessDriver) GetAppearance() string

GetAppearance returns the appearance string for the BLE Peripheral

func (*GenericAccessDriver) GetDeviceName added in v1.1.0 

func (b *GenericAccessDriver) GetDeviceName() string

GetDeviceName returns the device name for the BLE Peripheral

func (*GenericAccessDriver) Halt added in v1.1.0 

func (b *GenericAccessDriver) Halt() (err error)

Halt stops driver (void)

func (*GenericAccessDriver) Name added in v1.1.0 

func (b *GenericAccessDriver) Name() string

Name returns the Driver name

func (*GenericAccessDriver) SetName added in v1.1.0 

func (b *GenericAccessDriver) SetName(n string)

SetName sets the Driver name

func (*GenericAccessDriver) Start added in v1.1.0 

func (b *GenericAccessDriver) Start() (err error)

Start tells driver to get ready to do work

type SerialPort added in v1.2.0 

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

SerialPort is a implementation of serial over Bluetooth LE Inspired by https://github.com/monteslu/ble-serial by @monteslu

func NewSerialPort added in v1.2.0 

func NewSerialPort(address string, rid string, tid string) *SerialPort

NewSerialPort returns a new serial over Bluetooth LE connection

func (*SerialPort) Address added in v1.2.0 

func (p *SerialPort) Address() string

Address returns the BLE address

func (*SerialPort) Close added in v1.2.0 

func (p *SerialPort) Close() (err error)

Close closes the BLE serial port connection

func (*SerialPort) Open added in v1.2.0 

func (p *SerialPort) Open() (err error)

Open opens a connection to a BLE serial device

func (*SerialPort) Read added in v1.2.0 

func (p *SerialPort) Read(b []byte) (n int, err error)

Read reads bytes from BLE serial port connection

func (*SerialPort) Write added in v1.2.0 

func (p *SerialPort) Write(b []byte) (n int, err error)

Write writes to the BLE serial port connection

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.