Cross-platform Bluetooth API for Go and TinyGo. Supports Linux, macOS, Windows, and bare metal using Nordic SoftDevice or HCI
Cross-platform Bluetooth API for Go and TinyGo. Supports Linux, macOS, Windows, and bare metal using Nordic SoftDevice or HCI
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, on the Espressif ESP32-C3 and ESP32-S3 with their onboard radio, or on 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.
[!IMPORTANT] You can help TinyGo with a financial contribution using OpenCollective. Please see https://opencollective.com/tinygo for more information. Thank you!
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())
}
}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:
…go must("enable radio", espradio.Enable(espradio.Config{})) must("enable BLE stack", adapter.Enable())
If you want more information about the `espradio` support, please see https://github.com/tinygo-org/espradio
## CYW43439 (RP2040-W)
Go Bluetooth has bare metal support for boards that include a separate CYW43439 Bluetooth Low Energy radio co-processor.
Currently supported boards include:
* [Raspberry Pi Pico RP2040-W](https://www.raspberrypi.com/documentation/microcontrollers/raspberry-pi-pico.html#raspberry-pi-pico-w)
* [Pimoroni Badger2040-W](https://shop.pimoroni.com/products/badger-2040-w)
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 a Pico RP2040-W board with the example we provide that turns it into a BLE peripheral to act like a heart rate monitor:
tinygo flash -target pico-w ./examples/heartrate
If you want more information about the `cyw43439` support, please see https://github.com/soypat/cyw43439
## 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](./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.No open issues yet, or sync has not completed.