bleclient

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 Bluetooth package.

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

Drivers for several BLE Services can be found in the according driver folder.

How to Install

Please refer to the main README.md

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.

Connect on 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

Connect on 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/drivers/ble"
  "gobot.io/x/gobot/v2/platforms/bleclient"
)

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

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

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

  if err := robot.Start(); err != nil {
		panic(err)
	}
}

Documentation

Overview

Package bleclient provides the Gobot client adaptor for Bluetooth LE.

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

Index

• func WithDebug() debugOption
• func WithScanTimeout(timeout time.Duration) scanTimeoutOption
• type Adaptor
  • func NewAdaptor(identifier string, opts ...optionApplier) *Adaptor
  • func (a *Adaptor) Address() string
  • func (a *Adaptor) Connect() error
  • func (a *Adaptor) Disconnect() error
  • func (a *Adaptor) Finalize() error
  • func (a *Adaptor) Name() string
  • func (a *Adaptor) RSSI() int
  • func (a *Adaptor) ReadCharacteristic(cUUID string) ([]byte, error)
  • func (a *Adaptor) Reconnect() error
  • func (a *Adaptor) SetName(n string)
  • func (a *Adaptor) Subscribe(cUUID string, f func(data []byte)) error
  • func (a *Adaptor) WithoutResponses(bool)
  • func (a *Adaptor) WriteCharacteristic(cUUID string, data []byte) error

Functions

func WithDebug

func WithDebug() debugOption

WithDebug switch on some debug messages.

func WithScanTimeout

func WithScanTimeout(timeout time.Duration) scanTimeoutOption

WithScanTimeout substitute the default scan timeout of 10 min.

Types

type Adaptor

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

Adaptor represents a Client Connection to a BLE Peripheral

func NewAdaptor

func NewAdaptor(identifier string, opts ...optionApplier) *Adaptor

NewAdaptor returns a new Adaptor given an identifier. The identifier can be the address or the name.

Supported options:

"WithAdaptorDebug"
"WithAdaptorScanTimeout"

func (*Adaptor) Address

func (a *Adaptor) Address() string

Address returns the Bluetooth LE address of the device if connected, otherwise the identifier

func (*Adaptor) Connect

func (a *Adaptor) Connect() error

Connect initiates a connection to the BLE peripheral.

func (*Adaptor) Disconnect

func (a *Adaptor) Disconnect() error

Disconnect terminates the connection to the BLE peripheral.

func (*Adaptor) Finalize

func (a *Adaptor) Finalize() error

Finalize finalizes the BLEAdaptor

func (*Adaptor) Name

func (a *Adaptor) Name() string

Name returns the name for the adaptor and after the connection is done, the name of the device

func (*Adaptor) RSSI

func (a *Adaptor) RSSI() int

RSSI returns the Bluetooth LE RSSI value at the moment of connecting the adaptor

func (*Adaptor) ReadCharacteristic

func (a *Adaptor) ReadCharacteristic(cUUID string) ([]byte, error)

ReadCharacteristic returns bytes from the BLE device for the requested characteristic UUID. The UUID can be given as 16-bit or 128-bit (with or without dashes) value.

func (*Adaptor) Reconnect

func (a *Adaptor) Reconnect() 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.

func (*Adaptor) SetName

func (a *Adaptor) SetName(n string)

SetName sets the name for the adaptor

func (*Adaptor) Subscribe

func (a *Adaptor) Subscribe(cUUID string, f func(data []byte)) error

Subscribe subscribes to notifications from the BLE device for the requested characteristic UUID. The UUID can be given as 16-bit or 128-bit (with or without dashes) value.

func (*Adaptor) WithoutResponses

func (a *Adaptor) WithoutResponses(bool)

WithoutResponses sets if the adaptor should expect responses after writing characteristics for this device (has no effect at the moment).

func (*Adaptor) WriteCharacteristic

func (a *Adaptor) WriteCharacteristic(cUUID string, data []byte) error

WriteCharacteristic writes bytes to the BLE device for the requested characteristic UUID. The UUID can be given as 16-bit or 128-bit (with or without dashes) value.