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. */
96 } dis_c_evt_type_t;
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. */
111 } dis_c_char_type_t;
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. */
124 } dis_c_handles_t;
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. */
131 } dis_c_string_t;
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. */
138 } dis_c_sys_id_t;
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. */
145 } dis_c_reg_cert_data_list_t;
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. */
154 } dis_c_pnp_id_t;
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. */
167 } ble_dis_c_read_rsp_t;
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 */
199 sdk_err_t dis_client_init(dis_c_evt_handler_t evt_handler);
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 */
210 sdk_err_t dis_c_disc_srvc_start(uint8_t conn_idx);
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.