tps.h
Go to the documentation of this file.
1 /**
2 *****************************************************************************************
3 *
4 * @file tps.h
5 *
6 * @brief Tx Power 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_TPS Tx Power Service (TPS)
46 * @{
47 * @brief Definitions and prototypes for the TPS interface.
48 *
49 * @details The Tx Power Service uses the Tx Power characteristic to expose a device's current
50 * transmit power level when in connection.
51 *
52 * After \ref tps_init_t variable is initialized, the application must call \ref tps_service_init()
53 * to add Tx Power Service and Tx Power Level characteristic to the BLE Stack database.
54 *
55 * This module also provides \ref tps_tx_power_level_set() function to the
56 * application to update the current value of Tx Power Level characteristic.
57 *
58 */
59
60 #ifndef __TPS_H__
61 #define __TPS_H__
62
63 #include "gr_includes.h"
64 #include "custom_config.h"
65 #include <stdint.h>
66
67 /**
68 * @defgroup TPS_STRUCT Structures
69 * @{
70 */
71 /**@brief Tx Power Servic init stucture. This contains all option and data needed for initialization of the service. */
72 typedef struct
73 {
74 int8_t initial_tx_power_level; /**< Initial value of Tx Power Level characteristic (in dBm) */
75 } tps_init_t;
76 /** @} */
77
78 /**
79 * @defgroup TPS_FUNCTION Functions
80 * @{
81 */
82 /**
83 *****************************************************************************************
84 * @brief Initialize a Tx Power Service instance and add in BLE Stack database.
85 *
86 * @param[in] p_tps_init: Pointer to a Tx Power Service environment variable.
87 *
88 * @return Result of service initialization.
89 *****************************************************************************************
90 */
91 sdk_err_t tps_service_init(tps_init_t *p_tps_init);
92
93 /**
94 *****************************************************************************************
95 * @brief Set new value of Tx power level characteristic.
96 *
97 * @param[in] tx_power_level: New value of Tx power level, range [-100, 20] dBm.
98 *
99 * @return BLE_SDK_SUCCESS on success, otherwise an error code.
100 *****************************************************************************************
101 */
102 sdk_err_t tps_tx_power_level_set(int8_t tx_power_level);
103
104 /**
105 *****************************************************************************************
106 * @brief Provide the interface for other modules to obtain the tps service start handle .
107 *
108 * @return The tps service start handle.
109 *****************************************************************************************
110 */
111 uint16_t tps_service_start_handle_get(void);
112
113 /** @} */
114
115 #endif
116 /** @} */
117 /** @} */
tps_init_t
Tx Power Servic init stucture.
Definition: tps.h:73
tps_init_t::initial_tx_power_level
int8_t initial_tx_power_level
Initial value of Tx Power Level characteristic (in dBm)
Definition: tps.h:74
gr_includes.h
Include Files API.
tps_service_init
sdk_err_t tps_service_init(tps_init_t *p_tps_init)
Initialize a Tx Power Service instance and add in BLE Stack database.
tps_service_start_handle_get
uint16_t tps_service_start_handle_get(void)
Provide the interface for other modules to obtain the tps service start handle .
sdk_err_t
uint16_t sdk_err_t
SDK API result type.
Definition: ble_error.h:273
tps_tx_power_level_set
sdk_err_t tps_tx_power_level_set(int8_t tx_power_level)
Set new value of Tx power level characteristic.