Go Bluetooth

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.

By using TinyGo, it can also be used running "bare metal" on microcontrollers produced by Nordic Semiconductor, or boards that have a Bluetooth co-processor that uses the Bluetooth Host Controller Interface (HCI).

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

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 (
	"context"
	"time"

	"tinygo.org/x/bluetooth"
)

var adapter = bluetooth.DefaultAdapter

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

	ctx, cancel := context.WithCancel(context.Background())
	adapter.SetConnectHandler(func(device bluetooth.Device, connected bool) {
		if connected {
			println("device connected:", device.Address.String())
			return
		}

		println("device disconnected:", device.Address.String())
		cancel()
	})

  	// 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())
	
	// Stop advertising to release resources
	defer adv.Stop()

	println("advertising...")
	<- ctx.Done()
}

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

Current support

| | Linux | macOS | Windows | Nordic Semi | ESP32 (NINA-FW) | CYW43439 (RP2040-W) | | -------------------------------- | ------------------ | ------------------ | ------------------ | ------------------ | ------------------ | ------------------- | | API used | BlueZ | CoreBluetooth | WinRT | SoftDevice | HCI | HCI | | Scanning | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | Connect to peripheral | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | Write peripheral characteristics | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | Receive notifications | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | Advertisement | :heavy_check_mark: | :x: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | Local services | :heavy_check_mark: | :x: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | Local characteristics | :heavy_check_mark: | :x: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | | Send notifications | :heavy_check_mark: | :x: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |

Linux

Go Bluetooth support for Linux uses BlueZ via the D-Bus interface. 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/tinygo-org/cbgo fork of the 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

Troubleshooting

There is a known issue with iTerm2 and the Bluetooth package. If you are getting a message like abort: trap, try whitelisting iTerm2 manually through System Settings -> Privacy & Security -> Bluetooth.

Windows

Go Bluetooth support for Windows uses the WinRT Bluetooth interfaces by way of the https://github.com/saltosystems/winrt-go package.

Installation

Only the Go compiler itself is needed to compile Go Bluetooth code targeting Windows.

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:

• Adafruit Circuit Playground Bluefruit
• Adafruit CLUE
• Adafruit Feather nRF52840 Express
• Adafruit ItsyBitsy nRF52840

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

For example, this comm