{"id":13575490,"url":"https://github.com/tinygo-org/bluetooth","last_synced_at":"2025-05-14T23:01:47.504Z","repository":{"id":38476857,"uuid":"189875241","full_name":"tinygo-org/bluetooth","owner":"tinygo-org","description":"Cross-platform Bluetooth API for Go and TinyGo. Supports Linux, macOS, Windows, and bare metal using Nordic SoftDevice or HCI","archived":false,"fork":false,"pushed_at":"2025-05-05T12:48:49.000Z","size":1615,"stargazers_count":840,"open_issues_count":96,"forks_count":152,"subscribers_count":13,"default_branch":"release","last_synced_at":"2025-05-10T09:52:44.874Z","etag":null,"topics":["ble","bluetooth","bluetooth-low-energy","central","linux","macos","nordicsemi","peripheral","softdevice","tinygo"],"latest_commit_sha":null,"homepage":"https://tinygo.org","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tinygo-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-06-02T17:25:06.000Z","updated_at":"2025-05-06T03:20:10.000Z","dependencies_parsed_at":"2023-12-25T12:50:56.208Z","dependency_job_id":"8357df6c-6d46-44f3-9c27-7cf54ed80be7","html_url":"https://github.com/tinygo-org/bluetooth","commit_stats":{"total_commits":250,"total_committers":29,"mean_commits":8.620689655172415,"dds":0.552,"last_synced_commit":"a668e1b0a062612faa41ac354f7edd5b25428101"},"previous_names":["aykevl/go-bluetooth"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinygo-org%2Fbluetooth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinygo-org%2Fbluetooth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinygo-org%2Fbluetooth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinygo-org%2Fbluetooth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tinygo-org","download_url":"https://codeload.github.com/tinygo-org/bluetooth/tar.gz/refs/heads/release","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254243353,"owners_count":22038044,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ble","bluetooth","bluetooth-low-energy","central","linux","macos","nordicsemi","peripheral","softdevice","tinygo"],"created_at":"2024-08-01T15:01:01.538Z","updated_at":"2025-05-14T23:01:47.388Z","avatar_url":"https://github.com/tinygo-org.png","language":"C","readme":"# Go Bluetooth\n\n[![Go Bluetooth](./images/gobluetooth.png)](https://tinygo.org/bluetooth)\n\n[![PkgGoDev](https://pkg.go.dev/badge/pkg.go.dev/tinygo.org/x/bluetooth)](https://pkg.go.dev/tinygo.org/x/bluetooth) [![Linux](https://github.com/tinygo-org/bluetooth/actions/workflows/linux.yml/badge.svg?branch=dev)](https://github.com/tinygo-org/bluetooth/actions/workflows/linux.yml) [![macOS](https://github.com/tinygo-org/bluetooth/actions/workflows/macos.yml/badge.svg?branch=dev)](https://github.com/tinygo-org/bluetooth/actions/workflows/macos.yml) [![Windows](https://github.com/tinygo-org/bluetooth/actions/workflows/windows.yml/badge.svg?branch=dev)](https://github.com/tinygo-org/bluetooth/actions/workflows/windows.yml)\n\nGo Bluetooth is a cross-platform package for using [Bluetooth Low Energy](https://en.wikipedia.org/wiki/Bluetooth_Low_Energy) hardware from the Go programming language. \n\nIt works on typical operating systems such as [Linux](#linux), [macOS](#macos), and [Windows](#windows). \n\nBy using [TinyGo](https://tinygo.org/), it can also be used running \"bare metal\" on microcontrollers produced by [Nordic Semiconductor](https://www.nordicsemi.com/), or boards that have a Bluetooth co-processor that uses the [Bluetooth Host Controller Interface (HCI)](https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host-controller-interface/host-controller-interface-functional-specification.html).\n\nThe Go Bluetooth package can be used to create both Bluetooth Low Energy Centrals as well as to create Bluetooth Low Energy Peripherals.\n\n## Bluetooth Low Energy Central\n\nA typical Bluetooth Low Energy Central would be your laptop computer or mobile phone.\n\nThis example shows a central that scans for peripheral devices and then displays information about them as they are discovered:\n\n```go\npackage main\n\nimport (\n\t\"tinygo.org/x/bluetooth\"\n)\n\nvar adapter = bluetooth.DefaultAdapter\n\nfunc main() {\n\t// Enable BLE interface.\n\tmust(\"enable BLE stack\", adapter.Enable())\n\n\t// Start scanning.\n\tprintln(\"scanning...\")\n\terr := adapter.Scan(func(adapter *bluetooth.Adapter, device bluetooth.ScanResult) {\n\t\tprintln(\"found device:\", device.Address.String(), device.RSSI, device.LocalName())\n\t})\n\tmust(\"start scan\", err)\n}\n\nfunc must(action string, err error) {\n\tif err != nil {\n\t\tpanic(\"failed to \" + action + \": \" + err.Error())\n\t}\n}\n```\n\n## Bluetooth Low Energy Peripheral\n\nA typical Bluetooth Low Energy Peripheral would be a temperature sensor or heart rate sensor.\n\nThis example shows a peripheral that advertises itself as being available for connection:\n\n```go\npackage main\n\nimport (\n\t\"time\"\n\n\t\"tinygo.org/x/bluetooth\"\n)\n\nvar adapter = bluetooth.DefaultAdapter\n\nfunc main() {\n  \t// Enable BLE interface.\n\tmust(\"enable BLE stack\", adapter.Enable())\n\n  \t// Define the peripheral device info.\n\tadv := adapter.DefaultAdvertisement()\n\tmust(\"config adv\", adv.Configure(bluetooth.AdvertisementOptions{\n\t\tLocalName: \"Go Bluetooth\",\n  \t}))\n  \n  \t// Start advertising\n\tmust(\"start adv\", adv.Start())\n\n\tprintln(\"advertising...\")\n\tfor {\n\t\t// Sleep forever.\n\t\ttime.Sleep(time.Hour)\n\t}\n}\n\nfunc must(action string, err error) {\n\tif err != nil {\n\t\tpanic(\"failed to \" + action + \": \" + err.Error())\n\t}\n}\n```\n\n## Current support\n\n|                                  | Linux              | macOS              | Windows            | Nordic Semi        | ESP32 (NINA-FW)    | CYW43439 (RP2040-W) |\n| -------------------------------- | ------------------ | ------------------ | ------------------ | ------------------ | ------------------ | ------------------- |\n| API used                         | BlueZ              | CoreBluetooth      | WinRT              | SoftDevice         | HCI         \t    | HCI                 |\n| Scanning                         | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark:  |\n| Connect to peripheral            | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark:  |\n| Write peripheral characteristics | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark:  |\n| Receive notifications            | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark:  |\n| Advertisement                    | :heavy_check_mark: | :x:                | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark:  |\n| Local services                   | :heavy_check_mark: | :x:                | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark:  |\n| Local characteristics            | :heavy_check_mark: | :x:                | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark:  |\n| Send notifications               | :heavy_check_mark: | :x:                | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark:  |\n\n## Linux\n\nGo Bluetooth support for Linux uses [BlueZ](http://www.bluez.org/) via the [D-Bus](https://en.wikipedia.org/wiki/D-Bus) interface. This should work with most distros that support BlueZ such as Ubuntu, Debian, Fedora, and Arch Linux, among others.\n\nLinux can be used both as a BLE Central or as a BLE Peripheral.\n\n### Installation\n\nYou need to have a fairly recent version of BlueZ, for example v5.48 is the latest released version for Ubuntu/Debian.\n\n\tsudo apt update\n\tsudo apt install bluez\n\nOnce you have done this, you can obtain the Go Bluetooth package using Git:\n\n\tgit clone https://github.com/tinygo-org/bluetooth.git\n\n### Compiling\n\nAfter you have followed the installation, you should be able to compile/run the \"scanner\" test program:\n\n\tcd bluetooth\n\tgo run ./examples/scanner\n\n## macOS\n\nGo Bluetooth support for macOS uses the [CoreBluetooth](https://developer.apple.com/documentation/corebluetooth?language=objc) libraries thanks to the https://github.com/tinygo-org/cbgo fork of the `cbgo` package.\n\nAs 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. \n\nThe macOS support only can only act as a BLE Central at this time, with some additional development work needed for full functionality.\n\n### Installation\n\nIn 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:\n\n\txcode-select --install\n\nOnce you have done this, you can obtain the Go Bluetooth package using Git:\n\n\tgit clone https://github.com/tinygo-org/bluetooth.git\n\n### Compiling\n\nAfter you have followed the installation, you should be able to compile/run the \"scanner\" test program:\n\n\tcd bluetooth\n\tgo run ./examples/scanner\n\n### Troubleshooting\n\nThere 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 -\u003e Privacy \u0026 Security -\u003e Bluetooth.\n\n## Windows\n\nGo Bluetooth support for Windows uses the [WinRT Bluetooth](https://docs.microsoft.com/en-us/uwp/api/windows.devices.bluetooth.bluetoothadapter?view=winrt-19041) interfaces by way of the https://github.com/saltosystems/winrt-go package.\n\n### Installation\n\nOnly the Go compiler itself is needed to compile Go Bluetooth code targeting Windows.\n\nYou can obtain the Go Bluetooth package using Git:\n\n\tgit clone https://github.com/tinygo-org/bluetooth.git\n\n### Compiling\n\nAfter you have followed the installation, you should be able to compile/run the \"scanner\" test program:\n\n\tcd bluetooth\n\tgo run .\\examples\\scanner\n\n## Nordic Semiconductor\n\nGo Bluetooth has bare metal support for several chips from [Nordic Semiconductor](https://www.nordicsemi.com/) that include a built-in Bluetooth Low Energy radio.\n\nThis support requires compiling your programs using [TinyGo](https://tinygo.org/).\n\nYou 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.\n\nThe 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.\n\n### Installation\n\nYou 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/  \n\nOnce you have installed TinyGo, you can install the Go Bluetooth package by running:\n\n\tgit clone https://github.com/tinygo-org/bluetooth.git\n\nCheck your desired target board for any additional installation requirements.\n\n### Adafruit \"Bluefruit\" boards\n\nThe 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:\n\n* [Adafruit Circuit Playground Bluefruit](https://www.adafruit.com/product/4333)\n* [Adafruit CLUE](https://www.adafruit.com/product/4500)\n* [Adafruit Feather nRF52840 Express](https://www.adafruit.com/product/4062)\n* [Adafruit ItsyBitsy nRF52840](https://www.adafruit.com/product/4481)\n\nAfter you have installed TinyGo and the Go Bluetooth package, you should be able to compile/run code for your device.\n\nFor 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:\n\n\ttinygo flash -target circuitplay-bluefruit ./examples/circuitplay\n\n### Seeed Studio XIAO nRF52840\n\nThe Seeed Studio Xiao nRF52840 uses the [UF2 bootloader](https://github.com/microsoft/uf2) with pre-loaded SoftDevice firmware, so it is very easy to use with TinyGo.\n\n* [Seeed Studio XIAO nRF52840](https://wiki.seeedstudio.com/XIAO_BLE)\n\nYou can flash your TinyGo program like this:\n\n    tinygo flash -target=xiao-ble ./examples/heartrate\n\n### Other boards with UF2 bootloader\n\nThere are other boards with TinyGo support that use the same UF2 bootloader with pre-loaded SoftDevice. They include:\n\n* [Nice Keyboards nice!nano](https://nicekeyboards.com/products/nice-nano-v1-0)\n* [Makerdiary nRF52840 MDK USB Dongle](https://wiki.makerdiary.com/nrf52840-mdk-usb-dongle/)\n\n### BBC micro:bit\n\n#### Version 1\n\nThe [BBC micro:bit](https://microbit.org/) uses an nRF51 chip with a CMSIS-DAP interface.\n\nYou will need to install OpenOCD (http://openocd.org/) to flash the board.\n\nFirst, flash the SoftDevice firmware by copying the .hex file to the device. For example (on Linux):\n\n\tcd bluetooth\n    cp ./s110_nrf51_8.0.0/s110_nrf51_8.0.0_softdevice.hex /media/yourusername/MICROBIT/\n\nOnce you have copied the SoftDevice firmware to the BBC micro:bit, you can then flash your TinyGo program:\n\n    tinygo flash -target=microbit-s110v8 ./examples/heartrate\n\n#### Version 2\n\nThe [BBC micro:bit v2](https://microbit.org/new-microbit/) uses an nRF52833 chip with a CMSIS-DAP interface.\n\nSupport for the v2 will be available soon.\n\n### Supported Chips\n\nThe following Nordic Semiconductor chips are currently supported:\n\n* [nRF51822](https://www.nordicsemi.com/Products/Low-power-short-range-wireless/nRF51822) with the [S110](https://www.nordicsemi.com/Software-and-Tools/Software/S110) SoftDevice (version 8). This SoftDevice does not support all features (e.g. scanning).\n* [nRF52832](https://www.nordicsemi.com/Products/Low-power-short-range-wireless/nRF52832) with the [S132](https://www.nordicsemi.com/Software-and-Tools/Software/S132) SoftDevice (version 6).\n* [nRF52840](https://www.nordicsemi.com/Products/Low-power-short-range-wireless/nRF52840) with the [S140](https://www.nordicsemi.com/Software-and-Tools/Software/S140) SoftDevice (version 6 and 7).\n\n### Flashing the SoftDevice on Other Boards\n\nTo 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.\n\nFlashing the SoftDevice can sometimes be tricky. If you have [nrfjprog](https://www.nordicsemi.com/Software-and-Tools/Development-Tools/nRF-Command-Line-Tools) 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.\n\n    nrfjprog -f nrf52 --eraseall\n    nrfjprog -f nrf52 --program path/to/softdevice.hex\n\nAfter 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):\n\n    tinygo flash -target=pca10040-s132v6 ./examples/heartrate\n\nFlashing will normally reset the board.\n\n## ESP32 (NINA)\n\nGo Bluetooth has bare metal support for boards that include a separate ESP32 Bluetooth Low Energy radio co-processor. The ESP32 must be running the Arduino or Adafruit `nina_fw` firmware.\n\nSeveral boards created by Adafruit and Arduino already have the `nina-fw` firmware pre-loaded. This means you can use TinyGo and the Go Bluetooth package without any additional steps required.\n\nCurrently supported boards include:\n\n* [Adafruit Metro M4 AirLift](https://www.adafruit.com/product/4000)\n* [Adafruit PyBadge](https://www.adafruit.com/product/4200) with [AirLift WiFi FeatherWing](https://www.adafruit.com/product/4264)\n* [Adafruit PyPortal](https://www.adafruit.com/product/4116)\n* [Arduino Nano 33 IoT](https://docs.arduino.cc/hardware/nano-33-iot)\n* [Arduino Nano RP2040 Connect](https://docs.arduino.cc/hardware/nano-rp2040-connect)\n\nAfter you have installed TinyGo and the Go Bluetooth package, you should be able to compile/run code for your device.\n\nFor example, this command can be used to compile and flash an Arduino Nano RP2040 Connect board with the example we provide that turns it into a BLE peripheral to act like a heart rate monitor:\n\n\ttinygo flash -target nano-rp2040 ./examples/heartrate\n\nIf you want more information about the `nina-fw` firmware, or want to add support for other ESP32-equipped boards, please see https://github.com/arduino/nina-fw\n\n## CYW43439 (RP2040-W)\n\nGo Bluetooth has bare metal support for boards that include a separate CYW43439 Bluetooth Low Energy radio co-processor.\n\nCurrently supported boards include:\n\n* [Raspberry Pi Pico RP2040-W](https://www.raspberrypi.com/documentation/microcontrollers/raspberry-pi-pico.html#raspberry-pi-pico-w)\n* [Pimoroni Badger2040-W](https://shop.pimoroni.com/products/badger-2040-w)\n\nAfter you have installed TinyGo and the Go Bluetooth package, you should be able to compile/run code for your device.\n\nFor 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:\n\n\ttinygo flash -target pico-w ./examples/heartrate\n\nIf you want more information about the `cyw43439` support, please see https://github.com/soypat/cyw43439\n\n## API stability\n\n**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.\n\nSome things that will probably change:\n\n  * Add options to the `Scan` method, for example to filter on UUID.\n  * Extra options to the `Enable` function, to request particular features (such as the number of peripheral connections supported).\n\nThis package will probably remain unstable until the following has been implemented:\n\n  * Scan filters. For example, to filter on service UUID.\n  * Bonding and private addresses.\n  * Full support for all features at least two desktop operating systems.\n  * Maybe some Bluetooth Classic support, such as A2DP.\n\n## Contributing\n\nYour contributions are welcome!\n\nPlease take a look at our [CONTRIBUTING.md](./CONTRIBUTING.md) document for details.\n\n## Frequently Asked Questions\n\n**Q. Where can I get an introduction to Bluetooth Low Energy, GAP, GATT, etc.?**\n\nA. Please see this excellent article from our friends at Adafruit: https://learn.adafruit.com/introduction-to-bluetooth-low-energy\n\n**Q. What is a client and server in BLE?**\n\nA. Please see https://devzone.nordicsemi.com/f/nordic-q-a/71/what-is-a-client-and-server-in-ble\n\n**Q. Can a device be both a GATT client and GATT server?**\n\nA. 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.\n\n## License\n\nThis project is licensed under the BSD 3-clause license, see the LICENSE file for details.\n\nThe SoftDevices from Nordic are licensed under a different license, check the license file in the SoftDevice source directory.\n","funding_links":[],"categories":["C","Wireless Communication"],"sub_categories":["WASI and WASM Unknown"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftinygo-org%2Fbluetooth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftinygo-org%2Fbluetooth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftinygo-org%2Fbluetooth/lists"}