<markdown>
BGAPI
=====

## はじめに

BGAPIは**command**，**response**，**event**という3種類の処理によって動作する、
イベントドリブンな軽量APIです。実体は適切なフォーマットの16進数を送受信しているだけであり、
さまざまなプログラミング言語に簡単に移植することが可能です。  
(参考：[Python, C#, Arduino向けの実装例](https://github.com/jrowberg/bglib))

本文章では、BlueGiga社の提供するBLESDKに同梱されている**bglib**の使用方法について、
簡単に解説していきたいと思います。


## 基本概念

BLE機器との接続，キャラクタリスティックの読み書き等の基本的な処理はもちろん、
複雑なシステムコマンドまで、全てが関数として実装されています。
ユーザはそれらを呼び出すだけで、BGAPIの全ての機能にアクセスすることが可能です。  
(実装ファイル：anytypes.h, cmd_def.h, cmd_def.h)

PCから使用する場合、BlueGiga社のBLEドングル，BLED112に仮想COMドライバからアクセスし、
BGAPIの**command**を送信します。**command**は受理された場合、必ず**response**を返してきます。
これを仮想COMから読み込み解析することで、ユーザは**command**の実行結果等の詳細な情報を得ることができます。

また、いくつかの処理は結果を**event**として、不定期に返却してきます。
なので、そうした処理に対しては実行後、複数回の仮想COMからの読み出しが必要となります。

こうした**response**と**event**は、イベントハンドラで処理することを想定しています。
なので、ユーザはその実装を適宜書き換えることで任意の動作を実現します。  
(実装ファイル：commands.c)


## 下準備

### 1. ドライバのインストール
[BLED112の製品ページ](https://www.bluegiga.com/en-US/products/bled112-bluetooth-smart-dongle/)から、
ドライバをダウンロードします。(ダウンロードには会員登録が必要です。)

### 2. シリアル通信処理の実装
BGAPIを使用するにあたって、コマンド送信処理とメッセージループを独自に実装する必要があります。
**scan_example**内の**output関数**，**read_message関数**がそれぞれ参考になるかと思います。

注意点として、おそらく仮想COMのドライバは全二重通信に対応していません。
そのため、仮想COMの読み書きは排他制御される必要があります。


## BGAPIを用いたBLE接続手順

簡単のため、一部の**command**の引数の解説や、**response**の発生タイミングについては記述しません。

1. **ble_cmd_gap_end_procedure()**  
   現在のGAP接続および、BLE機器の検索を終了します。

2. **ble_cmd_connection_disconnect(uint8 handle)**  
   *handle*に指定した接続を破棄し、その接続を利用可能な状態にします。

3. **ble_cmd_gap_discover(args...)**  
   アドバタイズ状態のBLE機器を検索します。
   検索結果は**ble_evt_connection_status()**として発生し、
   そのイベントハンドラ内で参照することが可能です。

4. **ble_cmd_gap_connect_direct(bd_addr address, args...)**  
   *address*に6byteのmacアドレスを指定することで、そのBLE機器へ接続します。
</markdown>