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 "gr55xx_sys.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 < CFG_MAX_CONNECTIONS ?\
74  10 : CFG_MAX_CONNECTIONS) /**< Maximum number of DIS connections.
75  The value is configurable. */
76 #define DIS_SYS_ID_LEN 8 /**< System ID length. */
77 #define DIS_PNP_ID_LEN 7 /**< PnP ID length. */
78 #define DIS_VAL_MAX_LEN 128 /**< Maximal length for Characteristic values - 128 bytes. */
79 #define DIS_IEEE_CERTIF_MIN_LEN 6 /**< IEEE Certification length (min 6 bytes). */
80 
81 /**
82  * @defgroup DIS_CHAR_MASK Characteristics Mask
83  * @{
84  * @brief Bit masks for the initialization of \ref dis_init_t.char_mask.
85  */
86 #define DIS_CHAR_SYSTEM_ID_SUP 0x00000006 /**< Bit mask of the System ID. */
87 #define DIS_CHAR_MODEL_NUMBER_SUP 0x00000018 /**< Bit mask of the Model Number. */
88 #define DIS_CHAR_SERIAL_NUMBER_SUP 0x00000060 /**< Bit mask of the Serial Number. */
89 #define DIS_CHAR_FIRMWARE_REV_SUP 0x00000180 /**< Bit mask of the Firmware Revision. */
90 #define DIS_CHAR_HARDWARE_REV_SUP 0x00000600 /**< Bit mask of the Hardware Revision. */
91 #define DIS_CHAR_SOFTWARE_REV_SUP 0x00001800 /**< Bit mask of the Software Revision. */
92 #define DIS_CHAR_MANUFACTURER_NAME_SUP 0x00006000 /**< Bit mask of the Manufacturer Name. */
93 #define DIS_CHAR_11073_CERT_DATA_SUP 0x00018000 /**< Bit mask of the IEEE 11073-20601 Regulatory Certification Data List. */
94 #define DIS_CHAR_PNP_ID_SUP 0x00060000 /**< Bit mask of the PnP ID. */
95 #define DIS_CHAR_FULL 0x0007ffff /**< Bit mask of the full characteristic. */
96 /** @} */
97 
98 /**
99  * @defgroup DIS_IEEE_11073_BODY IEEE 11073-20601 Authoritative Body Type
100  * @{
101  */
102 #define DIS_11073_BODY_EMPTY 0 /**< Empty body type. */
103 #define DIS_11073_BODY_IEEE 1 /**< IEEE body type. */
104 #define DIS_11073_BODY_CONTINUA 2 /**< Continua body type. */
105 #define DIS_11073_BODY_EXP 254 /**< Exp body type. */
106 /** @} */
107 /** @} */
108 
109 /**
110  * @defgroup DIS_STRUCT Structures
111  * @{
112  */
113 /**@brief UTF-8 string data type. */
114 typedef struct
115 {
116  uint8_t length; /**< String length. */
117  char *p_str; /**< String data. */
118 } dis_string_t;
119 
120 /**@brief System ID parameters. The first field is the LSOs and the second
121  * field contains the MSOs. */
122 typedef struct
123 {
124  uint8_t manufacturer_id[5]; /**< Manufacturer-defined ID. */
125  uint8_t org_unique_id[3]; /**< Organizationally unique ID (OUI) which is issued by IEEE. */
126 } dis_sys_id_t;
127 
128 /**@brief IEEE 11073-20601 Regulatory Certification Data List Structure. */
129 typedef struct
130 {
131  char *p_list; /**< Pointer to the list which contains the encoded opaque
132  * structure based on IEEE 11073-20601 specification. */
133  uint8_t list_len; /**< Length of the list. */
135 
136 /**@brief PnP ID parameters */
137 typedef struct
138 {
139  uint8_t vendor_id_source; /**< Vendor ID Source. */
140  uint16_t vendor_id; /**< Vendor ID. */
141  uint16_t product_id; /**< Product ID. */
142  uint16_t product_version; /**< Product Version. */
143 } dis_pnp_id_t;
144 
145 /**@brief Device Information Service init structure. This contains all options
146  * and data needed for initialization of the service. */
147 typedef struct
148 {
149  uint32_t char_mask; /**< Initial mask of Supported characteristics, and configured with \ref DIS_CHAR_MASK. */
150  dis_string_t manufact_name_str; /**< Initial manufacturer Name String. */
151  dis_string_t model_num_str; /**< Initial model Number String. */
152  dis_string_t serial_num_str; /**< Initial serial Number String. */
153  dis_string_t hw_rev_str; /**< Initial hardware Revision String. */
154  dis_string_t fw_rev_str; /**< Initial firmware Revision String. */
155  dis_string_t sw_rev_str; /**< Initial software Revision String. */
156  dis_sys_id_t *p_sys_id; /**< Initial system ID. */
157  dis_reg_cert_data_list_t reg_cert_data_list; /**< Initial IEEE 11073-20601 Regulatory Certification Data List. */
158  dis_pnp_id_t *p_pnp_id; /**< Initial PnP ID. */
159 } dis_init_t;
160 /** @} */
161 
162 /**
163  * @defgroup DIS_FUNCTION Functions
164  * @{
165  */
166 /**
167  *****************************************************************************************
168  * @brief Initialize a Device Information Service instance and add in the database.
169  *
170  * @param[in] p_dis_init: Pointer to Device Information Service initialization variable.
171  *
172  * @return Result of service initialization.
173  *****************************************************************************************
174  */
176 /** @} */
177 
178 #endif
179 /** @} */
180 /** @} */
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:157
dis_sys_id_t
System ID parameters.
Definition: dis.h:123
dis_init_t::model_num_str
dis_string_t model_num_str
Initial model Number String.
Definition: dis.h:151
dis_init_t::manufact_name_str
dis_string_t manufact_name_str
Initial manufacturer Name String.
Definition: dis.h:150
dis_pnp_id_t::vendor_id
uint16_t vendor_id
Vendor ID.
Definition: dis.h:140
dis_init_t::char_mask
uint32_t char_mask
Initial mask of Supported characteristics, and configured with Characteristics Mask.
Definition: dis.h:149
dis_pnp_id_t::product_version
uint16_t product_version
Product Version.
Definition: dis.h:142
dis_init_t::sw_rev_str
dis_string_t sw_rev_str
Initial software Revision String.
Definition: dis.h:155
gr55xx_sys.h
GR55XX System API.
dis_string_t::p_str
char * p_str
String data.
Definition: dis.h:117
dis_reg_cert_data_list_t::list_len
uint8_t list_len
Length of the list.
Definition: dis.h:133
dis_string_t
UTF-8 string data type.
Definition: dis.h:115
dis_pnp_id_t::vendor_id_source
uint8_t vendor_id_source
Vendor ID Source.
Definition: dis.h:139
dis_pnp_id_t::product_id
uint16_t product_id
Product ID.
Definition: dis.h:141
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:243
dis_init_t::serial_num_str
dis_string_t serial_num_str
Initial serial Number String.
Definition: dis.h:152
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:131
dis_pnp_id_t
PnP ID parameters.
Definition: dis.h:138
dis_init_t
Device Information Service init structure.
Definition: dis.h:148
dis_init_t::p_pnp_id
dis_pnp_id_t * p_pnp_id
Initial PnP ID.
Definition: dis.h:158
dis_reg_cert_data_list_t
IEEE 11073-20601 Regulatory Certification Data List Structure.
Definition: dis.h:130
dis_string_t::length
uint8_t length
String length.
Definition: dis.h:116
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:156
dis_init_t::hw_rev_str
dis_string_t hw_rev_str
Initial hardware Revision String.
Definition: dis.h:153
dis_init_t::fw_rev_str
dis_string_t fw_rev_str
Initial firmware Revision String.
Definition: dis.h:154