fork of the tinygo bluetooth library with some bad ideas implemented
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
kayos@tcp.direct 8aacde8b78
Merge branch 'upstream' into release
1 month ago
.circleci macos: update xcode in use to 10.3.0 1 year ago
data gen: generate standard service and characteristic UUIDs from Nordic Semiconductor bluetooth numbers database 2 years ago
examples updating URLs for fork 1 month ago
images docs: adding go bluetooth gopher 2 years ago
rawterm examples: let macos use rawterm to compile nusclient 2 years ago
s110_nrf51_8.0.0 Add S110 version 8.0.0 SoftDevice for nrf51822 2 years ago
s113_nrf52_7.0.1 nrf: add support for S113 SoftDevice 1 year ago
s132_nrf52_6.1.1 Initial commit 3 years ago
s140_nrf52_6.1.1 nrf52: add support for S140 version 6 2 years ago
s140_nrf52_7.3.0 nrf: update s140v7 SoftDevice version to latest, 7.3.0 11 months ago
tools updating URLs for fork 1 month ago
winbt updating URLs for fork 1 month ago
.gitattributes Initial commit 3 years ago
.gitignore nrf52: add support for S140 version 6 2 years ago
CHANGELOG.md all: prepare for release 0.5.0 5 months ago
CONTRIBUTING.md docs: update README with lots of info/organization and also add CONTRIBUTING guidelines 2 years ago
LICENSE docs: update license year 5 months ago
Makefile nrf: add support for S113 SoftDevice 1 year ago
README.md updating URLs for fork 1 month ago
adapter.go gap: add connection handler to be called on adapter connect/disconnect 2 years ago
adapter_darwin.go darwin: make Adapter.Connect thread-safe 1 year ago
adapter_linux.go Update fork from upstream 1 month ago
adapter_nrf51.go Add //go:build lines for Go 1.18 5 months ago
adapter_nrf528xx-full.go Add //go:build lines for Go 1.18 5 months ago
adapter_nrf528xx-peripheral.go Add //go:build lines for Go 1.18 5 months ago
adapter_nrf528xx.go Add //go:build lines for Go 1.18 5 months ago
adapter_s110.c nrf: add GATT client 2 years ago
adapter_s110.go Add //go:build lines for Go 1.18 5 months ago
adapter_s113v7.c nrf: add support for S113 SoftDevice 1 year ago
adapter_s113v7.go Add //go:build lines for Go 1.18 5 months ago
adapter_s132.c nrf: add GATT client 2 years ago
adapter_s132.go Add //go:build lines for Go 1.18 5 months ago
adapter_s140v6.c nrf52: add support for S140 version 6 2 years ago
adapter_s140v6.go Add //go:build lines for Go 1.18 5 months ago
adapter_s140v7.c nrf: update s140v7 SoftDevice version to latest, 7.3.0 11 months ago
adapter_s140v7.go Add //go:build lines for Go 1.18 5 months ago
adapter_sd.go Add //go:build lines for Go 1.18 5 months ago
adapter_windows.go updating URLs for fork 1 month ago
bluetooth.go updating URLs for fork 1 month ago
characteristic_uuids.go gen: generate standard service and characteristic UUIDs from Nordic Semiconductor bluetooth numbers database 2 years ago
error_sd.go Add //go:build lines for Go 1.18 5 months ago
gap.go Update fork from upstream 1 month ago
gap_darwin.go darwin: make Adapter.Connect thread-safe 1 year ago
gap_linux.go Update fork from upstream 1 month ago
gap_nrf51.go Add //go:build lines for Go 1.18 5 months ago
gap_nrf528xx-advertisement.go Add //go:build lines for Go 1.18 5 months ago
gap_nrf528xx-central.go Add //go:build lines for Go 1.18 5 months ago
gap_windows.go updating URLs for fork 1 month ago
gattc_darwin.go darwin: properly handle 16-bit UUIDs for service and characteristics in the unique format used by macOS 2 years ago
gattc_linux.go Merge branch 'upstream' into release 1 month ago
gattc_sd.go Add //go:build lines for Go 1.18 5 months ago
gatts.go all: add support for sending notifications 2 years ago
gatts_linux.go Update fork from upstream 1 month ago
gatts_other.go Add //go:build lines for Go 1.18 5 months ago
gatts_sd.go Add //go:build lines for Go 1.18 5 months ago
go.mod updating modules 1 month ago
go.sum updating modules 1 month ago
mac.go Fix ParseMAC bug 5 months ago
service_uuids.go gen: generate standard service and characteristic UUIDs from Nordic Semiconductor bluetooth numbers database 2 years ago
uuid.go darwin: properly handle 16-bit UUIDs for service and characteristics in the unique format used by macOS 2 years ago
uuid16.go Add //go:build lines for Go 1.18 5 months ago
uuid16_darwin.go darwin: properly handle 16-bit UUIDs for service and characteristics in the unique format used by macOS 2 years ago
uuid_sd.go Add //go:build lines for Go 1.18 5 months ago
uuid_test.go add more test, fix uuid test (strings are lower case in implementation) 2 years ago
version.go Change version to notate our fork 1 month ago

README.md

Go Bluetooth

Go Bluetooth

PkgGoDev CircleCI

Go Bluetooth is a cross-platform package for using Bluetooth Low Energy hardware from the Go programming language.

It works on typical operating systems such as Linux, macOS, and Windows.

It can also be used running "bare metal" on microcontrollers produced by Nordic Semiconductor by using TinyGo.

The Go Bluetooth package can be used to create both Bluetooth Low Energy Centrals as well as to create Bluetooth Low Energy Peripherals.

Bluetooth Low Energy Central

A typical Bluetooth Low Energy Central would be your laptop computer or mobile phone.

This example shows a central that scans for peripheral devices and then displays information about them as they are discovered:

package main

import (
	"git.tcp.direct/kayos/prototooth"
)

var adapter = bluetooth.DefaultAdapter

func main() {
	// Enable BLE interface.
	must("enable BLE stack", adapter.Enable())

	// Start scanning.
	println("scanning...")
	err := adapter.Scan(func(adapter *bluetooth.Adapter, device bluetooth.ScanResult) {
		println("found device:", device.Address.String(), device.RSSI, device.LocalName())
	})
	must("start scan", err)
}

func must(action string, err error) {
	if err != nil {
		panic("failed to " + action + ": " + err.Error())
	}
}

Bluetooth Low Energy Peripheral

A typical Bluetooth Low Energy Peripheral would be a temperature sensor or heart rate sensor.

This example shows a peripheral that advertises itself as being available for connection:

package main

import (
	"time"

	"git.tcp.direct/kayos/prototooth"
)

var adapter = bluetooth.DefaultAdapter

func main() {
  	// Enable BLE interface.
	must("enable BLE stack", adapter.Enable())

  	// Define the peripheral device info.
	adv := adapter.DefaultAdvertisement()
	must("config adv", adv.Configure(bluetooth.AdvertisementOptions{
		LocalName: "Go Bluetooth",
  	}))
  
  	// Start advertising
	must("start adv", adv.Start())

	println("advertising...")
	for {
		// Sleep forever.
		time.Sleep(time.Hour)
	}
}

func must(action string, err error) {
	if err != nil {
		panic("failed to " + action + ": " + err.Error())
	}
}

Current support

Linux macOS Windows Nordic Semi
API used BlueZ CoreBluetooth WinRT SoftDevice
Scanning ✔️ ✔️ ✔️ ✔️
Connect to peripheral ✔️ ✔️ ✔️
Write peripheral characteristics ✔️ ✔️ ✔️
Receive notifications ✔️ ✔️ ✔️
Advertisement ✔️ ✔️
Local services ✔️ ✔️
Local characteristics ✔️ ✔️
Send notifications ✔️ ✔️

Linux

Go Bluetooth support for Linux uses BlueZ via the D-Bus interface thanks to the https://github.com/muka/go-bluetooth package. This should work with most distros that support BlueZ such as Ubuntu, Debian, Fedora, and Arch Linux, among others.

Linux can be used both as a BLE Central or as a BLE Peripheral.

Installation

You need to have a fairly recent version of BlueZ, for example v5.48 is the latest released version for Ubuntu/Debian.

sudo apt update
sudo apt install bluez

Once you have done this, you can obtain the Go Bluetooth package using Git:

git clone https://github.com/tinygo-org/bluetooth.git

Compiling

After you have followed the installation, you should be able to compile/run the "scanner" test program:

cd bluetooth
go run ./examples/scanner

macOS

Go Bluetooth support for macOS uses the CoreBluetooth libraries thanks to the https://github.com/JuulLabs-OSS/cbgo package.

As a result, it should work with most versions of macOS, although it will require compiling using whatever specific version of XCode is required by your version of the operating system.

The macOS support only can only act as a BLE Central at this time, with some additional development work needed for full functionality.

Installation

In order to compile Go Bluetooth code targeting macOS, you must do so on macOS itself. In other words, we do not currently have cross compiler support. You must also have XCode tools installed:

xcode-select --install

Once you have done this, you can obtain the Go Bluetooth package using Git:

git clone https://github.com/tinygo-org/bluetooth.git

Compiling

After you have followed the installation, you should be able to compile/run the "scanner" test program:

cd bluetooth
go run ./examples/scanner

Windows

Go Bluetooth support for Windows uses the WinRT Bluetooth interfaces by way of the https://github.com/tinygo-org/bluetooth/winbt package that is part of this package.

The Windows support is still experimental, and needs additional development to be useful. At this time, it can only be used to perform scanning operations as a BLE Central.

For specifics please see https://github.com/tinygo-org/bluetooth/issues/13

Installation

Once you have done this, you can obtain the Go Bluetooth package using Git:

git clone https://github.com/tinygo-org/bluetooth.git

Compiling

After you have followed the installation, you should be able to compile/run the "scanner" test program:

cd bluetooth
go run .\examples\scanner

Nordic Semiconductor

Go Bluetooth has bare metal support for several chips from Nordic Semiconductor that include a built-in Bluetooth Low Energy radio.

This support requires compiling your programs using TinyGo.

You must also use firmware provided by Nordic Semiconductor known as the "SoftDevice". The SoftDevice is a binary blob that implements the BLE stack. There are other (open source) BLE stacks, but the SoftDevices are pretty solid and have all the qualifications you might need. Other BLE stacks might be added in the future.

The Nordic Semiconductor SoftDevice can be used both as a BLE Central or as a BLE Peripheral, depending on which chip is being used. See the "Supported Chips" section below.

Installation

You must install TinyGo to be able to compile bare metal code using Go Bluetooth. Follow the instructions for your operating system at https://tinygo.org/getting-started/

Once you have installed TinyGo, you can install the Go Bluetooth package by running:

git clone https://github.com/tinygo-org/bluetooth.git

Check your desired target board for any additional installation requirements.

Adafruit "Bluefruit" boards

The line of "Bluefruit" boards created by Adafruit already have the SoftDevice firmware pre-loaded. This means you can use TinyGo and the Go Bluetooth package without any additional steps required. Supported Adafruit boards include:

After you have installed TinyGo and the Go Bluetooth package, you should be able to compile/run code for your device.

For example, this command can be used to compile and flash an Adafruit Circuit Playground Bluefruit board with the example we provide that turns it into a BLE server to control the built-in NeoPixel LEDs:

tinygo flash -target circuitplay-bluefruit ./examples/circuitplay

There are other boards with TinyGo support that also use the same UF2 bootloader with pre-loaded SoftDevice. They include:

BBC micro:bit

Version 1

The BBC micro:bit uses an nRF51 chip with a CMSIS-DAP interface.

You will need to install OpenOCD (http://openocd.org/) to flash the board.

First, flash the SoftDevice firmware by copying the .hex file to the device. For example (on Linux):

cd bluetooth
cp ./s110_nrf51_8.0.0/s110_nrf51_8.0.0_softdevice.hex /media/yourusername/MICROBIT/

Once you have copied the SoftDevice firmware to the BBC micro:bit, you can then flash your TinyGo program:

tinygo flash -target=microbit-s110v8 ./examples/heartrate

Version 2

The BBC micro:bit v2 uses an nRF52833 chip with a CMSIS-DAP interface.

Support for the v2 will be available soon.

Supported Chips

The following Nordic Semiconductor chips are currently supported:

  • nRF51822 with the S110 SoftDevice (version 8). This SoftDevice does not support all features (e.g. scanning).
  • nRF52832 with the S132 SoftDevice (version 6).
  • nRF52840 with the S140 SoftDevice (version 6 and 7).

Flashing the SoftDevice on Other Boards

To use a board that uses one of the above supported chips from Nordic Semiconductor, other then those already listed, you will probably need to install the SoftDevice firmware on the board yourself in order to use it with TinyGo and the Go Bluetooth package.

Flashing the SoftDevice can sometimes be tricky. If you have nrfjprog installed, you can erase the flash and flash the new BLE firmware using the following commands. Replace the path to the hex file with the correct SoftDevice, for example s132_nrf52_6.1.1/s132_nrf52_6.1.1_softdevice.hex for S132 version 6.

nrfjprog -f nrf52 --eraseall
nrfjprog -f nrf52 --program path/to/softdevice.hex

After that, don't reset the board but instead flash a new program to it. For example, you can flash the Heart Rate Sensor example using tinygo (modify the -target flag as needed for your board):

tinygo flash -target=pca10040-s132v6 ./examples/heartrate

Flashing will normally reset the board.

API stability

The API is not stable! Because many features are not yet implemented and some platforms (e.g. Windows and macOS) are not yet fully supported, it's hard to say what a good API will be. Therefore, if you want stability you should pick a particular git commit and use that. Go modules can be useful for this purpose.

Some things that will probably change:

  • Add options to the Scan method, for example to filter on UUID.
  • Extra options to the Enable function, to request particular features (such as the number of peripheral connections supported).

This package will probably remain unstable until the following has been implemented:

  • Scan filters. For example, to filter on service UUID.
  • Bonding and private addresses.
  • Full support for all features at least two desktop operating systems.
  • Maybe some Bluetooth Classic support, such as A2DP.

Contributing

Your contributions are welcome!

Please take a look at our CONTRIBUTING.md document for details.

Frequently Asked Questions

Q. Where can I get an introduction to Bluetooth Low Energy, GAP, GATT, etc.?

A. Please see this excellent article from our friends at Adafruit: https://learn.adafruit.com/introduction-to-bluetooth-low-energy

Q. What is a client and server in BLE?

A. Please see https://devzone.nordicsemi.com/f/nordic-q-a/71/what-is-a-client-and-server-in-ble

Q. Can a device be both a GATT client and GATT server?

A. Yes, but this is not currently supported by Go Bluetooth. Current support is either to act as a central in client mode, or as a peripheral in server mode.

License

This project is licensed under the BSD 3-clause license, see the LICENSE file for details.

The SoftDevices from Nordic are licensed under a different license, check the license file in the SoftDevice source directory.