用户工具

站点工具


侧边栏

CC2640R2&BLE5.0开发

关于我们

入门开始

视频教程

外设驱动

开发BLE应用

工具集

其他

cc2640r2f:gatt_servapp_module

GATT ServApp 模块

GATT 服务器应用程序(GATT ServApp)用于存储和管理应用程序范围的属性表,各种配置文件使用此模块将其特性添加到属性表。

蓝牙低功耗协议栈使用此模块来响应 GATT 客户端的发现请求。例如,GATT 客户端可以发送 Discover all Primary Characteristics 消息,GATT 服务器端的蓝牙低功耗协议栈接收到该消息,使用 GATT ServApp 查找并发送存储在属性表中的所有主要特性。

这种类型的功能超出了本文档的范围,它们是在库代码中实现的。您可以从 gattservapp_util.c 中定义配置文件,也可以从 BLE Stack API Reference( GATT ServApp 部分)中描述的 API 来查看 GATT ServApp 函数,函数功能包括查找特定属性和阅读修改客户端特征配置。

图1. GATT ServApp 的功能示例

GATT ServApp 在应用程序中的功能示例如图 1,图中示意了属性表的初始化,对应着 GATT Services 和 Profile 中的属性表。该流程图是程序上下文的具体实现过程,程序中分别使用了 GGS_Addservice()、GATTServApp_AddService()、DevInfo_AddService()、SimpleProfile_AddService(),一步一步在 GATT Server 中构建了属性表。

构建属性表

上电或重置时,应用程序通过 GATT ServApp 创建 GATT 表添加服务,每个服务都包含具体 UUID 值、权限以及读取和写入回调的属性列表。正如图 1 所示,所有这些信息是通过 GATT ServApp 传递到 GATT 并存储在堆栈中。

属性表初始化必须在应用程序初始化函数中出现,也就是 simple_peripheral_init()。

    //初始化 GATT 属性
    GGS_AddService (GATT_ALL_SERVICES );          // GAP 
    GATTServApp_AddService (GATT_ALL_SERVICES );  // GATT 属性

在属性表中实现配置文件

属性表的定义

GATT 属性的每个服务或组必须定义一个固定大小的属性表,该表被传递到 GATT 中。 simple_gatt_profile.c 中的此表定义如下:

    static  gattAttribute_t  simpleProfileAttrTbl [ SERVAPP_NUM_ATTR_SUPPORTED ]

表中的每个属性都是以下类型:

    typedef struct attAttribute_t
    {
       gattAttrType_t type; //!< 属性类型(2 或 16 个八位字节 UUID)
       uint8 permissions;   //!< 属性权限

       uint16 handle;        //!< 属性句柄-由属性服务器内部分配

       uint8* const pValue; //!< 属性值 -属性值的最大长度为 512 octets。
    } gattAttribute_t;
  • gattAttrType_t 类型
    type 是与放置在表中的属性相关联的 UUID 。gattAttrType_t 本身定义为:
    typedef  struct 
    { 
       uint8  len ;          //!<UUID 的长度(2或16)
       const  uint8  * uuid ;  //!<指向 UUID 的指针
    }  gattAttrType_t ;

其中长度可以是 ATT_BT_UUID_SIZE(2字节)或 ATT_UUID_SIZE(16字节)。* uuid 是指向蓝牙 SIG(定义在 gatt_uuid.c 中)或配置文件中定义的自定义 UUID 保留的数字指针。

  • uint8 权限
    强制 GATT 客户端设备如何读取和访问该属性的值,可能的权限在 gatt.h 中定义如下:

    宏定义 16进制数 权限
    #define GATT_PERMIT_READ 0x01 可读
    #define GATT_PERMIT_WRITE 0x02 可写
    #define GATT_PERMIT_AUTHEN_READ 0x04 认证后可读
    #define GATT_PERMIT_AUTHEN_WRITE 0x08 认证后可写
    #define GATT_PERMIT_AUTHOR_READ 0x10 授权后可读
    #define GATT_PERMIT_AUTHOR_WRITE 0x20 授权后可写
    #define GATT_PERMIT_ENCRYPT_READ 0x40 读需要加密
    #define GATT_PERMIT_ENCRYPT_WRITE 0x80 写需要加密

    这里的认证、授权、加密后面 GATT 内存分配部分还会详细说明。

  • uint16 handle
    handle 不可修改,由属性服务器内部分配(顺序分配)。

  • * uint8 const pValue **
    pValue 是指向属性值的指针,初始化后大小无法更改,最大为 512 个字节。

Service 声明

参考下面 simple_gatt_profile service 声明:

    // Simple Profile Service 
    { 
       {  ATT_BT_UUID_SIZE , primaryServiceUUID  },    // type 
       GATT_PERMIT_READ ,                               // permissions 
       0 ,                                              // handle 
       (uint8  * )&simpleProfileService                // pValue 
    }

其中 type 设置的是蓝牙 SIG 规范定义的主服务 UUID(0x2800),权限为可读( GATT_PERMIT_READ),允许客户端读取该服务。pValue 是指向服务的 UUID的指针,自定义为 0xFFF0。

    // Simple Profile Service 属性
    static  CONST  gattAttrType_t  simpleProfileService  = 
       { 
          ATT_BT_UUID_SIZE ,
          simpleProfileServUUID 
       };

characteristic Declaration

参考下面 simple_gatt_profile Characteristic1 Declaration:

    //特征 1 声明
    { 
       {  ATT_BT_UUID_SIZE , characterUUID  }, // type 
       GATT_PERMIT_READ ,                       // permissions 
       0 ,                                      // handle 
       &simpleProfileChar1Props                 // pValue 
    },

type 设置为蓝牙 SIG 定义的 characteristic UUID(0x2803),权限为可读(GATT_PERMIT_READ),允许客户端读取该服务。对于 characteristic Declaration 中的 pValue 值,传递给 GATT ServApp,GATT ServApp 只需要 characteristic Value 的权限。所以在 characteristic Declaration 的 pValue 值传递了 characteristic Value 的权限,可读可写(0x0A)。GATT ServApp 会自动构建 characteristic value 的 handle 和 UUID ,然后放入 characteristic Declaration 的 pValue 的 2-4 个字节中。

注意:characteristic Declaration 中的 pValue 和 characteristic Value 中的权限是有区别的,前者是 GATT 客户端可以读取看见的属性,后者是 characteristic Value 的真实权限,这意味着他们必须要一致,不然会混淆 GATT 客户端的开发者。

客户端 Characteristic Configuration

首先要明白一点,前面说的 characteristic value 1、2、3、5 都是客户端发送读写命令,然后服务端响应处理并返回。但 characteristic 4 value 不具有读写权限,它仅仅是通知属性,只能是服务端发送给客户端。

下面代码设置了 characteristic config 的可读可写属性,客户端可以配置 characteristic 4 value,比如当前就是禁用通知。客户端可以设置 characteristic config 的值来控制通知属性。

参考 simple_gatt_profile 中 Characteristic 4 配置:

      // Characteristic Value 4
      { 
        { ATT_BT_UUID_SIZE, simpleProfilechar4UUID },
        0, 
        0, 
        &simpleProfileChar4 
      },

     //Characteristic 4 configuration
     { 
     {  ATT_BT_UUID_SIZE , clientCharCfgUuID  },
       GATT_PERMIT_READ  |  GATT_PERMIT_WRITE ,
       0 ,
       (uint8  * )&simpleProfileChar4Config 
      },

添加服务功能

如 GATT ServApp 模块所述,应用启动时需要添加支持的 GATT 服务。每个配置文件都需要一个全局 AddService 函数,用于被应用程序调用。其中一些服务在协议栈中定义,如 GAP GATT 服务和 GATT 服务。用户定义的服务必须公开自己的 AddService 函数,该应用程序可以调用配置文件初始化。以 SimpleProfile_AddService()为例,这些功能应该如下:

  • 为客户端特征配置(CCC)阵列分配空间。作为示例,指向这些数组之一的指针在配置文件中初始化,如 client_characteristic_configuration 中所述。
    AddService 函数需要声明支持的连接,并为每个数组分配内存。只有一个 CCC 在 simple_gatt_profile 中定义,但可以有多个 CCC 。当有多个设备连接服务端,服务端的 simpleProfileChar4Config 必须为每个连接了的客户端分配一个内存,用于为每个设备保存通知配置。
        //分配客户端特征配置表
        simpleProfileChar4Config  =  (gattCharCfg_t  * )ICall_malloc (sizeof (gattCharCfg_t ) *  linkDBNumConns  );

        if  ( simpleProfileChar4Config  ==  NULL  )
        { 
        return  ( bleMemAllocError  ); 
        }
  • 使用下面的函数初始化 CCC 数组,这样 CCC 值在掉电之后也能够保存下来。可以在连接设备时尝试使用之前保存的值,如果连接设备是新的设备则使用默认值。
    `GATTServApp_InitCharCfg ( INVALID_CONHANDLE , simpleProfileChar4Config  );`
  • 使用 GATTServApp_RegisterService 注册配置文件。该函数功能是将配置文件的属性表传递给 GATT ServApp,以便将配置文件的属性添加到由协议栈管理的应用程序属性表中,并为每个属性分配句柄。这也将配置文件的回调指针传递给堆栈,以启动 GATT ServApp 和配置文件之间的通信。
    //Register GATT attribute list and CBs with GATT Server App
    status =  GATTServApp_RegisterService ( simpleProfileAttrTbl ,
                                          GATT_NUM_ATTRS ( simpleProfileAttrTbl  ),
                                          GATT_MAX_ENCRYPT_KEY_SIZE ,
                                          &simpleProfileCBs  );

注册应用程序回调函数

配置文件可以使用回调将邮件中继到应用程序。在 simple_peripheral 项目中,只要 GATT 客户端写入特征值,simple_gatt_profile 将调用应用程序回调。如果要使用这些应用程序回调,配置文件必须定义一个注册应用程序回调函数,该应用程序在初始化期间用于设置回调。simple_gatt_profile 的注册应用程序回调函数如下:

        bStatus_t  SimpleProfile_RegisterAppCBs ( simpleProfileCBs_t  * appCallbacks  )
        { 
           if  ( appCallbacks  )
           { 
              simpleProfile_AppCBs  =  appCallbacks ; 
              返回 ( SUCCESS  ); 
           }

           else 
           { 
              return  ( bleAlreadyInRequestedMode  ); 
           } 
        }

其中回调 typedef 被定义为:

        typedef  struct 
        { 
           simpleProfileChange_t  pfnSimpleProfileChange ;  //当特征值更改时调用
        }  simpleProfileCBs_t ;

然后,应用程序必须定义此类型的回调,并将其传递给具有 SimpleProfile_RegisterAppCBs()函数的 simple_gatt_profile 。这发生在 simple_peripheral.c 中,代码如下所示:

    //简单的 GATT 配置文件回调
    #ifndef FEATURE_OAD_ONCHIP 
    static  simpleProfileCBs_t  SimpleBLEPeripheral_simpleProfileCBs  = 
    { 
       SimpleBLEPeripheral_charValueChangeCB  //特征值更改回调
    }; 
    #endif //!FEATURE_OAD_ONCHIP

    // ...

    //使用 SimpleGATTprofile 注册回调
    SimpleProfile_RegisterAppCB (&SimpleBLEPeripheral_simpleProfileCBs );

上述操作完成之后,一旦 characteristic 中 value 改变,SBP_CHAR_CHANGE_EVT 事件被更新,应用程序就可以收到并处理改变的值。

客户端读请求

如图 2 所示当接收到来自 GATT 客户端的读取请求时,协议栈先检查属性的权限。如果属性可读,则调用 Profile 读回调函数。Profile 复制该值,并在 profile 层执行特定处理,由 ATT_ReadRsp 指令发送给协议栈,协议栈使用 ATT_READ_RSP 发送给客户端。

图2. 客户端读请求流程

客户端写请求

当收到来自 GATT 客户端给定属性的写请求时,协议栈会检查属性的权限。如果该属性是允许写的,则调用该配置文件的回调。配置文件存储要写入的值,执行 profile 层的响应处理,并在需要时通知应用程序。图 3 显示了 simple_gatt_profile 中 simpleprofileChar3 的写入过程。

图3. 客户端写请求流程

注意:协议栈程序最小化处理非常重要,在该示例中,应用程序在上下文中通过消息队列的方式处理 value 改变之后的额外过程。

获取和设置函数

包含 characteristic 的配置文件应为应用程序提供 set 和 get 抽象功能,以读取和写入配置文件的 characteristic 。设置参数功能还包括如果相关 characteristic 有通知或指示属性,则检查并实现通知和指示的逻辑。

下图 4 是在 simple_gatt_profile 中设置 simpleProfile Chacteristic 4 的例子。

图4. 设置 Chacteristic 4 示例

应用程序在 simple_peripheral.c 中将 simpleProfile Characteristic 4 初始化为 0 ,代码如下:

    uint8_t charValue4 = 0;
    SimpleProfile_SetParameter(SIMPLEPROFILE_CHAR4, sizeof(uint8_t), &charValue4);

以下代码片段在 simple_gatt_profile.c 中,除了设置静态 simpleProfileChar4 的值之外,该函数还调用 GATTServApp_ProcessCharCfg()。这个调用操作会强制 GATT ServApp 检查 GATT 客户端是否已启用通知,如果启用,GATT ServApp 会向 GATT 客户端发送此属性的通知。

    bStatus_t SimpleProfile_SetParameter( uint8 param, uint8 len, void *value )
    {
      bStatus_t ret = SUCCESS switch ( param )
      {
      case SIMPLEPROFILE_CHAR4:
      if ( len == sizeof ( uint8 ) )
      {
        simpleProfileChar4 = *((uint8*)value);

        // See if Notification has been enabled
        GATTServApp_ProcessCharCfg( simpleProfileChar4Config, &simpleProfileChar4, FALSE,
                                        simpleProfileAttrTbl, GATT_NUM_ATTRS( simpleProfileAttrTbl ),
                                        INVALID_TASK_ID, simpleProfile_ReadAttrCB );
    }

队列写

当接收到多个写指令是,GATT 服务端通过排队方式处理更多的有效数据。默认队列大小为 5 ,默认 MTU 为 23,有效载荷为 18 字节,最多可以接收 90 个字节的有效载荷。有关排队写入的更多信息,请参阅蓝牙核心规范版本 5.0 的排队写入部分([Vol 3],F部分,第3.4.6节)。

使用 GATTServApp_SetParameter()与参数调整队列大小 GATT_PARAM_NUM_PREPARE_WRITES。虽然没有指定的限制,但它由可用的 HEAPMGR 空间限定。

为 GATT 程序分配内存

GATT 和 ATT 有效载荷结构必须动态分配内存。例如,发送 GATT_Notification 时必须分配缓冲区。这里有两种方法,一种是上面讲过的首选方式调用 SimpleProfile_SetParameter(),另一种是直接使用 GATT_Notification()或 GATT_Indication()。其实本质上S impleProfile_SetParameter()也是调用的 GATT_Notification()或 GATT_Indication()。

如果直接使用 GATT_Notification()或 GATT_Indication(),则必须如下添加内存管理(gattServApp_SendNotiInd中)。

  1. 尝试使用 GATT_bm_alloc()为通知或指示有效载荷分配内存。
  2. 如果分配成功,则使用 GATT_Notification()或 GATT_Indication()发送通知或指示。

    注意:如果通知或指示的返回值为 SUCCESS (0x00),则堆栈释放内存。

  3. 如果返回值不是 SUCCESS,则使用 GATT_bm_free()来释放内存。以下是 GATTServApp_SendNotiInd gattservapp_util.c 文件中函数的一个示例。
        noti.pValue = (uint8 *)GATT_bm_alloc( connHandle, ATT_HANDLE_VALUE_NOTI, GATT_MAX_MTU, &len );

        if ( noti.pValue != NULL )
        {
           status = (*pfnReadAttrCB)( connHandle, pAttr, noti.pValue, &noti.len, 0, len, GATT_LOCAL_READ );

           if ( status == SUCCESS )
           {
              noti.handle = pAttr->handle;

              if ( cccValue & GATT_CLIENT_CFG_NOTIFY )
              {
                 status = GATT_Notification( connHandle, &noti, authenticated );
              }

              else // GATT_CLIENT_CFG_INDICATE
              {
                 status = GATT_Indication( connHandle, (attHandleValueInd_t *)&noti, authenticated, taskId );
              }
           }

           if ( status != SUCCESS )
           {
              GATT_bm_free( (gattMsg_t *)&noti, ATT_HANDLE_VALUE_NOTI );
           }
        }

        else
        {
           status = bleNoResources;
        }

注册接收应用程序中的其他 GATT 事件

使用 GATT_RegisterForMsgs() 可以接收额外的 GATT 消息处理某些角落情况,这些情况可以在 SimpleBLEPeripheral_processGATTMsg() 中看到,目前处理以下三种情况。

  • 堆栈中的 GATT 服务器无法发送 ATT 响应(由于缺少可用的 HCI 缓冲区):尝试在下一个连接间隔发送。另外,如果在蓝牙核心规范版本 5.0 中指定的 ATT 事务在 30 秒内未完成,则会发送 bleTimeout 状态。
        // See if GATT server was unable to transmit an ATT response
        if (pMsg->hdr.status == blePending)
        {
        //No HCI buffer was available. Let's try to retransmit the response
        //on the next connection event.

        if (HCI_EXT_ConnEventNoticeCmd(pMsg->connHandle, selfEntity, SBP_CONN_EVT_END_EVT) == SUCCESS)
        {
        //First free any pending response
         SimpleBLEPeripheral_freeAttRsp(FAILURE);

         //Hold on to the response message for retransmission
         pAttRsp = pMsg;

         //Don't free the response message yet
         return (FALSE);
         }
         }
  • ATT 流量控制违规:通知应用程序连接的设备违反 ATT 流量控制规范,例如发送指示确认之前发送读取请求。在连接过程中,无需更多的 ATT 请求或指示。应用程序可能希望由于此违规而终止连接。作为 simple_peripheral 的一个例子,display 被更新。
        else if (pMsg->method == ATT_FLOW_CTRL_VIOLATED_EVENT)
        {
          //ATT request-response or indication-confirmation flow control is
          //violated. All subsequent ATT requests or indications will be dropped.
          //The app is informed in case it wants to drop the connection.

          //Display the opcode of the message that caused the violation.
          DISPLAY_WRITE_STRING_VALUE("FC Violated: %d", pMsg->msg.flowCtrlEvt.opcode, LCD_PAGE5);
        }
  • 更新 ATT MTU大小:通知应用程序,以防任何方式影响其处理。有关 MTU 的更多信息,请参见最大传输单元(MTU)。作为 simple_peripheral 的一个例子,display 被更新。
        else if (pMsg->method == ATT_MTU_UPDATED_EVENT)
        {
            // MTU size updated
            DISPLAY_WRITE_STRING_VALUE("MTU Size: $d", pMsg->msg.mtuEvt.MTU, LCD_PAGE5);
        }

加入我们

文章所有代码、工具、文档开源。加入我们QQ群 591679055获取更多支持,共同研究CC2640R2F&BLE5.0。

CC2640R2F&BLE5.0-乐控畅联 © Copyright 2017, 成都乐控畅联科技有限公司.

cc2640r2f/gatt_servapp_module.txt · 最后更改: 2021/06/22 23:14 (外部编辑)