Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Failed to load latest commit information.
Latest commit message
Commit time
October 23, 2021 20:26
September 26, 2020 20:23
August 17, 2019 08:29
July 27, 2022 19:06
June 19, 2020 00:29
July 27, 2022 16:59
September 26, 2020 20:23
August 3, 2020 21:01
July 27, 2019 12:35
April 12, 2020 21:04
August 19, 2022 16:05
August 19, 2022 16:32
September 3, 2020 09:45
September 2, 2020 22:12
September 3, 2020 09:45
September 26, 2020 19:47
November 21, 2021 20:41
August 19, 2022 16:20
September 26, 2020 20:23
September 28, 2020 04:58


Go bluetooth API for Linux-based Bluez DBus interface.


Bluez API versioning

The version on master tracks Ubuntu bluetoothd version (v5.64). There are dedicated branches/tags with various version

See branches for available versions.


The library is a wrapper to the Bluez DBus API and some high level API to ease the interaction.

High level features supported:

  • Client code generation from bluez documentation
  • Shell wrappers for rfkill, btmgmt, hciconfig, hcitool
  • An hci socket basic API (inspired by go-ble/ble)
  • Expose bluetooth service from go code [unstable]
  • Pairing and authentication support (via agent)
  • Beaconing send & receive (iBeacon and Eddystone)
  • Mesh API support (since v5.53)


  • Generate dbus-compatible XML from documentation
  • Generate mock service to test the library against

Using this library

Want to add your project? Please, add it to the and open a PR!

Running examples

Examples are available in _examples folder.

cd _examples
go run main.go
# print available example commands
# Example discovery
go run main.go discovery

Development setup

  1. Clone the repository

git clone

  1. Retrieve the bluetooth API and generate GO code
make bluez/init bluez/checkout gen/clean gen/run

Code generation

To generate code for a new version of bluez use the command

BLUEZ_VERSION=5.65 make gen/clean gen

Change to a version available in bluez. Note that generated code may be broken or incomplete and the generation script may need fine tuning.

How generation works

The code structure follow this pattern:

  • ./api contains wrappers for the DBus Api
  • ./bluez contains the actual implementation, generated from the bluez documentation

Use make gen to re-generate go sources. There is also a commodity bluez JSON file available in the root folder for reference.

Generated code has gen_ prefix. If an API file exists with the same filename but without the prefix, generation will be skipped for that API.


The library is tested with

  • golang 1.17.5
  • bluez bluetooth v5.50, v5.54, v5.60

Development notes

  • Inspect a service ObjectManager

    dbus-send --system --print-reply --dest=go.bluetooth /hci0/apps/0 org.freedesktop.DBus.ObjectManager.GetManagedObjects
  • Retrieve char properties

    dbus-send --system --print-reply --dest=go.bluetooth /hci0/apps/0/service000003e8/char0  org.freedesktop.DBus.Properties.GetAll string:org.bluez.GattCharacteristic1
  • Give access to hciconfig to any user and avoid sudo (may have security implications)

    sudo setcap 'cap_net_raw,cap_net_admin+eip' `which hciconfig`
  • Monitor Bluetooth activity

    sudo btmon

  • Monitor DBus activity

    sudo dbus-monitor --system "type=error"

  • Start bluetoothd with experimental features and verbose debug messages make bluetoothd

  • Enable LE advertisement (on a single pc ensure to use at least 2x bluetooth adapter)

      sudo btmgmt -i 0 power off
      sudo btmgmt -i 0 name "my go app"
      sudo btmgmt -i 0 le on    
      sudo btmgmt -i 0 connectable on
      sudo btmgmt -i 0 advertising on
      sudo btmgmt -i 0 power on



Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.