{"id":18572167,"url":"https://github.com/suesslabs/linux.bluetooth","last_synced_at":"2025-04-10T07:31:01.041Z","repository":{"id":49817514,"uuid":"517785811","full_name":"SuessLabs/Linux.Bluetooth","owner":"SuessLabs","description":".NET Linux Bluetooth library for interfacing with peripherals using DBus BlueZ","archived":false,"fork":false,"pushed_at":"2024-03-08T14:05:25.000Z","size":336,"stargazers_count":35,"open_issues_count":6,"forks_count":4,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-03-26T08:46:16.497Z","etag":null,"topics":["avalonia","ble","bluetooth","bluetooth-low-energy","bluez","bluez-dbus","csharp","dotnet","linux","suesslabs","xeno-innovations"],"latest_commit_sha":null,"homepage":"https://www.nuget.org/packages/Linux.Bluetooth/","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SuessLabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/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}},"created_at":"2022-07-25T18:55:56.000Z","updated_at":"2024-04-15T04:03:16.656Z","dependencies_parsed_at":"2023-12-26T17:41:28.527Z","dependency_job_id":"2dd62a21-0c26-450e-8a5b-abeafa301419","html_url":"https://github.com/SuessLabs/Linux.Bluetooth","commit_stats":{"total_commits":73,"total_committers":6,"mean_commits":"12.166666666666666","dds":"0.34246575342465757","last_synced_commit":"03937c31142b7bce4ffb1914e360864fcada295f"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SuessLabs%2FLinux.Bluetooth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SuessLabs%2FLinux.Bluetooth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SuessLabs%2FLinux.Bluetooth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SuessLabs%2FLinux.Bluetooth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SuessLabs","download_url":"https://codeload.github.com/SuessLabs/Linux.Bluetooth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248176250,"owners_count":21060032,"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":["avalonia","ble","bluetooth","bluetooth-low-energy","bluez","bluez-dbus","csharp","dotnet","linux","suesslabs","xeno-innovations"],"created_at":"2024-11-06T23:05:12.604Z","updated_at":"2025-04-10T07:31:00.725Z","avatar_url":"https://github.com/SuessLabs.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Linux Bluetooth Library for .NET\n\n![img](https://raw.githubusercontent.com/SuessLabs/Linux.Bluetooth/master/images/Linux.Bluetooth-128x128.png)\n\nThe Linux.Bluetooth library for .NET gives developers the ability to quickly stand up and interface with Linux's BLE radio with very little effort. There's no need to recall the laborious D-Bus API calls, we handle that for you.\n\n[![Linux.Bluetooth NuGet Version](https://img.shields.io/nuget/v/Linux.Bluetooth)](https://www.nuget.org/packages/Linux.Bluetooth/)\n\n![Debugging Image](https://raw.githubusercontent.com/SuessLabs/Linux.Bluetooth/master/docs/Adapter%20-%20ObjectPath%20Contents.png)\n\nThe library uses, [Tmds.DBus](https://github.com/tmds/Tmds.DBus) to access Linux's D-Bus, the preferred interface for Bluetooth in userspace.\n\nCheck out the SuessLabs article on using [Linux.Bluetooth](https://suesslabs.com/csharp/net-and-linux-bluetooth/)\n\n## Requirements\n\n* Linux\n* .NET 6, 7, and 8\n\n_Sorry, older Mono (.NET Framework) versions are not supported._\n\nThis project has been validated against, BlueZ v5.50 and above. You can check which version you're using with, `bluetoothd -v`.\n\n### Supported Distributions\n\nLinux.Bluetooth aims to support Linux Distributions where both .NET and BlueZ is supported. Officially, this NuGet package has been tested against Ubuntu 20.04 LTS.\n\nList of [BlueZ supported](http://www.bluez.org/about/) distros:\n\n* Ubuntu Linux\n* Raspbian (_Raspberry PI_)\n* Debian GNU/Linux\n* Fedora Core / Red Hat Linux\n* OpenSuSE / SuSE Linux\n* Mandrake Linux\n* Gentoo Linux\n* Chrome OS\n\n## Installation\n\n```bash\ndotnet add package Linux.Bluetooth\n```\n\n## Usage\n\nC# events are available for several properties. Events are useful for properly handling disconnects and reconnects.\n\n### Get a Bluetooth adapter\n\n```C#\nusing Linux.Bluetooth;\n...\nIAdapter1 adapter = (await BlueZManager.GetAdaptersAsync()).FirstOrDefault();\n```\n\nor get a particular adapter:\n\n```C#\nIAdapter1 adapter = await BlueZManager.GetAdapterAsync(adapterName: \"hci0\");\n```\n\n## Scan for Bluetooth devices\n\n```C#\nadapter.DeviceFound += adapter_DeviceFoundAsync;\n\nawait adapter.StartDiscoveryAsync();\n...\nawait adapter.StopDiscoveryAsync();\n```\n\n### Get Devices\n\n`adapter.DeviceFound` (above) will be called immediately for existing devices, and as new devices show up during scanning; `eventArgs.IsStateChange` can be used to distinguish between existing and new devices. Alternatively you can can use `GetDevicesAsync`:\n\n```C#\nIReadOnlyList\u003cDevice\u003e devices = await adapter.GetDevicesAsync();\n```\n\n### Connect to a Device\n\n```C#\ndevice.Connected += device_ConnectedAsync;\ndevice.Disconnected += device_DisconnectedAsync;\ndevice.ServicesResolved += device_ServicesResolvedAsync;\n\nawait device.ConnectAsync();\n```\n\nAlternatively, you can wait for \"Connected\" and \"ServicesResolved\" to equal true:\n\n```C#\nTimeSpan timeout = TimeSpan.FromSeconds(15);\n\nawait device.ConnectAsync();\nawait device.WaitForPropertyValueAsync(\"Connected\", value: true, timeout);\nawait device.WaitForPropertyValueAsync(\"ServicesResolved\", value: true, timeout);\n```\n\n### Retrieve a GATT Service and Characteristic\n\nPrerequisite: You must be connected to a device and services must be resolved. You may need to pair with the device in order to use some services.\n\nExample using GATT Device Information Service UUIDs.\n\n```C#\nstring serviceUUID = \"0000180a-0000-1000-8000-00805f9b34fb\";\nstring characteristicUUID = \"00002a24-0000-1000-8000-00805f9b34fb\";\n\nIGattService1 service = await device.GetServiceAsync(serviceUUID);\nIGattCharacteristic1 characteristic = await service.GetCharacteristicAsync(characteristicUUID);\n```\n\n### Read a GATT Characteristic value\n\n```C#\nbyte[] value = await characteristic.ReadValueAsync(timeout);\n\nstring modelName = Encoding.UTF8.GetString(value);\n```\n\n### Subscribe to GATT Characteristic Notifications\n\n```C#\ncharacteristic.Value += characteristic_Value;\n...\n\nprivate static async Task characteristic_Value(GattCharacteristic characteristic, GattCharacteristicValueEventArgs e)\n{\n  try\n  {\n    Console.WriteLine($\"Characteristic value (hex): {BitConverter.ToString(e.Value)}\");\n\n    Console.WriteLine($\"Characteristic value (UTF-8): \\\"{Encoding.UTF8.GetString(e.Value)}\\\"\");\n  }\n  catch (Exception ex)\n  {\n    Console.Error.WriteLine(ex);\n  }\n}\n```\n\n## Tips\n\nIt may be necessary to pair with a device for a GATT service to be visible or for reading GATT characteristics to work. To pair, one option is to run `bluetoothctl` (or `sudo bluetoothctl`)\nand then run `default agent` and `agent on` within `bluetoothctl`. Watch `bluetoothctl` for pairing requests.\n\nSee [Ubuntu's Introduction to Pairing](https://ubuntu.com/core/docs/bluez/reference/pairing/introduction).\n\n### BluetoothCtl Helper\n\nFrom command line, use `bluetoothctl` or Bluetooth Manager to scan and retrieve device UUIDs and Services to assist with debugging..\"\n\n```bash\n$ bluetoothctl\n\n; Get list of BT Adapters\nlist\n\n; Scan for devices\nscan on\n\n; Stop Scanning\nscan off\n\n; List known devices\ndevices\n```\n\n## Contributing\n\nSee [Contributing](./github/CONTRIBUTING.md).\n\n## Coming Soon\n\n* Deprecating `Linux.Bluetooth.Extensions`. It will now just be `Linux.Bluetooth` namespace.\n\n## Reference\n\n* [Prism Avalonia](https://github.com/AvaloniaCommunity/Prism.Avalonia) for Linux GUI test app\n* [Doing Bluetooth Low Energy on Linux](https://elinux.org/images/3/32/Doing_Bluetooth_Low_Energy_on_Linux.pdf)\n* **BlueZ API**:\n  * [HEAD](https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc)\n  * [v5.53](https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc?h=5.53) - _i.e. Ubuntu v20.04 LTS_\n* [BlueZ Official Site](http://www.bluez.org/)\n* [Install BlueZ on the Raspberry PI](https://learn.adafruit.com/install-bluez-on-the-raspberry-pi/overview)\n\n**Sponsored by:** [Suess Labs](https://suesslabs.com) a subsidary of [Xeno Innovations, Inc](https://xenoinc.com).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuesslabs%2Flinux.bluetooth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsuesslabs%2Flinux.bluetooth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuesslabs%2Flinux.bluetooth/lists"}