ble

package
v1.13.0 Latest Latest
Warning

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

 Go to latest Published: May 22, 2019 License: Apache-2.0, Apache-2.0 Imports: 10 Imported by: 0

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 ble package by @roylee17. Thank you!

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/...
OSX

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

Ubuntu

Everything should already just compile on most Linux systems.

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.

OSX

To run any of the Gobot BLE code you must use the GODEBUG=cgocheck=0 flag in order to get around some of the issues in the CGo-based implementation.

If you connect by name, then you do not need to worry about the Bluetooth LE ID. However, if you want to connect by ID, OS X uses its own Bluetooth ID system which is different from the IDs used on Linux. The code calls thru the XPC interfaces provided by OSX, so as a result does not need to run under sudo.

For example:

GODEBUG=cgocheck=0 go run examples/minidrone.go 8b2f8032290143e18fc7c426619632e8
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"
	"gobot.io/x/gobot/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 

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 

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

BatteryDriver represents the Battery Service for a BLE Peripheral

func NewBatteryDriver 

func NewBatteryDriver(a BLEConnector) *BatteryDriver

NewBatteryDriver creates a BatteryDriver

func (*BatteryDriver) Connection 

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

Connection returns the Driver's Connection to the associated Adaptor

func (*BatteryDriver) GetBatteryLevel 

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

GetBatteryLevel reads and returns the current battery level

func (*BatteryDriver) Halt 

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

Halt stops battery driver (void)

func (*BatteryDriver) Name 

func (b *BatteryDriver) Name() string

Name returns the Driver name

func (*BatteryDriver) SetName 

func (b *BatteryDriver) SetName(n string)

SetName sets the Driver name

func (*BatteryDriver) Start 

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

Start tells driver to get ready to do work

type ClientAdaptor 

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

ClientAdaptor represents a Client Connection to a BLE Peripheral

func NewClientAdaptor 

func NewClientAdaptor(address string) *ClientAdaptor

NewClientAdaptor returns a new ClientAdaptor given an address or peripheral name

func (*ClientAdaptor) Address 

func (b *ClientAdaptor) Address() string

Address returns the Bluetooth LE address for the adaptor

func (*ClientAdaptor) Connect 

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

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

func (*ClientAdaptor) Disconnect 

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

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

func (*ClientAdaptor) Finalize 

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

Finalize finalizes the BLEAdaptor

func (*ClientAdaptor) Name 

func (b *ClientAdaptor) Name() string

Name returns the name for the adaptor

func (*ClientAdaptor) ReadCharacteristic 

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 

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 

func (b *ClientAdaptor) SetName(n string)

SetName sets the name for the adaptor

func (*ClientAdaptor) Subscribe 

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 

func (b *ClientAdaptor) WithoutResponses(use bool)

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

func (*ClientAdaptor) WriteCharacteristic 

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 

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

DeviceInformationDriver represents the Device Information Service for a BLE Peripheral

func NewDeviceInformationDriver 

func NewDeviceInformationDriver(a BLEConnector) *DeviceInformationDriver

NewDeviceInformationDriver creates a DeviceInformationDriver

func (*DeviceInformationDriver) Connection 

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

Connection returns the Driver's Connection to the associated Adaptor

func (*DeviceInformationDriver) GetFirmwareRevision 

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

GetFirmwareRevision returns the firmware revision for the BLE Peripheral

func (*DeviceInformationDriver) GetHardwareRevision 

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

GetHardwareRevision returns the hardware revision for the BLE Peripheral

func (*DeviceInformationDriver) GetManufacturerName 

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

GetManufacturerName returns the manufacturer name for the BLE Peripheral

func (*DeviceInformationDriver) GetModelNumber 

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

GetModelNumber returns the model number for the BLE Peripheral

func (*DeviceInformationDriver) GetPnPId 

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

GetPnPId returns the PnP ID for the BLE Peripheral

func (*DeviceInformationDriver) Halt 

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

Halt stops driver (void)

func (*DeviceInformationDriver) Name 

func (b *DeviceInformationDriver) Name() string

Name returns the Driver name

func (*DeviceInformationDriver) SetName 

func (b *DeviceInformationDriver) SetName(n string)

SetName sets the Driver name

func (*DeviceInformationDriver) Start 

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

Start tells driver to get ready to do work

type GenericAccessDriver 

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

GenericAccessDriver represents the Generic Access Service for a BLE Peripheral

func NewGenericAccessDriver 

func NewGenericAccessDriver(a BLEConnector) *GenericAccessDriver

NewGenericAccessDriver creates a GenericAccessDriver

func (*GenericAccessDriver) Connection 

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

Connection returns the Driver's Connection to the associated Adaptor

func (*GenericAccessDriver) GetAppearance 

func (b *GenericAccessDriver) GetAppearance() string

GetAppearance returns the appearance string for the BLE Peripheral

func (*GenericAccessDriver) GetDeviceName 

func (b *GenericAccessDriver) GetDeviceName() string

GetDeviceName returns the device name for the BLE Peripheral

func (*GenericAccessDriver) Halt 

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

Halt stops driver (void)

func (*GenericAccessDriver) Name 

func (b *GenericAccessDriver) Name() string

Name returns the Driver name

func (*GenericAccessDriver) SetName 

func (b *GenericAccessDriver) SetName(n string)

SetName sets the Driver name

func (*GenericAccessDriver) Start 

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

Start tells driver to get ready to do work

type SerialPort 

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 

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

NewSerialPort returns a new serial over Bluetooth LE connection

func (*SerialPort) Address 

func (p *SerialPort) Address() string

Address returns the BLE address

func (*SerialPort) Close 

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

Close closes the BLE serial port connection

func (*SerialPort) Open 

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

Open opens a connection to a BLE serial device

func (*SerialPort) Read 

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

Read reads bytes from BLE serial port connection

func (*SerialPort) Write 

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.