fork of the tinygo bluetooth library with some bad ideas implemented
Go to file
2020-09-10 15:24:22 +02:00
.circleci macos: completed initial implementation 2020-09-02 08:37:04 +02:00
examples examples: add example for Circuit Playground Bluefruit board to control built-in NeoPixels 2020-09-10 15:24:22 +02:00
rawterm examples/nusserver: refactor terminal handling 2020-06-11 15:46:08 +02:00
s110_nrf51_8.0.0 Add S110 version 8.0.0 SoftDevice for nrf51822 2020-05-31 15:40:57 +02:00
s132_nrf52_6.1.1 Initial commit 2019-11-08 10:58:02 +01:00
s140_nrf52_6.1.1 nrf52: add support for S140 version 6 2020-08-30 16:39:16 +02:00
s140_nrf52_7.0.1 Port current codebase to S140 softdevice 2020-03-06 14:24:50 +01:00
winbt domain: use custom domain for all uses of winbt subpackage 2020-09-09 16:04:40 +02:00
.gitattributes Initial commit 2019-11-08 10:58:02 +01:00
.gitignore nrf52: add support for S140 version 6 2020-08-30 16:39:16 +02:00
adapter_darwin.go docs: better explanation of peripheral UUID on macOS 2020-09-02 08:37:04 +02:00
adapter_linux.go linux: improve scanning 2020-06-28 00:21:47 +02:00
adapter_nrf51.go all: add support for sending notifications 2020-06-03 19:42:21 +02:00
adapter_nrf528xx.go nrf528xx: correct returned MAC address in struct with global scan result 2020-09-09 18:46:11 +02:00
adapter_s110.c nrf: add GATT client 2020-06-28 00:21:40 +02:00
adapter_s110.go Add S110 version 8.0.0 SoftDevice for nrf51822 2020-05-31 15:40:57 +02:00
adapter_s132.c nrf: add GATT client 2020-06-28 00:21:40 +02:00
adapter_s132.go softdevice: make code more flexible for other SoftDevices 2020-03-06 13:46:42 +01:00
adapter_s140v6.c nrf52: add support for S140 version 6 2020-08-30 16:39:16 +02:00
adapter_s140v6.go nrf52: add support for S140 version 6 2020-08-30 16:39:16 +02:00
adapter_s140v7.c nrf52: add support for S140 version 6 2020-08-30 16:39:16 +02:00
adapter_s140v7.go nrf52: add support for S140 version 6 2020-08-30 16:39:16 +02:00
adapter_sd.go nrf: add GATT client 2020-06-28 00:21:40 +02:00
adapter_windows.go domain: use custom domain for all uses of winbt subpackage 2020-09-09 16:04:40 +02:00
adapter.go all: replace GAP events with auto-restarting advertisements 2020-06-01 23:29:31 +02:00
bluetooth.go docs,domain: use import for custom domain for package, also GoDocs format info for package 2020-09-09 16:04:40 +02:00
CONTRIBUTING.md docs: update README with lots of info/organization and also add CONTRIBUTING guidelines 2020-09-03 15:40:52 +02:00
error_sd.go softdevice: make code more flexible for other SoftDevices 2020-03-06 13:46:42 +01:00
gap_darwin.go macos: added characteristic notifications 2020-09-02 08:37:04 +02:00
gap_linux.go linux: correct use of Addresser when scanning 2020-09-03 15:26:43 +02:00
gap_nrf51.go gap: switch to use MACAddress struct when possible for shared implementation 2020-09-02 08:37:04 +02:00
gap_nrf528xx.go gap: switch to use MACAddress struct when possible for shared implementation 2020-09-02 08:37:04 +02:00
gap_windows.go domain: use custom domain for all uses of winbt subpackage 2020-09-09 16:04:40 +02:00
gap.go gap: correct use of Address on Linux platform 2020-09-02 08:37:04 +02:00
gattc_darwin.go linux: all for DiscoverServices and DiscoverCharacteristics to discover all when no specific list of UUIDs 2020-09-03 15:26:43 +02:00
gattc_linux.go linux: all for DiscoverServices and DiscoverCharacteristics to discover all when no specific list of UUIDs 2020-09-03 15:26:43 +02:00
gattc_sd.go nrf: add GATT client 2020-06-28 00:21:40 +02:00
gatts_linux.go all: add support for sending notifications 2020-06-03 19:42:21 +02:00
gatts_other.go all: add support for sending notifications 2020-06-03 19:42:21 +02:00
gatts_sd.go nrf: add GATT client 2020-06-28 00:21:40 +02:00
gatts.go all: add support for sending notifications 2020-06-03 19:42:21 +02:00
go.mod examples: add example for Circuit Playground Bluefruit board to control built-in NeoPixels 2020-09-10 15:24:22 +02:00
go.sum macos: starting point for adding macOS support 2020-09-02 08:37:04 +02:00
LICENSE Initial commit 2019-11-08 10:58:02 +01:00
mac.go all: support HasServiceUUID on advertisement payloads 2020-06-04 19:23:25 +02:00
Makefile examples: add example for Circuit Playground Bluefruit board to control built-in NeoPixels 2020-09-10 15:24:22 +02:00
README.md domain: use custom domain for go.mod and examples 2020-09-09 16:04:40 +02:00
uuid_sd.go softdevice: make code more flexible for other SoftDevices 2020-03-06 13:46:42 +01:00
uuid_test.go linux: add support for services 2019-11-16 19:11:59 +00:00
uuid.go all: support HasServiceUUID on advertisement payloads 2020-06-04 19:23:25 +02:00

Go Bluetooth

PkgGoDev CircleCI

This package provides a cross-platform Bluetooth Low Energy module for Go that can be used on operating systems such as Linux, macOS, and Windows.

It can also be used running "bare metal" on microcontrollers such as those produced by Nordic Semiconductor.

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

package main

import (
	"tinygo.org/x/bluetooth"
)

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())
	}
}

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

The current support for Linux uses BlueZ via the D-Bus interface. It 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 as well as BLE peripheral. You need to have a fairly recent version of BlueZ, for example v5.48 is the latest released version for Ubuntu/Debian.

macOS

The current macOS support uses the CoreBluetooth libraries provided by macOS. 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 support needed for full functionality.

Windows

The Windows support is still experimental, and needs additional development to be useful.

Nordic Semiconductor

As you can see above, there is bare metal support for several chips from Nordic Semiconductors.

These chips are supported through TinyGo.

This support also requires firmware provided by Nordic Semi 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.

At the moment the following chips are supported:

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

Adafruit "Bluefruit" boards

The support for boards created by Adafruit already have the Nordic Semi SoftDevice firmware pre-installed. You can use TinyGo with this package without any additional steps required. Supported boards include:

Flashing the SoftDevice

Other boards that use supported chips from Nordic Semi that do not already have the SoftDevice firmware must have it installed on the board in order to use this package.

Flashing the SoftDevice can 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.

For boards that use the CMSIS-DAP interface (such as the BBC micro:bit), this works a bit different. Flashing the SoftDevice is done by simply copying the .hex file to the device, for example (on Linux):

cp path/to/softdevice.hex /media/yourusername/MICROBIT/

Flashing will then need to be done a bit differently, using the CMSIS-DAP interface instead of the mass-storage interface normally used by TinyGo:

tinygo flash -target=microbit-s110v8 -programmer=cmsis-dap ./examples/heartrate

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.
  • Usable support on 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.

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.