M5stack(ESP32) で Bluetooth(btstack) の機能を利用する際の注意点

btstack は、非同期に処理を行なうため、 各種イベントごとにコールバック関数を登録する方式を採用しています。

例えば、「ペアリングの要求を受けた場合にその要求を許可するかどうか」や、 「接続が切断された場合にどう処理するか」をコールバックに登録した関数で処理します。

どのようなイベントがあり、 そのコールバックではどのような情報を取得できるかは、 以下のソースで確認できます。

btstack/src/btstack_event.h

また、そのコールバックでどのような処理が必要なのかは、 各サンプルプログラムを確認すると分かります。

大部分のイベントは、単に状態を通知するためのものであり、 処理しなければならないイベントは極僅かです。

なお、一つのイベントに対して複数のコールバックを登録できるものと、 一つのイベントに対して 1 つのコールバック登録に制限されるものがあります。

Bluetooth は、ペアリングで取得した情報を保持しておき、 その情報をもとに再起動などの時に再接続を行ないます。

つまり、この情報は不揮発の情報として保持しておく必要があります。

btstack のライブラリ内には、 これらの情報を FLASH の NVS 領域に保持する処理が書かれているので、 ユーザプログラムで直接それらの情報にアクセスする必要はありません。

一方で、ペアリングの情報を削除したい、というようなケースがあると思います。 その場合、以下の関数を呼ぶと、これらの情報を削除できます。

• gap_drop_link_key_for_bd_addr( addr );
• le_device_db_remove( index );

あるいは、少し強引な方法ですが、 NVS の namespace "BTstack" のデータを全て削除し、再起動する方法でも削除可能です。

1
2
3
4
5
6
7

    hid_host_init(s_hid_descriptor_storage, sizeof(s_hid_descriptor_storage));
    hid_host_register_packet_handler(packet_handler_host);

    gap_set_default_link_policy_settings(
        LM_LINK_POLICY_ENABLE_SNIFF_MODE | LM_LINK_POLICY_ENABLE_ROLE_SWITCH);

    hci_set_master_slave_policy(HCI_ROLE_MASTER);

ここでは、classic HID ホストの初期化と、 コールバックの登録を行なっています。

M5stack を device と接続するには、 接続先デバイスの BD_ADDR が必要です。

この BD_ADDR を取得するために、周辺デバイスのスキャンを行ないます。

なお、事前に接続先デバイスの BD_ADDR が分かっている場合、 スキャンは不要です。

このスキャンのサンプルは、以下にあります。

btstack/port/esp32/example/gap_inquiry/main/

接続先デバイスの BD_ADDR を以下の関数に渡すことで、 そのデバイスと接続が行なわれます。

hid_host_connect( addr, s_hid_host_report_mode, &s_hid_info_in.cid);

なお、ペアリングが成功すると、 ペアリング情報が btstack ライブラリによって FLASH ROM の NVS 上に記録されます。

この情報によって、次回からキーボード側からの接続要求を受けることが可能になります。

前述の通り、一度ペアリングすることで、 そのペアリング情報が NVS に記録され、 キーボード側からの接続要求を受けることが可能になります。

この接続要求を受けると、 HID_SUBEVENT_INCOMING_CONNECTION イベントのコールバック関数が呼び出されます。

このコールバック関数で以下を実行することで、 接続要求が受け入れられて接続が確立します。

hid_host_accept_connection( cid, s_hid_host_report_mode );

ここでは、classic HID device の初期化と、 コールバックの登録を行なっています。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

    gap_set_class_of_device( bt_kb_getCod() );
    gap_set_local_name( s_hid_device_name );
    
    gap_set_default_link_policy_settings(
        LM_LINK_POLICY_ENABLE_ROLE_SWITCH | LM_LINK_POLICY_ENABLE_SNIFF_MODE );
    gap_set_allow_role_switch(true);

    hid_create_sdp_record(s_hid_service_buffer, 0x10001, &hid_params);

    sdp_register_service(s_hid_service_buffer);

    device_id_create_sdp_record(
        s_device_id_sdp_service_buffer, 0x10003,
        DEVICE_ID_VENDOR_ID_SOURCE_BLUETOOTH,
        BLUETOOTH_COMPANY_ID_BLUEKITCHEN_GMBH, 1, 1);

    sdp_register_service(s_device_id_sdp_service_buffer);

    hid_device_init(hid_boot_device, hidDescriptorLen, pHidDescriptor );

    s_hci_event_callback_registration.callback = &packet_handler;
    hci_add_event_handler(&s_hci_event_callback_registration);

    hid_device_register_packet_handler(&packet_handler_device);

PC 側のスキャンでリストされるように、 discoverable を有効にします。

gap_discoverable_control( 1 );

この状態で、 PC 側からペアリング処理を行なうと、ペアリングが完了します。

ペアリングが完了しても、 キーの押下情報を送るにはライブラリ側の準備が必要です。

その送信準備を要求するのが、以下の関数です。

hid_device_request_can_send_now_event( s_hid_info_out.cid );

hid_device_request_can_send_now_event() の送信要求によって、 送信準備が行なわれ、準備が整うと HID_SUBEVENT_CAN_SEND_NOW イベントの コールバックが呼ばれます。 このコールバックで以下を実行することで、レポートが送信されます。

hid_device_send_interrupt_message( cid, hidReport, sizeof(hidReport));

前述の送信要求と、送信は非同期に行なわれるので、注意が必要です。

ペアリング後、再起動時などで devicd 側からホストに接続する場合、以下を実行します。

key_hid_device_connect( addr );

ここでは、classic HID device の初期化と、 コールバックの登録を行なっています。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

    sm_set_io_capabilities(IO_CAPABILITY_NO_INPUT_NO_OUTPUT);

    sm_set_authentication_requirements(
        SM_AUTHREQ_SECURE_CONNECTION | SM_AUTHREQ_BONDING);

    // setup ATT server
    att_server_init(profile_data, NULL, NULL);

    // setup battery service
    battery_service_server_init( 100 );

    // setup device information service
    device_information_service_server_init();

    // setup HID Device service
    hids_device_init(0, get_hidDescriptor(), get_hidDescriptorLen() );

    // setup advertisements
    gap_advertisements_set_params(
        adv_int_min, adv_int_max, adv_type, 0, null_addr, 0x07, 0x00);
    gap_advertisements_set_data( sizeof(adv_data), (uint8_t*) adv_data);
    
    // register for SM events
    static btstack_packet_callback_registration_t sm_event_callback_registration;
    sm_event_callback_registration.callback = packet_handler;
    sm_add_event_handler(&sm_event_callback_registration);

    // register for HIDS
    hids_device_register_packet_handler(packet_handler);

PC 側のスキャンでリストされるように、 discoverable を有効にします。

gap_advertisements_enable(1);

PC 側からペアリング要求が来た際、 そのペアリングを受け入れるかどうかをコールバックで処理します。

発生するイベントは、 BLE を初期化した時の以下の関数の引数によって変わります。

sm_set_io_capabilities();

sm_passkey_input()

sm_just_works_confirm(sm_event_just_works_request_get_handle(packet));

sm_bonding_decline( sm_event_just_works_request_get_handle(packet) );

sm_event_numeric_comparison_request_get_passkey(packet)

sm_numeric_comparison_confirm( sm_event_numeric_comparison_request_get_handle(packet));

sm_bonding_decline( sm_event_numeric_comparison_request_get_handle(packet) );

sm_event_passkey_display_number_get_passkey(packet)

sm_passkey_input()

ペアリングが完了しても、 キーの押下情報を送るにはライブラリ側の準備が必要です。

その送信準備を要求するのが、以下の関数です。

hids_device_request_can_send_now_event( s_con_handle );

前述の送信要求によって、 送信準備が行なわれ、準備が整うと HIDS_SUBEVENT_CAN_SEND_NOW イベントの コールバックが呼ばれます。 このコールバックで以下を実行することで、レポートが送信されます。

hids_device_send_boot_keyboard_input_report()

あるいは

hids_device_send_input_report() 

前述の送信要求と、送信は非同期に行なわれるので、注意が必要です。

ペアリング後、再起動時などで devicd 側からホストに接続する場合、以下を実行します。

gap_advertisements_enable(1);

以上。