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 "gr_includes.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 /**< Maximum number of DIS Client connections. */
70 #define DIS_C_STRING_LEN_MAX 128 /**< Maximal length for Characteristic values - 128 bytes. */
71
72 /**
73 * @defgroup DIS_IEEE_11073_BODY IEEE 11073-20601 Authoritative Body Type
74 * @{
75 */
76 #define DIS_C_11073_BODY_EMPTY 0 /**< Empty body type. */
77 #define DIS_C_11073_BODY_IEEE 1 /**< IEEE body type. */
78 #define DIS_C_11073_BODY_CONTINUA 2 /**< Continua body type. */
79 #define DIS_C_11073_BODY_EXP 254 /**< Exp body type. */
80 /** @} */
81
82 /** @} */
83
84 /**
85 * @defgroup DIS_C_ENUM Enumerations
86 * @{
87 */
88 /**@brief Device Information Service Client event type. */
89 typedef enum
90 {
91 DIS_C_EVT_INVALID, /**< DIS Client invalid event. */
92 DIS_C_EVT_DISCOVERY_COMPLETE, /**< DIS Client has found Device Information Service and its characteristics. */
93 DIS_C_EVT_DISCOVERY_FAIL, /**< DIS Client found DIS service failed because of invalid operation or no found at the peer. */
94 DIS_C_EVT_DEV_INFORMATION_READ_RSP, /**< DIS Client has received device information value read response. */
95 } dis_c_evt_type_t;
96
97 /**@brief Device Information Service Client characteristic type. */
98 typedef enum
99 {
100 DIS_C_SYS_ID, /**< System ID characteristic. */
101 DIS_C_MODEL_NUM, /**< Model Number String characteristic. */
102 DIS_C_SERIAL_NUM, /**< Serial Number String characteristic. */
103 DIS_C_HW_REV, /**< Hardware Revision String characteristic. */
104 DIS_C_FW_REV, /**< Firmware Revision String characteristic. */
105 DIS_C_SW_REV, /**< Software Revision String characteristic. */
106 DIS_C_MANUF_NAME, /**< Manufacturer Name String characteristic. */
107 DIS_C_CERT_LIST, /**< IEEE 11073-20601 Regulatory Certification Data List characteristic. */
108 DIS_C_PNP_ID, /**< PnP ID characteristic. */
109 DIS_C_CHARACTER_NB /**< Number of all Device Information Service characteristics. */
110 } dis_c_char_type_t;
111 /** @} */
112
113 /**
114 * @defgroup DIS_C_STRUCT Structures
115 * @{
116 */
117 /**@brief Handles on the connected peer device needed to interact with it. */
118 typedef struct
119 {
120 uint16_t dis_srvc_start_handle; /**< DIS Serivce start handle. */
121 uint16_t dis_srvc_end_handle; /**< DIS Service end handle. */
122 uint16_t dis_char_handle[DIS_C_CHARACTER_NB]; /**< DIS characteristic handle. */
123 } dis_c_handles_t;
124
125 /**@brief Response data for string-based DIS characteristics. */
126 typedef struct
127 {
128 uint8_t *p_data; /**< Pointer to response data. */
129 uint16_t length; /**< Response data length. */
130 } dis_c_string_t;
131
132 /**@brief Response data for System ID parameters. */
133 typedef struct
134 {
135 uint8_t manufacturer_id[5]; /**< Manufacturer-defined ID. */
136 uint8_t org_unique_id[3]; /**< Organizationally unique ID (OUI) which is issued by IEEE. */
137 } dis_c_sys_id_t;
138
139 /**@brief Response data for IEEE 11073-20601 Regulatory Certification Data List Structure. */
140 typedef struct
141 {
142 uint8_t *p_list; /**< Pointer to the list which contains the encoded opaque structure based on IEEE 11073-20601 specification. */
143 uint16_t list_length; /**< Length of the list. */
144 } dis_c_reg_cert_data_list_t;
145
146 /**@brief Response data for PnP ID parameters */
147 typedef struct
148 {
149 uint8_t vendor_id_source; /**< Vendor ID Source. */
150 uint16_t vendor_id; /**< Vendor ID. */
151 uint16_t product_id; /**< Product ID. */
152 uint16_t product_version; /**< Product Version. */
153 } dis_c_pnp_id_t;
154
155 /**@brief Device Information Service Client Read Response encode structure. */
156 typedef struct
157 {
158 dis_c_char_type_t char_type; /**< Characteristic type. */
159 union
160 {
161 dis_c_sys_id_t sys_id; /**< System ID characteristic response data. */
162 dis_c_string_t string_data; /**< Model Number, Serial Number, Hardware Revision, Firmware Revision, Software Revision, Manufacturer Name String characteristic response data. */
163 dis_c_reg_cert_data_list_t cert_list; /**< IEEE 11073-20601 Regulatory Certification Data List characteristic response data. */
164 dis_c_pnp_id_t pnp_id; /**< PnP ID characteristic response data. */
165 } encode_rst; /**< Result of encoding. */
166 } ble_dis_c_read_rsp_t;
167
168 /**@brief Device Information Service Client event. */
169 typedef struct
170 {
171 uint8_t conn_idx; /**< The connection index. */
172 dis_c_evt_type_t evt_type; /**< DIS Client event type. */
173 ble_dis_c_read_rsp_t read_rsp; /**< DIS Client characteristic Read Response encode. */
174 } dis_c_evt_t;
175 /** @} */
176
177 /**
178 * @defgroup DIS_C_TYPEDEF Typedefs
179 * @{
180 */
181 /**@brief Device Information Service Client event handler type. */
182 typedef void (*dis_c_evt_handler_t)(dis_c_evt_t *p_evt);
183 /** @} */
184
185 /**
186 * @defgroup DIS_C_FUNCTION Functions
187 * @{
188 */
189 /**
190 *****************************************************************************************
191 * @brief Register DIS Client event handler.
192 *
193 * @param[in] evt_handler: Device Information Service Client event handler.
194 *
195 * @return Result of initialization.
196 *****************************************************************************************
197 */
198 sdk_err_t dis_client_init(dis_c_evt_handler_t evt_handler);
199
200 /**
201 *****************************************************************************************
202 * @brief Discovery Device Information Service on peer.
203 *
204 * @param[in] conn_idx: Index of connection.
205 *
206 * @return Operation result.
207 *****************************************************************************************
208 */
209 sdk_err_t dis_c_disc_srvc_start(uint8_t conn_idx);
210
211 /**
212 *****************************************************************************************
213 * @brief Read Device Information Service characteristic value.
214 *
215 * @param[in] conn_idx: Index of connection.
216 * @param[in] char_read_type: Type of characteristic read.
217 *
218 * @return Operation result.
219 *****************************************************************************************
220 */
221 sdk_err_t dis_c_char_value_read(uint8_t conn_idx, dis_c_char_type_t char_read_type);
222 /** @} */
223
224 #endif
225
226 /** @} */
227 /** @} */
228
DIS_C_EVT_DISCOVERY_COMPLETE
@ DIS_C_EVT_DISCOVERY_COMPLETE
DIS Client has found Device Information Service and its characteristics.
Definition: dis_c.h:92
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:93
ble_dis_c_read_rsp_t
Device Information Service Client Read Response encode structure.
Definition: dis_c.h:157
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:94
ble_dis_c_read_rsp_t::pnp_id
dis_c_pnp_id_t pnp_id
PnP ID characteristic response data.
Definition: dis_c.h:164
DIS_C_MANUF_NAME
@ DIS_C_MANUF_NAME
Manufacturer Name String characteristic.
Definition: dis_c.h:106
dis_c_pnp_id_t::vendor_id_source
uint8_t vendor_id_source
Vendor ID Source.
Definition: dis_c.h:149
dis_c_evt_t::evt_type
dis_c_evt_type_t evt_type
DIS Client event type.
Definition: dis_c.h:172
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:182
ble_dis_c_read_rsp_t::sys_id
dis_c_sys_id_t sys_id
System ID characteristic response data.
Definition: dis_c.h:161
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:108
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:162
dis_c_reg_cert_data_list_t
Response data for IEEE 11073-20601 Regulatory Certification Data List Structure.
Definition: dis_c.h:141
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:142
gr_includes.h
Include Files API.
DIS_C_SERIAL_NUM
@ DIS_C_SERIAL_NUM
Serial Number String characteristic.
Definition: dis_c.h:102
dis_c_string_t::length
uint16_t length
Response data length.
Definition: dis_c.h:129
dis_c_string_t::p_data
uint8_t * p_data
Pointer to response data.
Definition: dis_c.h:128
dis_c_pnp_id_t::product_id
uint16_t product_id
Product ID.
Definition: dis_c.h:151
DIS_C_FW_REV
@ DIS_C_FW_REV
Firmware Revision String characteristic.
Definition: dis_c.h:104
dis_c_reg_cert_data_list_t::list_length
uint16_t list_length
Length of the list.
Definition: dis_c.h:143
dis_c_pnp_id_t::vendor_id
uint16_t vendor_id
Vendor ID.
Definition: dis_c.h:150
dis_c_evt_type_t
dis_c_evt_type_t
Device Information Service Client event type.
Definition: dis_c.h:90
DIS_C_SYS_ID
@ DIS_C_SYS_ID
System ID characteristic.
Definition: dis_c.h:100
dis_c_pnp_id_t::product_version
uint16_t product_version
Product Version.
Definition: dis_c.h:152
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:134
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
DIS_C_MODEL_NUM
@ DIS_C_MODEL_NUM
Model Number String characteristic.
Definition: dis_c.h:101
dis_c_handles_t
Handles on the connected peer device needed to interact with it.
Definition: dis_c.h:119
DIS_C_CERT_LIST
@ DIS_C_CERT_LIST
IEEE 11073-20601 Regulatory Certification Data List characteristic.
Definition: dis_c.h:107
dis_c_pnp_id_t
Response data for PnP ID parameters.
Definition: dis_c.h:148
DIS_C_SW_REV
@ DIS_C_SW_REV
Software Revision String characteristic.
Definition: dis_c.h:105
dis_c_string_t
Response data for string-based DIS characteristics.
Definition: dis_c.h:127
DIS_C_EVT_INVALID
@ DIS_C_EVT_INVALID
DIS Client invalid event.
Definition: dis_c.h:91
dis_c_evt_t::conn_idx
uint8_t conn_idx
The connection index.
Definition: dis_c.h:171
dis_c_handles_t::dis_srvc_start_handle
uint16_t dis_srvc_start_handle
DIS Serivce start handle.
Definition: dis_c.h:120
dis_c_evt_t
Device Information Service Client event.
Definition: dis_c.h:170
DIS_C_CHARACTER_NB
@ DIS_C_CHARACTER_NB
Number of all Device Information Service characteristics.
Definition: dis_c.h:109
DIS_C_HW_REV
@ DIS_C_HW_REV
Hardware Revision String characteristic.
Definition: dis_c.h:103
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:163
ble_dis_c_read_rsp_t::char_type
dis_c_char_type_t char_type
Characteristic type.
Definition: dis_c.h:158
dis_c_handles_t::dis_srvc_end_handle
uint16_t dis_srvc_end_handle
DIS Service end handle.
Definition: dis_c.h:121
dis_c_char_type_t
dis_c_char_type_t
Device Information Service Client characteristic type.
Definition: dis_c.h:99
dis_c_evt_t::read_rsp
ble_dis_c_read_rsp_t read_rsp
DIS Client characteristic Read Response encode.
Definition: dis_c.h:173
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.