dis.h
Go to the documentation of this file.
1 /**
2  *****************************************************************************************
3  *
4  * @file dis.h
5  *
6  * @brief Device Information Service API.
7  *
8  *****************************************************************************************
9  * @attention
10  #####Copyright (c) 2019 GOODIX
11  All rights reserved.
12 
13  Redistribution and use in source and binary forms, with or without
14  modification, are permitted provided that the following conditions are met:
15  * Redistributions of source code must retain the above copyright
16  notice, this list of conditions and the following disclaimer.
17  * Redistributions in binary form must reproduce the above copyright
18  notice, this list of conditions and the following disclaimer in the
19  documentation and/or other materials provided with the distribution.
20  * Neither the name of GOODIX nor the names of its contributors may be used
21  to endorse or promote products derived from this software without
22  specific prior written permission.
23 
24  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27  ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDERS AND CONTRIBUTORS BE
28  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34  POSSIBILITY OF SUCH DAMAGE.
35  *****************************************************************************************
36  */
37 
38 /**
39  * @addtogroup BLE_SRV BLE Services
40  * @{
41  * @brief Definitions and prototypes for the BLE Service interface.
42  */
43 
44 /**
45  * @defgroup BLE_SDK_DIS Device Information Service (DIS)
46  * @{
47  * @brief Definitions and prototypes for the DIS interface.
48  *
49  * @details The Device Information Service exposes manufacturer and/or vendor information
50  * about a device.This module implements the Device Information Service with all
51  * optional characteristics.
52  *
53  * After \ref dis_init_t variable is initialized, the application should call
54  * \ref dis_service_init() to add a Device Information Service and the characteristics
55  * which are selected by \ref dis_init_t.char_mask to the BLE Stack database.
56  * However the value of those characteristics locates in user space. The application
57  * should make sure the spaces for those values are available and those values will not be
58  * changed during the connection.
59  *
60  */
61 
62 #ifndef __DIS_H__
63 #define __DIS_H__
64 
65 #include "gr_includes.h"
66 #include "custom_config.h"
67 #include <stdint.h>
68 
69 /**
70  * @defgroup DIS_MACRO Defines
71  * @{
72  */
73 #define DIS_CONNECTION_MAX 10 /**< Maximum number of DIS connections.The value is configurable. */
74 #define DIS_SYS_ID_LEN 8 /**< System ID length. */
75 #define DIS_PNP_ID_LEN 7 /**< PnP ID length. */
76 #define DIS_VAL_MAX_LEN 128 /**< Maximal length for Characteristic values - 128 bytes. */
77 #define DIS_IEEE_CERTIF_MIN_LEN 6 /**< IEEE Certification length (min 6 bytes). */
78 
79 /**
80  * @defgroup DIS_CHAR_MASK Characteristics Mask
81  * @{
82  * @brief Bit masks for the initialization of \ref dis_init_t.char_mask.
83  */
84 #define DIS_CHAR_SYSTEM_ID_SUP 0x00000006 /**< Bit mask of the System ID. */
85 #define DIS_CHAR_MODEL_NUMBER_SUP 0x00000018 /**< Bit mask of the Model Number. */
86 #define DIS_CHAR_SERIAL_NUMBER_SUP 0x00000060 /**< Bit mask of the Serial Number. */
87 #define DIS_CHAR_FIRMWARE_REV_SUP 0x00000180 /**< Bit mask of the Firmware Revision. */
88 #define DIS_CHAR_HARDWARE_REV_SUP 0x00000600 /**< Bit mask of the Hardware Revision. */
89 #define DIS_CHAR_SOFTWARE_REV_SUP 0x00001800 /**< Bit mask of the Software Revision. */
90 #define DIS_CHAR_MANUFACTURER_NAME_SUP 0x00006000 /**< Bit mask of the Manufacturer Name. */
91 #define DIS_CHAR_11073_CERT_DATA_SUP 0x00018000 /**< Bit mask of the IEEE 11073-20601 Regulatory Certification Data List. */
92 #define DIS_CHAR_PNP_ID_SUP 0x00060000 /**< Bit mask of the PnP ID. */
93 #define DIS_CHAR_FULL 0x0007ffff /**< Bit mask of the full characteristic. */
94 /** @} */
95 
96 /**
97  * @defgroup DIS_IEEE_11073_BODY IEEE 11073-20601 Authoritative Body Type
98  * @{
99  */
100 #define DIS_11073_BODY_EMPTY 0 /**< Empty body type. */
101 #define DIS_11073_BODY_IEEE 1 /**< IEEE body type. */
102 #define DIS_11073_BODY_CONTINUA 2 /**< Continua body type. */
103 #define DIS_11073_BODY_EXP 254 /**< Exp body type. */
104 /** @} */
105 /** @} */
106 
107 /**
108  * @defgroup DIS_STRUCT Structures
109  * @{
110  */
111 /**@brief UTF-8 string data type. */
112 typedef struct
113 {
114  uint8_t length; /**< String length. */
115  char *p_str; /**< String data. */
116 } dis_string_t;
117 
118 /**@brief System ID parameters. The first field is the LSOs and the second
119  * field contains the MSOs. */
120 typedef struct
121 {
122  uint8_t manufacturer_id[5]; /**< Manufacturer-defined ID. */
123  uint8_t org_unique_id[3]; /**< Organizationally unique ID (OUI) which is issued by IEEE. */
124 } dis_sys_id_t;
125 
126 /**@brief IEEE 11073-20601 Regulatory Certification Data List Structure. */
127 typedef struct
128 {
129  char *p_list; /**< Pointer to the list which contains the encoded opaque
130  * structure based on IEEE 11073-20601 specification. */
131  uint8_t list_len; /**< Length of the list. */
133 
134 /**@brief PnP ID parameters */
135 typedef struct
136 {
137  uint8_t vendor_id_source; /**< Vendor ID Source. */
138  uint16_t vendor_id; /**< Vendor ID. */
139  uint16_t product_id; /**< Product ID. */
140  uint16_t product_version; /**< Product Version. */
141 } dis_pnp_id_t;
142 
143 /**@brief Device Information Service init structure. This contains all options
144  * and data needed for initialization of the service. */
145 typedef struct
146 {
147  uint32_t char_mask; /**< Initial mask of Supported characteristics, and configured with \ref DIS_CHAR_MASK. */
148  dis_string_t manufact_name_str; /**< Initial manufacturer Name String. */
149  dis_string_t model_num_str; /**< Initial model Number String. */
150  dis_string_t serial_num_str; /**< Initial serial Number String. */
151  dis_string_t hw_rev_str; /**< Initial hardware Revision String. */
152  dis_string_t fw_rev_str; /**< Initial firmware Revision String. */
153  dis_string_t sw_rev_str; /**< Initial software Revision String. */
154  dis_sys_id_t *p_sys_id; /**< Initial system ID. */
155  dis_reg_cert_data_list_t reg_cert_data_list; /**< Initial IEEE 11073-20601 Regulatory Certification Data List. */
156  dis_pnp_id_t *p_pnp_id; /**< Initial PnP ID. */
157 } dis_init_t;
158 /** @} */
159 
160 /**
161  * @defgroup DIS_FUNCTION Functions
162  * @{
163  */
164 /**
165  *****************************************************************************************
166  * @brief Initialize a Device Information Service instance and add in the database.
167  *
168  * @param[in] p_dis_init: Pointer to Device Information Service initialization variable.
169  *
170  * @return Result of service initialization.
171  *****************************************************************************************
172  */
174 
175 /**
176  *****************************************************************************************
177  * @brief Provide the interface for other modules to obtain the dis service start handle .
178  *
179  * @return The dis service start handle.
180  *****************************************************************************************
181  */
183 
184 /** @} */
185 
186 #endif
187 /** @} */
188 /** @} */
dis_init_t::reg_cert_data_list
dis_reg_cert_data_list_t reg_cert_data_list
Initial IEEE 11073-20601 Regulatory Certification Data List.
Definition: dis.h:155
dis_sys_id_t
System ID parameters.
Definition: dis.h:121
dis_init_t::model_num_str
dis_string_t model_num_str
Initial model Number String.
Definition: dis.h:149
dis_init_t::manufact_name_str
dis_string_t manufact_name_str
Initial manufacturer Name String.
Definition: dis.h:148
dis_pnp_id_t::vendor_id
uint16_t vendor_id
Vendor ID.
Definition: dis.h:138
dis_init_t::char_mask
uint32_t char_mask
Initial mask of Supported characteristics, and configured with Characteristics Mask.
Definition: dis.h:147
dis_pnp_id_t::product_version
uint16_t product_version
Product Version.
Definition: dis.h:140
gr_includes.h
Include Files API.
dis_init_t::sw_rev_str
dis_string_t sw_rev_str
Initial software Revision String.
Definition: dis.h:153
dis_string_t::p_str
char * p_str
String data.
Definition: dis.h:115
dis_reg_cert_data_list_t::list_len
uint8_t list_len
Length of the list.
Definition: dis.h:131
dis_string_t
UTF-8 string data type.
Definition: dis.h:113
dis_pnp_id_t::vendor_id_source
uint8_t vendor_id_source
Vendor ID Source.
Definition: dis.h:137
dis_pnp_id_t::product_id
uint16_t product_id
Product ID.
Definition: dis.h:139
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
dis_init_t::serial_num_str
dis_string_t serial_num_str
Initial serial Number String.
Definition: dis.h:150
dis_reg_cert_data_list_t::p_list
char * p_list
Pointer to the list which contains the encoded opaque structure based on IEEE 11073-20601 specificati...
Definition: dis.h:129
dis_service_start_handle_get
uint16_t dis_service_start_handle_get(void)
Provide the interface for other modules to obtain the dis service start handle .
dis_pnp_id_t
PnP ID parameters.
Definition: dis.h:136
dis_init_t
Device Information Service init structure.
Definition: dis.h:146
dis_init_t::p_pnp_id
dis_pnp_id_t * p_pnp_id
Initial PnP ID.
Definition: dis.h:156
dis_reg_cert_data_list_t
IEEE 11073-20601 Regulatory Certification Data List Structure.
Definition: dis.h:128
dis_string_t::length
uint8_t length
String length.
Definition: dis.h:114
dis_service_init
sdk_err_t dis_service_init(dis_init_t *p_dis_init)
Initialize a Device Information Service instance and add in the database.
dis_init_t::p_sys_id
dis_sys_id_t * p_sys_id
Initial system ID.
Definition: dis.h:154
dis_init_t::hw_rev_str
dis_string_t hw_rev_str
Initial hardware Revision String.
Definition: dis.h:151
dis_init_t::fw_rev_str
dis_string_t fw_rev_str
Initial firmware Revision String.
Definition: dis.h:152