dis_c.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file dis_c.h
5 *
6 * @brief Device Information Service Client API
7 *
8 *****************************************************************************************
9 */
10 
11 /**
12  * @addtogroup BLE_SRV BLE Services
13  * @{
14  * @attention
15  #####Copyright (c) 2019 GOODIX
16  All rights reserved.
17 
18  Redistribution and use in source and binary forms, with or without
19  modification, are permitted provided that the following conditions are met:
20  * Redistributions of source code must retain the above copyright
21  notice, this list of conditions and the following disclaimer.
22  * Redistributions in binary form must reproduce the above copyright
23  notice, this list of conditions and the following disclaimer in the
24  documentation and/or other materials provided with the distribution.
25  * Neither the name of GOODIX nor the names of its contributors may be used
26  to endorse or promote products derived from this software without
27  specific prior written permission.
28 
29  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
30  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
31  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
32  ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
33  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
34  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
35  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
36  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
37  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
38  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
39  POSSIBILITY OF SUCH DAMAGE.
40  *****************************************************************************************
41  */
42 
43 /**
44  * @defgroup BLE_SDK_DIS_C Device Information Service Client (DIS_C)
45  * @{
46  * @brief Device Information Service Client module.
47  *
48  * @details The Device Information Service Client contains the APIs and types, which can be used by the
49  * application to discover Device Information Service of peer and interact with it.
50  *
51  * The application must provide an event handler to register, then call \ref dis_client_init().
52  * After Device Information Service Client discovers peer Device Information Service,
53  * application calls \ref dis_c_char_value_read() and get peer device information.
54  */
55 
56 #ifndef __DIS_C_H__
57 #define __DIS_C_H__
58 
59 #include "gr55xx_sys.h"
60 #include "ble_prf_types.h"
61 #include "custom_config.h"
62 #include <stdint.h>
63 #include <stdbool.h>
64 
65 /**
66  * @defgroup DIS_C_MACRO Defines
67  * @{
68  */
69 #define DIS_C_CONNECTION_MAX (10 < CFG_MAX_CONNECTIONS ?\
70  10 : CFG_MAX_CONNECTIONS) /**< Maximum number of DIS Client connections. */
71 #define DIS_C_STRING_LEN_MAX 128 /**< Maximal length for Characteristic values - 128 bytes. */
72 
73 /**
74  * @defgroup DIS_IEEE_11073_BODY IEEE 11073-20601 Authoritative Body Type
75  * @{
76  */
77 #define DIS_C_11073_BODY_EMPTY 0 /**< Empty body type. */
78 #define DIS_C_11073_BODY_IEEE 1 /**< IEEE body type. */
79 #define DIS_C_11073_BODY_CONTINUA 2 /**< Continua body type. */
80 #define DIS_C_11073_BODY_EXP 254 /**< Exp body type. */
81 /** @} */
82 
83 /** @} */
84 
85 /**
86  * @defgroup DIS_C_ENUM Enumerations
87  * @{
88  */
89 /**@brief Device Information Service Client event type. */
90 typedef enum
91 {
92  DIS_C_EVT_INVALID, /**< DIS Client invalid event. */
93  DIS_C_EVT_DISCOVERY_COMPLETE, /**< DIS Client has found Device Information Service and its characteristics. */
94  DIS_C_EVT_DISCOVERY_FAIL, /**< DIS Client found DIS service failed because of invalid operation or no found at the peer. */
95  DIS_C_EVT_DEV_INFORMATION_READ_RSP, /**< DIS Client has received device information value read response. */
97 
98 /**@brief Device Information Service Client characteristic type. */
99 typedef enum
100 {
101  DIS_C_SYS_ID, /**< System ID characteristic. */
102  DIS_C_MODEL_NUM, /**< Model Number String characteristic. */
103  DIS_C_SERIAL_NUM, /**< Serial Number String characteristic. */
104  DIS_C_HW_REV, /**< Hardware Revision String characteristic. */
105  DIS_C_FW_REV, /**< Firmware Revision String characteristic. */
106  DIS_C_SW_REV, /**< Software Revision String characteristic. */
107  DIS_C_MANUF_NAME, /**< Manufacturer Name String characteristic. */
108  DIS_C_CERT_LIST, /**< IEEE 11073-20601 Regulatory Certification Data List characteristic. */
109  DIS_C_PNP_ID, /**< PnP ID characteristic. */
110  DIS_C_CHARACTER_NB /**< Number of all Device Information Service characteristics. */
112 /** @} */
113 
114 /**
115  * @defgroup DIS_C_STRUCT Structures
116  * @{
117  */
118 /**@brief Handles on the connected peer device needed to interact with it. */
119 typedef struct
120 {
121  uint16_t dis_srvc_start_handle; /**< DIS Serivce start handle. */
122  uint16_t dis_srvc_end_handle; /**< DIS Service end handle. */
123  uint16_t dis_char_handle[DIS_C_CHARACTER_NB]; /**< DIS characteristic handle. */
125 
126 /**@brief Response data for string-based DIS characteristics. */
127 typedef struct
128 {
129  uint8_t *p_data; /**< Pointer to response data. */
130  uint16_t length; /**< Response data length. */
132 
133 /**@brief Response data for System ID parameters. */
134 typedef struct
135 {
136  uint8_t manufacturer_id[5]; /**< Manufacturer-defined ID. */
137  uint8_t org_unique_id[3]; /**< Organizationally unique ID (OUI) which is issued by IEEE. */
139 
140 /**@brief Response data for IEEE 11073-20601 Regulatory Certification Data List Structure. */
141 typedef struct
142 {
143  uint8_t *p_list; /**< Pointer to the list which contains the encoded opaque structure based on IEEE 11073-20601 specification. */
144  uint16_t list_length; /**< Length of the list. */
146 
147 /**@brief Response data for PnP ID parameters */
148 typedef struct
149 {
150  uint8_t vendor_id_source; /**< Vendor ID Source. */
151  uint16_t vendor_id; /**< Vendor ID. */
152  uint16_t product_id; /**< Product ID. */
153  uint16_t product_version; /**< Product Version. */
155 
156 /**@brief Device Information Service Client Read Response encode structure. */
157 typedef struct
158 {
159  dis_c_char_type_t char_type; /**< Characteristic type. */
160  union
161  {
162  dis_c_sys_id_t sys_id; /**< System ID characteristic response data. */
163  dis_c_string_t string_data; /**< Model Number, Serial Number, Hardware Revision, Firmware Revision, Software Revision, Manufacturer Name String characteristic response data. */
164  dis_c_reg_cert_data_list_t cert_list; /**< IEEE 11073-20601 Regulatory Certification Data List characteristic response data. */
165  dis_c_pnp_id_t pnp_id; /**< PnP ID characteristic response data. */
166  } encode_rst; /**< Result of encoding. */
168 
169 /**@brief Device Information Service Client event. */
170 typedef struct
171 {
172  uint8_t conn_idx; /**< The connection index. */
173  dis_c_evt_type_t evt_type; /**< DIS Client event type. */
174  ble_dis_c_read_rsp_t read_rsp; /**< DIS Client characteristic Read Response encode. */
175 } dis_c_evt_t;
176 /** @} */
177 
178 /**
179  * @defgroup DIS_C_TYPEDEF Typedefs
180  * @{
181  */
182 /**@brief Device Information Service Client event handler type. */
183 typedef void (*dis_c_evt_handler_t)(dis_c_evt_t *p_evt);
184 /** @} */
185 
186 /**
187  * @defgroup DIS_C_FUNCTION Functions
188  * @{
189  */
190 /**
191  *****************************************************************************************
192  * @brief Register DIS Client event handler.
193  *
194  * @param[in] evt_handler: Device Information Service Client event handler.
195  *
196  * @return Result of initialization.
197  *****************************************************************************************
198  */
200 
201 /**
202  *****************************************************************************************
203  * @brief Discovery Device Information Service on peer.
204  *
205  * @param[in] conn_idx: Index of connection.
206  *
207  * @return Operation result.
208  *****************************************************************************************
209  */
211 
212 /**
213  *****************************************************************************************
214  * @brief Read Device Information Service characteristic value.
215  *
216  * @param[in] conn_idx: Index of connection.
217  * @param[in] char_read_type: Type of characteristic read.
218  *
219  * @return Operation result.
220  *****************************************************************************************
221  */
222 sdk_err_t dis_c_char_value_read(uint8_t conn_idx, dis_c_char_type_t char_read_type);
223 /** @} */
224 
225 #endif
226 
227 /** @} */
228 /** @} */
229 
DIS_C_EVT_DISCOVERY_COMPLETE
@ DIS_C_EVT_DISCOVERY_COMPLETE
DIS Client has found Device Information Service and its characteristics.
Definition: dis_c.h:93
DIS_C_EVT_DISCOVERY_FAIL
@ DIS_C_EVT_DISCOVERY_FAIL
DIS Client found DIS service failed because of invalid operation or no found at the peer.
Definition: dis_c.h:94
ble_dis_c_read_rsp_t
Device Information Service Client Read Response encode structure.
Definition: dis_c.h:158
DIS_C_EVT_DEV_INFORMATION_READ_RSP
@ DIS_C_EVT_DEV_INFORMATION_READ_RSP
DIS Client has received device information value read response.
Definition: dis_c.h:95
ble_dis_c_read_rsp_t::pnp_id
dis_c_pnp_id_t pnp_id
PnP ID characteristic response data.
Definition: dis_c.h:165
DIS_C_MANUF_NAME
@ DIS_C_MANUF_NAME
Manufacturer Name String characteristic.
Definition: dis_c.h:107
dis_c_pnp_id_t::vendor_id_source
uint8_t vendor_id_source
Vendor ID Source.
Definition: dis_c.h:150
dis_c_evt_t::evt_type
dis_c_evt_type_t evt_type
DIS Client event type.
Definition: dis_c.h:173
dis_c_evt_handler_t
void(* dis_c_evt_handler_t)(dis_c_evt_t *p_evt)
Device Information Service Client event handler type.
Definition: dis_c.h:183
ble_dis_c_read_rsp_t::sys_id
dis_c_sys_id_t sys_id
System ID characteristic response data.
Definition: dis_c.h:162
dis_c_disc_srvc_start
sdk_err_t dis_c_disc_srvc_start(uint8_t conn_idx)
Discovery Device Information Service on peer.
DIS_C_PNP_ID
@ DIS_C_PNP_ID
PnP ID characteristic.
Definition: dis_c.h:109
ble_dis_c_read_rsp_t::string_data
dis_c_string_t string_data
Model Number, Serial Number, Hardware Revision, Firmware Revision, Software Revision,...
Definition: dis_c.h:163
dis_c_reg_cert_data_list_t
Response data for IEEE 11073-20601 Regulatory Certification Data List Structure.
Definition: dis_c.h:142
dis_c_reg_cert_data_list_t::p_list
uint8_t * p_list
Pointer to the list which contains the encoded opaque structure based on IEEE 11073-20601 specificati...
Definition: dis_c.h:143
DIS_C_SERIAL_NUM
@ DIS_C_SERIAL_NUM
Serial Number String characteristic.
Definition: dis_c.h:103
dis_c_string_t::length
uint16_t length
Response data length.
Definition: dis_c.h:130
gr55xx_sys.h
GR55XX System API.
dis_c_string_t::p_data
uint8_t * p_data
Pointer to response data.
Definition: dis_c.h:129
dis_c_pnp_id_t::product_id
uint16_t product_id
Product ID.
Definition: dis_c.h:152
DIS_C_FW_REV
@ DIS_C_FW_REV
Firmware Revision String characteristic.
Definition: dis_c.h:105
dis_c_reg_cert_data_list_t::list_length
uint16_t list_length
Length of the list.
Definition: dis_c.h:144
dis_c_pnp_id_t::vendor_id
uint16_t vendor_id
Vendor ID.
Definition: dis_c.h:151
dis_c_evt_type_t
dis_c_evt_type_t
Device Information Service Client event type.
Definition: dis_c.h:91
DIS_C_SYS_ID
@ DIS_C_SYS_ID
System ID characteristic.
Definition: dis_c.h:101
dis_c_pnp_id_t::product_version
uint16_t product_version
Product Version.
Definition: dis_c.h:153
dis_client_init
sdk_err_t dis_client_init(dis_c_evt_handler_t evt_handler)
Register DIS Client event handler.
ble_prf_types.h
Profile/Service Common Types.
dis_c_sys_id_t
Response data for System ID parameters.
Definition: dis_c.h:135
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
DIS_C_MODEL_NUM
@ DIS_C_MODEL_NUM
Model Number String characteristic.
Definition: dis_c.h:102
dis_c_handles_t
Handles on the connected peer device needed to interact with it.
Definition: dis_c.h:120
DIS_C_CERT_LIST
@ DIS_C_CERT_LIST
IEEE 11073-20601 Regulatory Certification Data List characteristic.
Definition: dis_c.h:108
dis_c_pnp_id_t
Response data for PnP ID parameters.
Definition: dis_c.h:149
DIS_C_SW_REV
@ DIS_C_SW_REV
Software Revision String characteristic.
Definition: dis_c.h:106
dis_c_string_t
Response data for string-based DIS characteristics.
Definition: dis_c.h:128
DIS_C_EVT_INVALID
@ DIS_C_EVT_INVALID
DIS Client invalid event.
Definition: dis_c.h:92
dis_c_evt_t::conn_idx
uint8_t conn_idx
The connection index.
Definition: dis_c.h:172
dis_c_handles_t::dis_srvc_start_handle
uint16_t dis_srvc_start_handle
DIS Serivce start handle.
Definition: dis_c.h:121
dis_c_evt_t
Device Information Service Client event.
Definition: dis_c.h:171
DIS_C_CHARACTER_NB
@ DIS_C_CHARACTER_NB
Number of all Device Information Service characteristics.
Definition: dis_c.h:110
DIS_C_HW_REV
@ DIS_C_HW_REV
Hardware Revision String characteristic.
Definition: dis_c.h:104
ble_dis_c_read_rsp_t::cert_list
dis_c_reg_cert_data_list_t cert_list
IEEE 11073-20601 Regulatory Certification Data List characteristic response data.
Definition: dis_c.h:164
ble_dis_c_read_rsp_t::char_type
dis_c_char_type_t char_type
Characteristic type.
Definition: dis_c.h:159
dis_c_handles_t::dis_srvc_end_handle
uint16_t dis_srvc_end_handle
DIS Service end handle.
Definition: dis_c.h:122
dis_c_char_type_t
dis_c_char_type_t
Device Information Service Client characteristic type.
Definition: dis_c.h:100
dis_c_evt_t::read_rsp
ble_dis_c_read_rsp_t read_rsp
DIS Client characteristic Read Response encode.
Definition: dis_c.h:174
dis_c_char_value_read
sdk_err_t dis_c_char_value_read(uint8_t conn_idx, dis_c_char_type_t char_read_type)
Read Device Information Service characteristic value.