この記事は Aptpod Advent Calendar 2018の13日目の記事です.
Aptpodで、エンベデッドエンジニアをしている @ffmatsuです.
弊社ではエッジデバイス(データ収集用の車載機/ラズパイ)の開発をしており、これらのエッジデバイスの動作状態を簡単に把握する仕組みのひとつとして、Bluetooth(BLE)を用いたiOS/Androidアプリとの通信機能も開発しています.
今回のAdvent Calendarでは、BlueZのサンプルコードを使ってBLE通信する方法を紹介しようと思ったのですが、そもそも BlueZのサンプルコードを紹介した記事が少なかったので、本記事では BlueZのAPIの概略やサンプルコードの解説をお送りしたいと思います.
What is BlueZ ?
Linuxの標準のBluetoothプロトコルスタックです.
ラズパイOSのRaspbianでもBlueZが使われているので、このBlueZを制御する事でラズパイ上でBluetoothの各機能(BLE通信など)を使う事ができます.
BlueZのソースコード
BlueZのソースコードは以下のリポジトリで公開されています.
https://git.kernel.org/pub/scm/bluetooth/bluez.git
今回は、最新のRaspbianでも採用されている、 v5.47をターゲットにお話します.
以下のページから実際にソースコードをダウンロードした上で記事を読んで頂けると理解しやすいかと思います.
http://www.bluez.org/release-of-bluez-5-47/
BlueZのフォルダ構成
BlueZのソースコードを見ると、以下のようなフォルダ構成になっています.
├── client
├── doc
├── emulator
├── gdbus
├── gobex
├── monitor
├── obexd
├── peripheral
├── plugins
├── profiles
├── src
├── test
├── test-driver
├── tools
└── unit
and more ...
この中で、注目すべきフォルダを以下に示します.
- doc
- D-Bus InterfaceのAPI仕様を記載したテキスト
- test
- 動作確認用のPythonのサンプルコード
- tools
-
hciconfigなどの、コマンドツールのソースコード
-
- client
-
bluetoothctlのソースコード
-
BlueZのAPI仕様について
他のBlueZを使用したBLE機能の記事を見ると、 hciconfigや gattoolsなどのコマンドツールを使った実例が多いのですが、BlueZの機能を十分に活用するのであれば、BlueZのAPIを使った方がよいかと思います.
BlueZのAPI仕様は、 doc/フォルダに展開されています.
https://git.kernel.org/pub/scm/bluetooth/bluez.git/tree/doc?h=5.47
これらのAPI仕様ですが、D-Busのインターフェースで記載されています.
D-Bus
D-Busについての解説は、以下の記事がとても詳しいです.
https://www.silex.jp/library/blog/20170126-1
D-Bus制御のプログラミングは上述の記事通り、とても面倒くさいです.
ただし、Pythonに関しては割と直感的に記述でき、BlueZのサンプルコードには各機能毎のAPIを実際に動かす事ができるPythonのコードがあるので、これらのサンプルコードを使ってAPIの実動作を確認しながらプログラミングしていくと幸せになれます.
docフォルダの内容
doc/フォルダには、BlueZのD-Bus APIの仕様が記載されたドキュメントが格納されています.
以下に各Profileに関連するファイルの要約を示します.
各Profileの詳細は、実際にファイルを参照してください.
共通
BLE/ Classic 両方で使用するAPIです
| file | 概略 |
|---|---|
| adapter-api.txt | 自デバイス(Adapter)を制御するAPI |
| agent-api.txt | ペアリング処理のAPI |
| device-api.txt | 接続相手のデバイスを制御するAPI |
BLE関連
BLEのGATT/Advertisingの制御や、BLE専用のProfile/Serviceを実装したAPIです.
| file | 概略 |
|---|---|
| advertising-api.txt | Advertising関連のAPI |
| gatt-api.txt | GATT Prfileの設定API |
| alert-api.txt | Phone Alert Status (PASP)のAPI |
| cyclingspeed-api.txt | Cycling Speed and Cadence のAPI |
| health-api.txt | HealthのAPI |
| heartrate-api.txt | Heart RateのAPI |
| proximity-api.txt | Proximity のAPI |
| thermometer-api.txt | Health Thermometer のAPI |
Classic関連
Classic (Bluetooth BR/EDR)関連のProfileを制御するAPIです.
| file | 概略 |
|---|---|
| input-api.txt | HID ProrileのAPI |
| media-api.txt | A2DP/AVRCPを抽象化したAPI |
| network-api.txt | PANなどのNetwork 関連のAPI |
| obex-agent-api.txt | PBAPなどでも使われるOBEX protocolのAPI |
| obex-api.txt | OBEX全体を制御するAPI |
| profile-api.txt | SPPなど、RFCOMMをProfileとして登録するAPI |
| sap-api.txt | SIM Access ProfileのAPI |
ちなみに、Hands Free Profile (HFP)関連のAPIは
ofonoを使う事になります.
testフォルダの内容
test/フォルダ内には、上述のD-Bus APIをpythonから呼び出すサンプルコードが展開されています.
これらのコードを実際に実行すると、各APIの簡単な動作を確認する事が可能になります.
以下に、各サンプルコードの概要を記載します
共通
| file | 概略 |
|---|---|
| bluezutils.py | 他のpythonコードからimportされるutil群 |
| dbusdef.py |
bluezutils.py内のfind_adapter()を試しに呼ぶスクリプト.BlueZが認識しているBluetoothアダプタ(hci*)を一覧表示する |
| test-adapter | Adapter インターフェースの各Property (デバイス名やアドレス)を取得/表示するスクリプト |
| monitor-bluetooth | Adapter, Deviceのinterfaceから発行される - PropertyChanged - Added - Removed の各シグナルをシグナルハンドラに登録し、メッセージ内容を表示するスクリプト |
| test-manager |
org.freedesktop.DBus.ObjectManager(D-Busの共通インターフェース)の- Added - Removed を表示する |
| test-discovery | Adapterに対して StartDiscovery()を要求し、周辺に存在する相手デバイスを探索する |
| list-devices | Adapterのinterfaceに対して GetManagedObject()を要求し、現在、BlueZが認識している相手デバイス（ペアリング済み、発見済み）の一覧を表示する |
| simple-agent | ペアリング処理を代行するAgentをD-Busに登録し、ペアリング処理(Numeric Comparisonなど)を実行するスクリプト |
| test-device | 相手デバイス（ペアリング済み、発見済み）に対して、接続要求や削除、リスト取得などのAPIを要求する |
BLE (Low Energy向け)
BLE向けのAPIのテストコードです.
後半のtest-*で始まる、Profile毎のテストコードの詳細は省略します.
(GATT Profileの一覧はこちら)
| file | 概略 |
|---|---|
| example-advertisement | BLEのAdvertisingのサンプル. v.5.43ではExperimental扱いなので、そのままでは動きません. |
| example-gatt-client | 接続中のデバイス(GATT Server)からHeart Rate Serviceを受信するClientを起動 |
| example-gatt-server | 擬似的にGATT Server を立ち上げる |
| test-gatt-profile | GATT Profile APIのテスト. Gatt Clientを登録する事で、自動接続などの機能が提供される |
| test-cyclingspeed | Cycling Speed and Cadenceのテスト |
| test-health | Healthのテスト |
| test-heartrate | Heart Rateのテスト |
| test-proximity | Proximity Profileのテスト |
| test-thermometer | Health Thermometerのテスト |
| test-alert | Phone Alert Statusのテスト |
Classic向け
こちらは従来型と呼ばれるProfileのサンプル/テストコードです.
需要も少なそうなので、さらっと紹介します。
(Classic Profileの一覧はこちら)
| file | 概略 |
|---|---|
| test-profile | シリアル通信プロファイル(SSP)やHands Free Profile(HFP)などで使われる共通のProtocolであるRFCOMM. これをProfileという概念で制御しています. このテストでは引数でパラメータを指定して、Profileを登録します. (そのあと、Profileに対して NewConnection()を要求すれば接続されるはず) |
| pbap-client | PhoneBook Access Profile (PBAP)のOBEX Clientを接続するサンプルです. その後、対話方式で電話帳のindexやサイズを選択すると、接続中の携帯電話の電話帳情報(vCard)を表示できます. |
| map-client | Message Access Profile (MAP)のClientサンプル. こちらも中身は OBEXのClientを接続します. |
| ftp-client | File Transfer Profile(FTP)のClientサンプル |
| opp-client | Object Push Profile (OPP)の Clientサンプルです. 古い仕様なので省略 |
| sap_client.py | SIM Access Profileです. かなり古いプロファイルですね |
| simple-endpoint | 電話音声(HFP)やストリーミング転送(A2DP)の音声出力先も制御する MediaのAPIのサンプル |
| simple-player | 上述のMediaを制御するMediaPlayerのサンプル. このサンプルを使って、ラズパイでBluetoothスピーカにする記事がありますね |
| test-hfp | Profileを使ってHFPのRFCOMMを接続し、ATコマンドで制御するサンプルです. |
| test-network | 接続中のデバイスに対して Personal Area Network(PAN)などの接続を要求するテスト. Network APIのConnect()を実行しています. |
| test-nap | こちらはPANなどのServer側のテスト. NetworkServer APIの Register()を実行しています. |
サンプルコードを実際に動かしてみる
実際に、test/フォルダ以下の各pythonのコードを動かしてみましょう
list-devices
testフォルダのlist-devicesを覗いてみると、以下の実装を確認できます
manager = dbus.Interface(bus.get_object("org.bluez", "/"),
"org.freedesktop.DBus.ObjectManager")
...
objects = manager.GetManagedObjects()
D-Busのサービス org.bluezで管理しているObjectsから、デバイス情報を出力するコードだとわかります。
実際に動かしてみます.
$ ./list-devices
[ /org/bluez/hci0 ]
Name = ubuntu
Powered = 1
Modalias = usb:v1D6Bp0246d052B
DiscoverableTimeout = 0
Alias = ubuntu
PairableTimeout = 0
Discoverable = 0
Address = 00:XX:XX:XX:XX:XX
Discovering = 0
Pairable = 1
Class = 786700
UUIDs = 0x1112 0x1801 0x110e 0x1800 0x1200 0x110c 0x110a 0x110b
[ /org/bluez/hci0/dev_XX_XX_XX_XX_XX_EC ]
Name = M720 Triathlon
Paired = 1
Modalias = usb:v046DpB015d0007
Adapter = /org/bluez/hci0
ServicesResolved = 1
Appearance = 962
LegacyPairing = 0
Alias = M720 Triathlon
Connected = 1
UUIDs = 0x1800 0x1801 0x180a 0x180f 0x1812 00010000-0000-1000-8000-011f2000046d
Address = XX:XX:XX:XX:XX:EC
Blocked = 0
Trusted = 1
Icon = input-mouse
[ /org/bluez/hci0/dev_XX_XX_XX_XX_XX_26 ]
...
bluezの getManagedObjects()の結果を表示できました.筆者の環境では、前半が自デバイス(ubuntu)、後半がペアリング済みデバイス(M720)の情報になりました.
どのようにPythonからD-Busを呼び出しているのか？を詳細に説明するのは難しいのですが、ここではPythonのサンプルコードでBlueZを制御できている. という事を実感して頂ければと思います.
(ちなみに、dbus-pythonのチュートリアルはこちらを参照してください.)
monitor-bluetooth
test/フォルダ以下のmonitor-bluetoothは、BlueZのD-Busのやり取りを出力するテストコードです.
試しに、周辺のBluetooth機器を探索して、D-Busの受信を確認してみます.
ターミナルを2個開いて、一つのターミナルで monitor-bluetoothを実行します.
次に、別のターミナルで、bluetoothctlを使ってscan onを実行します.
$ bluetoothctl
[HHKB-BT]# scan on
Discovery started
[CHG] Controller 00:E1:8C:23:60:C1 Discovering: yes
[NEW] Device XX:8A:9F:9D:AB:EE XX-8A-9F-9D-AB-EE
[NEW] Device 4F:XX:9D:85:59:2D 4F-XX-9D-85-59-2D
[NEW] Device 66:15:XX:01:FB:FD 66-15-XX-01-FB-FD
[NEW] Device 46:E8:80:XX:20:5A 46-E8-80-XX-20-5A
[NEW] Device 56:DF:07:F3:XX:F0 56-DF-07-F3-XX-F0
[NEW] Device 8C:85:90:77:1A:XX 8C-85-90-77-1A-XX
[NEW] Device XX:43:62:9D:FE:AA XX-43-62-9D-FE-AA
[NEW] Device 4D:XX:14:F0:4B:78 4D-XX-14-F0-4B-78
すると、monitor-bluetoothを実行しているターミナル側に、
BlueZに関するD-Busのメッセージの内容が出力されてきます.
$ ./monitor-bluetooth
{Adapter1.PropertyChanged} [/org/bluez/hci0] Discovering = 1
{Added org.bluez.Device1} [/org/bluez/hci0/dev_XX_XX_XX_XX_XX_XX]
Paired = 0
ServicesResolved = 0
Adapter = /org/bluez/hci0
LegacyPairing = 0
Alias = XX_XX_XX_XX_XX_XX
Connected = 0
UUIDs = dbus.Array([], signature=dbus.Signature('s'), variant_level=1)
Address = XX:XX:XX:XX:XX:XX
RSSI = -65
Trusted = 0
Blocked = 0
{Added org.bluez.Device1} [/org/bluez/hci0/dev_XX_XX_XX_XX_XX_XX]
Paired = 0
ServicesResolved = 0
Adapter = /org/bluez/hci0
LegacyPairing = 0
Alias = XX-XX-XX-XX-XX-XX
...
...
実際に通信してみると、BlueZがどのようなメッセージ(Signal)をD-Bus上で通知してくるのかがわかるので、使えそうなメッセージがあれば、signalハンドラをdbus-pythonに登録して検出する事ができます.
また、デバッグ用途でも使えるかも.
example-gatt-server
今回、一番の目的だった、BLEのGATT通信が動作するサンプルコードです.
このサンプルコードは、GATT Serverが動作します.
コードを覗いて見ると、以下のGATT Serviceを立ち上げています.
- Battery Service (UUID=
0x1801) - Heart Rate (UUID=
0x180D) - Test Service (UUID=
12345678-1234-5678-1234-56789abcdef0)
実際にBattery ServiceやHeart Rate Serviceは実装しておらず、あくまでもエミュレートしたものになっています.
例えばHeart Rateはランダムな値を通知しますし、Battery Serviceは5秒毎に値が減っていき、その変化を通知する実装になっています.
GObject.timeout_add(5000, self.drain_battery)
def drain_battery(self):
if self.battery_lvl > 0:
self.battery_lvl -= 2
if self.battery_lvl < 0:
self.battery_lvl = 0
print('Battery Level drained: ' + repr(self.battery_lvl))
self.notify_battery_level()
return True
では、本当にBLEの通信ができるか試してみましょう.
サンプルプログラムを、以下の通りターミナルで実行します.
$ ./example-gatt-server
Registering GATT application...
GetManagedObjects
GATT application registered
Battery Level drained: 98
Battery Level drained: 96
Battery Level drained: 94
Battery Level drained: 92
Battery Level drained: 90
Battery Levelが徐々に減ってきていますね.
早速BLEを接続したいのですが、GATT Serverを起動しただけでは、Client側から発見できません.なので、Advertisingする事で周囲のデバイスに対して自分の存在を通知します.
別のターミナルを立ち上げて、以下のコマンドを実行してAdvertisingを開始します.
sudo hciconfig hci0 leadv
この状態で、スマートフォンのBLEテストアプリから、GATT Serverに接続します.
確認には、以下のアプリを使用しました。
- iOS: BLE Scnanner 4.0
- Android: nFR Connect for Mobile
実際に接続した時のスクショです。
Battery LevelやHeart Rateが取れていますね!
最後に
誤記/追記情報がありましたらご指摘頂けるとうれしいです.
次回は、実際にこのサンプルコードを使って、ラズパイに接続した温度センサーの値を通知するGATT Serverを構築できればと思います.